Problem/Motivation

Drupal 8's @covers and @coversDefaultClass annotations are a mess.

This issue fixes them as they exist now.

Using the patch in #2415441: Automate finding @covers errors one could spend a couple hours fixing all the obvious @covers and @coversDefaultClass errors.

Proposed resolution

Remaining tasks

User interface changes

API changes

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category Bug because the problem prevents generating a coverage report, and also is wrong documentation.
Unfrozen changes Unfrozen because it improves documentation and automated tests, and only changes docblocks.
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Mile23’s picture

Status: Active » Needs review
FileSize
31.4 KB

Not much to say really, other than I wiped it out by accident so it took twice as long.

This does not add missing @covers but fixes existing ones.

Mile23’s picture

Issue summary: View changes

Added beta evaluation.

daffie’s picture

Status: Needs review » Needs work
+++ b/core/modules/views/tests/src/Unit/PluginBaseTest.php
@@ -46,9 +46,8 @@ protected function setUp() {
    *   Whether to unpack all options.
    *

@@ -289,6 +287,7 @@ public function providerTestSetOptionDefault() {
    * Tests filterByDefinedOptions().
    *

+++ b/core/modules/views/tests/src/Unit/ViewExecutableUnitTest.php
@@ -119,7 +119,7 @@ public function testBuildThemeFunctions() {
    * Tests the generateHandlerId method().
    *

@@ -131,7 +131,7 @@ public function testGenerateHandlerId() {
    * Tests the addHandler method().
    *

@@ -217,7 +217,7 @@ public function testAddHandlerWithEntityField() {
    * Tests attachDisplays().
    *

+++ b/core/tests/Drupal/Tests/Component/Plugin/PluginBaseTest.php
@@ -19,9 +19,7 @@ class PluginBaseTest extends UnitTestCase {
    * Tests the getPluginId method.
    *

@@ -49,8 +47,7 @@ public function providerTestGetPluginId() {
    * Tests the getBaseId method.
    *

@@ -80,8 +77,7 @@ public function providerTestGetBaseId() {
    * Tests the getDerivativeId method.
    *

@@ -109,7 +105,7 @@ public function providerTestGetDerivativeId() {
    * Tests the getPluginDefinition method.
    *

+++ b/core/tests/Drupal/Tests/Core/Batch/PercentagesTest.php
@@ -24,8 +24,7 @@ class PercentagesTest extends UnitTestCase {
    * Tests the format() function.
    *

+++ b/core/tests/Drupal/Tests/Core/DrupalKernel/ValidateHostnameTest.php
@@ -20,7 +20,7 @@ class ValidateHostnameTest extends UnitTestCase {
    * Tests hostname validation.
    *

+++ b/core/tests/Drupal/Tests/Core/Menu/LocalTaskDefaultTest.php
@@ -217,8 +219,7 @@ public function providerTestGetWeight() {
    * Tests the getWeight method.
    *

@@ -231,8 +232,8 @@ public function testGetWeight($plugin_definition, $plugin_id, $expected_weight)
    * Tests getActive/setActive() method.
    *

@@ -294,7 +297,7 @@ public function testGetTitleWithTitleArguments() {
    * Tests the getOption method.
    *

I think that these lines can be removed.

+++ b/core/tests/Drupal/Tests/Core/Routing/RouteMatchTest.php
@@ -30,7 +30,6 @@ protected function getRouteMatch($name, Route $route, array $parameters, array $
-   * @covers \Drupal\Core\Routing\NullRouteMatch

I am not sure what to do with this line. We are also testing this other class. Can we change @covers to @see? @Mile23: If you have a better idea please let me know.

Mile23’s picture

Status: Needs work » Needs review
FileSize
31.97 KB
7.03 KB

As always, thanks for the review. :-)

@Mile23: If you have a better idea please let me know.

Well, I did make the patch you're reviewing. :-)

testRouteMatchFromRequest() doesn't actually test NullRouteMatch. It tests whether RouteMatch::createFromRequest() returns a match that has a bunch of null values, and then goes on to find out what testRouteMatchFromRequest() returns in other circumstances.

Also, you can't @cover a class. :-)

NullRouteMatch itself doesn't look like it needs much unit testing.

Regarding all the ones like this: * Tests the getOption method., I just wanted to limit scope for this patch. But you're correct: Those lines are just more stuff to maintain. I did a more careful read-through of the files you mentioned and changed them.

Also, #2413941: BubbleableMetadataTest::testApply has wrong @covers got in, so it needed a mini-reroll.

daffie’s picture

Status: Needs review » Reviewed & tested by the community

Good work Mile23! And thanks for explaining the NullRouteMatch testing.

Looks all good to me.
The documentation is a lot better for unittesting.
There are also two function which are renamed. Both are test-functions and they are allowed for beta-changes.
So it gets a RTBC from me.

daffie’s picture

#2409587: Incorrect documentation for @covers has landed. Starting a re-test to see if there are any problems.

daffie queued 4: 2418237_4.patch for re-testing.

Mile23’s picture

Thanks, @daffie.

Looks like the patch applies so it doesn't need a re-roll. I think #2409587: Incorrect documentation for @covers deals with @covers that aren't wrong but didn't use the @coversDefaultClass/@covers pattern that is our standard. This patch checks for bad syntax and references to non-existent classes and/or methods.

neclimdul’s picture

Assigned: Unassigned » neclimdul
Status: Reviewed & tested by the community » Needs work

If so, then its broken again because I couldn't run coverage tests. Working on it.

neclimdul’s picture

Assigned: neclimdul » Unassigned
Status: Needs work » Needs review
FileSize
35.03 KB
3.06 KB

Interdiff is fairly self explanatory. Trickiest one is the routematch base test which was claiming to cover methods that only exist on the routematch, not methods publicly on the interface which is what its used for. Clarified the test documentation and removed the coverage. If we want to test that method we can put something in the routematch test explicitly.

neclimdul’s picture

FileSize
35.28 KB
1.79 KB

Actually #2409587: Incorrect documentation for @covers is what broke the base test. We can just revert those changes.

Mile23’s picture

Yah, that's what I found, too. Still generating a coverage report as a check, but I'm pretty sure that's right.

We really shouldn't have abstract base classes with executable tests in them that claim to cover code, because if for whatever reason we remove the subclasses, those tests silently cease to cover anything.

Update: Success on generating a coverage report, so yay.

Mile23’s picture

Still applies, nothing new to fix according to #2415441: Automate finding @covers errors.

daffie’s picture

Status: Needs review » Needs work
  1. +++ b/core/tests/Drupal/Tests/Core/Menu/ContextualLinkDefaultTest.php
    @@ -16,6 +16,7 @@
      * Tests the contextual link default class.
      *
    

    These lines can be removed.

  2. +++ b/core/tests/Drupal/Tests/Core/Routing/RouteMatchBaseTest.php
    @@ -15,7 +15,7 @@
    - * Base test class for testing the RouteMatch object.
    + * Base test class for testing classes implementing the route match interface.
    
    @@ -102,7 +102,7 @@ public function testGetRouteObject(RouteMatchInterface $route_match, Route $rout
        * @covers ::getParameter
    
    @@ -116,7 +116,7 @@ public function testGetParameter(RouteMatchInterface $route_match, Route $route,
        * @covers ::getParameters
    
    @@ -125,7 +125,7 @@ public function testGetParameters(RouteMatchInterface $route_match, Route $route
        * @covers ::getRawParameter
    
    @@ -139,7 +139,7 @@ public function testGetRawParameter(RouteMatchInterface $route_match, Route $rou
        * @covers ::getRawParameters
    

    Should we not use @coversDefaultClass for this. We have @covers in this class without a class reference. From which class are these methods?

Mile23’s picture

Status: Needs work » Needs review
FileSize
37.18 KB
2.36 KB

Thanks for the review, @daffie.

See the discussion of RouteMatchBaseTest in #11 and #12. It uses @covers on an abstract base class, so that concrete subclasses inherit the coverage, applied to their own @coverageDefaultClass. Changing that would be a bit out of scope for this issue.

Fixed the docblocks in ContextualLinkDefaultTest, and found a few more to change while I was looking at it.

neclimdul’s picture

FileSize
37.18 KB

Needed a re-roll after #2422019: Don't use reflection for parsing test annotations. No changes, just resolved a merge conflict because it added some annotations to some tests. Seems like we could probably RTBC this and just move forward? This fixes the issue of coverage being broken and any cleanups can come later.

Status: Needs review » Needs work

The last submitted patch, 16: 2418237-covers-fixes-16.patch, failed testing.

Status: Needs work » Needs review
daffie’s picture

Status: Needs review » Needs work

For me it is almost RTBC. I have only two nitpicks left:

  1. +++ b/core/tests/Drupal/Tests/Core/Config/Entity/EntityDisplayBaseTest.php
    @@ -50,7 +50,7 @@ public function testGetOriginalMode() {
    -   * @covers ::getDisplayBundle()
    +   * @covers ::getTargetBundle
    ...
       public function testGetDisplayBundle() {
    
    @@ -61,7 +61,7 @@ public function testGetDisplayBundle() {
    -   * @covers ::setDisplayBundle()
    +   * @covers ::setTargetBundle
    ...
       public function testSetDisplayBundle() {
    

    Can we also rename the test functions.

  2. +++ b/core/tests/Drupal/Tests/Core/Plugin/Discovery/ContainerDerivativeDiscoveryDecoratorTest.php
    @@ -17,7 +17,7 @@
        *
        * @see \Drupal\Core\Plugin\Discovery\ContainerDerivativeDiscoveryDecorator::getDerivativeFetcher().
    

    These lines can be removed.

Mile23’s picture

Status: Needs work » Needs review
FileSize
37.79 KB
2.07 KB

Nice catches.

daffie’s picture

Status: Needs review » Reviewed & tested by the community

It all looks good to me.
It is all about documentation about tests and some renaming of tests. So no problem with beta changes.
It is RTBC for me.

neclimdul’s picture

Status: Reviewed & tested by the community » Needs review
FileSize
37.82 KB

I'd say this was a straight re-roll but it was actually sort of an ugly merge conflict. It was mostly just a bunch of tests getting added above one of our chunks but because of that I'm going to mark it back NR just so someone can give it a once over and make sure I didn't miss anything.

Cause: #2409209: Replace all _url() calls beside the one in _l()

Conflicts:
core/modules/views/tests/src/Unit/ViewExecutableTest.php

daffie’s picture

@neclimdul: Can you add an interdiff.txt file. It helps with reviewing.

daffie’s picture

Status: Needs review » Reviewed & tested by the community

It all looks good to me. Again.
It is all about documentation about tests and some renaming of tests. So no problem with beta changes.
It is RTBC for me.

neclimdul’s picture

Resolving conflicts like this I apply the patch at the last working commit and then merge(https://gist.github.com/neclimdul/d611b5033c6d302fab7e). You can't really interdiff a merge though, you get all of the changes you are merging and not anything useful for review. Sorry.

Thanks for taking the time to review it!

jhodgdon’s picture

Component: documentation » phpunit

I'm changing the component. Although this is technically documentation, it seems like the test scripts use this?

Mile23’s picture

Component: phpunit » documentation

None of the Drupal CI test scripts use @covers, though it'd be great to add that: #2415441: Automate finding @covers errors

We are using @covers and @coversDefaultClass for both documentation and coverage annotation for phpunit, but documentation is the main use in Drupal-land.

Mile23’s picture

Issue tags: +Needs reroll

Boo and yay. :-)

neclimdul’s picture

FileSize
37.82 KB

Happily. No changes again so no change in status.

neclimdul’s picture

Issue tags: -Needs reroll
jyotisankar’s picture

Status: Reviewed & tested by the community » Needs review
Issue tags: +Needs Review
FileSize
37.85 KB
tim.plunkett’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community
Issue tags: -Needs Review

@jyotisankar are you trolling for commit credit?

#31 is wrong, #29 is the patch to commit.

Suggested commit credit:

Issue #2418237 by Mile23, neclimdul: The Mother Of All @covers Issues
tim.plunkett’s picture

Issue summary: View changes
neclimdul’s picture

Based on the comment number in the patch name and the fact out patches are the same with different metadata it looks like it was an honest mistake and a x-post.

A reminder its a good idea to refresh before posting a patch if you didn't assign it to yourself :-D

alexpott’s picture

Title: The Mother Of All @covers Issues » Fix incorrect @covers in PHPUnit tests
Issue summary: View changes
Status: Reviewed & tested by the community » Fixed

Due #34 I've given @jyotisankar a commit credit. I've committed the patch in #29 due to the fact that

diff --git a/core/modules/views/tests/src/Unit/ViewExecutableTest.php b/core/modules/views/tests/src/Unit/ViewExecutableTest.php
old mode 100644
new mode 100755

Documentation is not frozen in beta. Committed 0bab86f and pushed to 8.0.x. Thanks!

  • alexpott committed 0bab86f on 8.0.x
    Issue #2418237 by Mile23, neclimdul, jyotisankar: Fix incorrect @covers...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.