Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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
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. |
Comment | File | Size | Author |
---|---|---|---|
#22 | 2418237_22.patch | 37.82 KB | neclimdul |
Comments
Comment #1
Mile23Not 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.
Comment #2
Mile23Added beta evaluation.
Comment #3
daffie CreditAttribution: daffie commentedI think that these lines can be removed.
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.
Comment #4
Mile23As always, thanks for the review. :-)
Well, I did make the patch you're reviewing. :-)
testRouteMatchFromRequest()
doesn't actually testNullRouteMatch
. It tests whetherRouteMatch::createFromRequest()
returns a match that has a bunch of null values, and then goes on to find out whattestRouteMatchFromRequest()
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.
Comment #5
daffie CreditAttribution: daffie commentedGood 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.
Comment #6
daffie CreditAttribution: daffie commented#2409587: Incorrect documentation for @covers has landed. Starting a re-test to see if there are any problems.
Comment #8
Mile23Thanks, @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.
Comment #9
neclimdulIf so, then its broken again because I couldn't run coverage tests. Working on it.
Comment #10
neclimdulInterdiff 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.
Comment #11
neclimdulActually #2409587: Incorrect documentation for @covers is what broke the base test. We can just revert those changes.
Comment #12
Mile23Yah, 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.
Comment #13
Mile23Still applies, nothing new to fix according to #2415441: Automate finding @covers errors.
Comment #14
daffie CreditAttribution: daffie commentedThese lines can be removed.
Should we not use @coversDefaultClass for this. We have @covers in this class without a class reference. From which class are these methods?
Comment #15
Mile23Thanks 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.Comment #16
neclimdulNeeded 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.
Comment #19
daffie CreditAttribution: daffie commentedFor me it is almost RTBC. I have only two nitpicks left:
Can we also rename the test functions.
These lines can be removed.
Comment #20
Mile23Nice catches.
Comment #21
daffie CreditAttribution: daffie commentedIt 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.
Comment #22
neclimdulI'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
Comment #23
daffie CreditAttribution: daffie commented@neclimdul: Can you add an interdiff.txt file. It helps with reviewing.
Comment #24
daffie CreditAttribution: daffie commentedIt 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.
Comment #25
neclimdulResolving 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!
Comment #26
jhodgdonI'm changing the component. Although this is technically documentation, it seems like the test scripts use this?
Comment #27
Mile23None of the Drupal CI test scripts use
@covers
, though it'd be great to add that: #2415441: Automate finding @covers errorsWe are using
@covers
and@coversDefaultClass
for both documentation and coverage annotation for phpunit, but documentation is the main use in Drupal-land.Comment #28
Mile23Boo and yay. :-)
Comment #29
neclimdulHappily. No changes again so no change in status.
Comment #30
neclimdulComment #31
jyotisankar CreditAttribution: jyotisankar commentedComment #32
tim.plunkett@jyotisankar are you trolling for commit credit?
#31 is wrong, #29 is the patch to commit.
Suggested commit credit:
Comment #33
tim.plunkettComment #34
neclimdulBased 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
Comment #35
alexpottDue #34 I've given @jyotisankar a commit credit. I've committed the patch in #29 due to the fact that
Documentation is not frozen in beta. Committed 0bab86f and pushed to 8.0.x. Thanks!