[wp-trac] [WordPress Trac] #39265: Missing @covers in the comment blocks in PHPUnit tests

[WordPress Trac]

#39265: Missing @covers in the comment blocks in PHPUnit tests
------------------------------+-----------------------------
 Reporter:  pbearne           |       Owner:  SergeyBiryukov
     Type:  task (blessed)    |      Status:  accepted
 Priority:  normal            |   Milestone:  5.8
Component:  Build/Test Tools  |     Version:  4.8
 Severity:  normal            |  Resolution:
 Keywords:  php8              |     Focuses:
------------------------------+-----------------------------

Comment (by jrf):

 I've just uploaded a patch to fix some more `@covers` tags which are
 already in the code base, probably introduced some time over the last few
 months.


 I've also done a review of the new patches which were uploaded, similar to
 my earlier review in
 https://core.trac.wordpress.org/ticket/39265#comment:24.

 Thanks everyone for your perseverance and continued work on this ticket!


 == `actions+admin.diff`

 @hudson-atwell

 * Mostly looking good.
 * `.gitignore`: that change does not belong in this patch. Excluded IDE
 specific files/directories should be done at the user level via
 `.git/info/exclude`, not at the project level.
 * `tests/phpunit/tests/admin/includesScreen.php`: line 300 and below - the
 `@covers` tags refer to a non-existent class. The
 [https://developer.wordpress.org/reference/functions/get_current_screen/
 `get_current_screen()`] method returns a `WP_Screen` object, so the method
 calls, like `$screen->add_help_tab()` call the method from the `WP_Screen`
 class. The `@covers` tags need to be fixed to reflect that, so `@covers
 get_current_screen::add_help_tab` should be: `@covers
 WP_Screen::add_help_tab`.
 * `tests/phpunit/tests/admin/includesTheme.php`: line 179, same as above.
 The [https://developer.wordpress.org/reference/functions/wp_get_theme/
 `wp_get_theme()`] method retrieves a `WP_Theme` object, so the covers tag
 should be `@covers WP_Theme::get_post_templates`.
 * `tests/phpunit/tests/admin/includesListTable.php`: this file seems to
 exist three times in the patch. The `@covers class::WP_Posts_List_Table`
 tags are incorrect, so the patches for this file will need to be combined
 to get the correct patch.

 == `formatting.patch​`

 @pbearne

 * `@covers` syntax is correct.
 * `tests/phpunit/tests/formatting/Autop.php`: The `@covers` tags seem to
 refer to a non-existent function `autop` ? I think these should probably
 all be `@covers ::wpautop`. And if there are only tests for that one
 function in the file, adding just one `@covers` tag at the class docblock
 level instead of adding the tag to each individual method, is fine.
 * `tests/phpunit/tests/formatting/balanceTags.php` (and most, though not
 all, of the other files too): similar to the previous comment - one
 `@covers` tag at the class docblock level would be sufficient here as all
 tests in this test class seem to be for the one WP function.
 * `tests/phpunit/tests/formatting/EscUrl.php`,
 `tests/phpunit/tests/formatting/EscXml.php` - stray blank lines at the
 start of the docblocks need to be removed.
 * `tests/phpunit/tests/formatting/SanitizeTitleWithDashes.php`: nice catch
 on the mistake in the `test_strips_html()` test.

 == `I_folders.patch​`

 @pbearne

 All looks good. No real remarks. Some tags could probably be done at class
 docblock level, but the patch will work as is.

 == `o_folders.patch`

 @patopaiar

 All looks good. There are some stray `@uses` tags which shouldn't really
 be needed, but don't do any harm either, so all good.

 == `m-folders.patch`

 @pbearne

 All looks good. Just one tiny nitpick:
 - `tests/phpunit/tests/multisite/networkQuery.php` - indentation of the
 docblock is off round line 124

 == `p-folders.patch`

 @pbearne

 Mostly looking good. Just a few small remarks:
 * `tests/phpunit/tests/post/filtering.php`: line 72 - blank line between
 docblock and function declaration which should be removed.
 * `tests/phpunit/tests/post/filtering.php`: line 116 - stray blank
 docblock line which should be removed.
 * `tests/phpunit/tests/post/wpInsertPost.php`: line 81 - I think the
 function call got accidentally removed here, which would break the test.
 * `tests/phpunit/tests/post/wpPublishPost.php`: line 48, 68, 89, 124:
 there must be a blank docblock line between the function description and
 the first tag.


 == `q-folder.patch`

 @pbearne

 This patch needs a do-over.

 The patch uses the `@coversDefaultClass` annotation at the class level,
 but there are no `@covers` tags for the individual tests. The
 `@coversDefaultClass` annotation is a way to prevent having to repeat the
 same class name over and over in the `@covers` tags used for the
 individual test methods in the test class, but should only be used in
 conjunction with `@covers` tags at the method level.
 See the documentation for
 [https://phpunit.readthedocs.io/en/9.5/annotations.html#coversdefaultclass
 @coversDefaultClass].
 I think @pbearne probably intended to use the `@covers` at class level for
 these tests and that would have been perfectly fine.

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