[wp-trac] [WordPress Trac] #39265: Missing @covers and @uses in the comments block in phpunt test for wordpress

[WordPress Trac]

#39265: Missing @covers and @uses in the comments block in phpunt test for
wordpress
------------------------------+---------------------
 Reporter:  pbearne           |       Owner:  (none)
     Type:  enhancement       |      Status:  new
 Priority:  normal            |   Milestone:  5.6
Component:  Build/Test Tools  |     Version:  4.8
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:
------------------------------+---------------------
Changes (by jrf):

 * milestone:  Awaiting Review => 5.6


Comment:

 I'd highly recommend for this ticket to be revisited for WP 5.6.

 As explained in more detail in #50902, there are significant changes in
 PHP 8.0 which we will only be able to detect breakage from via unit tests.

 Knowing which code is not, or insufficiently, covered by tests will allow
 a more focused approach for expanding the test suite to ensure
 compatibility with PHP 8.0.

 ----

 Regarding the use of the `@covers` tags, reading the above discussion
 there seems to be some confusion about what that tag does and why it is so
 extremely useful (and important!), so let me try and explain it:

 Let's take a unit test which is set up to test function `foo()`. Function
 `foo()` calls the functions `bar()` and `baz()` under the hood as part of
 its logic.

 Now when running a code-coverage report, you will see that code coverage
 is recorded for function `foo()`, `bar()` and `baz()`, while in reality we
 were only testing function `foo()`.
 This is called ''incidental code coverage'' - covering code in
 functions/classes/methods which are **not** explicitly being tested. It is
 basically a ''false positive'' for which code is covered by a test.

 With incidental code coverage, it is easy to think your code base has a
 high test coverage, while in reality there are no dedicated tests for a
 lot of the code.

 In comes the `@covers` tag. The `@covers` tag ensures that only the code
 from the functions/methods/classes listed in `@covers` tag will be
 regarded as being covered by a specific test.
 So, when we add a `@covers ::foo` tag to the test from the example and run
 code coverage again, we will see that code coverage has only been recorded
 for the code from the `foo()` function and that the `bar()` and `baz()`
 functions have 0% code coverage.

 Once `@covers` tags have been added to all tests, the next step would be
 to add the `forceCoversAnnotation=true` setting in the `phpunit.xml.dist`
 configuration file. With that setting turned on, code coverage will only
 be recorded if a test has a `@covers` annotation. This effectively
 prevents incidental code coverage from entering the code coverage reports
 as only the code covered by tests with a `@covers` tag will be included.

 Also note: The tests don't all have to have individual `@covers` tags. If
 a test class, through a variety of tests,  covers all aspect of one
 particular function, a single `@covers` tag for that function in the test
 class docblock will suffice. Same if a test class covers every aspect of a
 class. A single `@covers` tag referencing the covered class in the test
 class docblock is enough in that case.

 For more information, have a look at:
 https://phpunit.readthedocs.io/en/7.5/annotations.html#covers and
 https://phpunit.readthedocs.io/en/7.5/code-coverage-analysis.html
 #specifying-covered-code-parts

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/39265#comment:7>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform