[wp-trac] [WordPress Trac] #56070: Use a consistent order of annotations in the test suite

[WordPress Trac]

#56070: Use a consistent order of annotations in the test suite
------------------------------+---------------------
 Reporter:  SergeyBiryukov    |       Owner:  (none)
     Type:  enhancement       |      Status:  new
 Priority:  normal            |   Milestone:  6.1
Component:  Build/Test Tools  |     Version:
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:
------------------------------+---------------------
Description changed by SergeyBiryukov:

Old description:

> WordPress core has an [https://developer.wordpress.org/coding-standards
> /inline-documentation-standards/php/#docblock-formatting established
> DocBlock format] for inline documentation:
> {{{
> /**
>  * Summary.
>  *
>  * Description.
>  *
>  * @since x.x.x
>  *
>  * @see Function/method/class relied on
>  * @link URL
>  *
>  * @global type $varname Description.
>  * @global type $varname Description.
>  *
>  * @param type $var Description.
>  * @param type $var Optional. Description. Default.
>  * @return type Description.
>  */
> }}}
> This is more or less consistently applied in core, which is helpful for
> reusing this template for newly added functions without the guesswork of
> where to put each particular tag.
>
> Unit tests also use some of these tags:
> * `@since`
> * `@see`
> * `@global`
> * `@param`
> * `@return` (for tests with dependencies)
>
> as well as some [https://make.wordpress.org/core/handbook/testing
> /automated-testing/writing-phpunit-tests/#annotations test-specific
> annotations]:
> * `@ticket`
> * `@group`
> * `@covers`
> * `@depends`
> * `@requires`
> * `@dataProvider`
> * `@expectedDeprecated`
> * `@expectedIncorrectUsage`
>
> However, the order of these annotations differs in various test classes
> and can be almost random even in test methods of the same class. These
> inconsistencies increase cognitive load when writing new tests or
> reviewing test PRs to bring them in line with existing tests.
>
> I would like to propose a DocBlock template that can be consistently
> applied across the test suite. Something like:
> {{{
> /**
>  * Summary.
>  *
>  * Description.
>  *
>  * @ticket
>  * @since x.x.x
>  *
>  * @group group_name_1
>  * @group group_name_2
>  *
>  * @covers function_name_1
>  * @covers function_name_2
>  *
>  * @requires function function_name
>  *
>  * @expectedDeprecated
>  * @expectedIncorrectUsage
>  *
>  * @see Function/method/class relied on
>  * @link URL
>  *
>  * @depends test_name
>  * @dataProvider data_provider_name
>  *
>  * @global type $varname Description.
>  * @global type $varname Description.
>  *
>  * @param type $var Description.
>  * @param type $var Optional. Description. Default.
>  * @return type Description.
>  */
> }}}
>
> Notes:
> * All of these annotations are optional and may not be present on a
> particular test, so most of the time the DocBlock would be much shorter.
> But if they are present, the order should be consistent across the test
> suite.
> * `@ticket` and `@since` are grouped together because they are both
> related to when a test was introduced.
> * `@group` and `@covers` are separated into their own sections for better
> readability when a test belongs to multiple groups and/or covers multiple
> functions.
> * `@depends` and `@dataProvider` are grouped together and moved closer to
> globals and parameters, because they are both related to passing data to
> the test. When reviewing the current usage of `@depends` in the test
> suite, I found some instances that don't pass any data but seem to
> (incorrectly) assume that this annotation defines the order in which the
> tests are executed. That can be addressed separately.
>
> Any thoughts on using this DocBlock format or any suggestions for
> improving it are welcome.

New description:

 WordPress core has an [https://developer.wordpress.org/coding-standards
 /inline-documentation-standards/php/#docblock-formatting established
 DocBlock format] for inline documentation:
 {{{
 /**
  * Summary.
  *
  * Description.
  *
  * @since x.x.x
  *
  * @see Function/method/class relied on
  * @link URL
  *
  * @global type $varname Description.
  * @global type $varname Description.
  *
  * @param type $var Description.
  * @param type $var Optional. Description. Default.
  * @return type Description.
  */
 }}}
 This is more or less consistently applied in core, which is helpful for
 reusing this template for newly added functions without the guesswork of
 where to put each particular tag.

 Unit tests also use some of these tags:
 * `@since`
 * `@see`
 * `@global`
 * `@param`
 * `@return` (for tests with dependencies)

 as well as some [https://make.wordpress.org/core/handbook/testing
 /automated-testing/writing-phpunit-tests/#annotations test-specific
 annotations]:
 * `@ticket`
 * `@group`
 * `@covers`
 * `@depends`
 * `@requires`
 * `@dataProvider`
 * `@expectedDeprecated`
 * `@expectedIncorrectUsage`

 However, the order of these annotations differs in various test classes
 and can be almost random even in test methods of the same class. These
 inconsistencies increase cognitive load when writing new tests or
 reviewing test PRs to bring them in line with existing tests.

 I would like to propose a DocBlock template that can be consistently
 applied across the test suite. Something like:
 {{{
 /**
  * Summary.
  *
  * Description.
  *
  * @since x.x.x
  * @ticket 12345
  *
  * @group group_name_1
  * @group group_name_2
  *
  * @covers function_name_1
  * @covers function_name_2
  *
  * @requires function function_name
  *
  * @expectedDeprecated
  * @expectedIncorrectUsage
  *
  * @see Function/method/class relied on
  * @link URL
  *
  * @depends test_name
  * @dataProvider data_provider_name
  *
  * @global type $varname Description.
  * @global type $varname Description.
  *
  * @param type $var Description.
  * @param type $var Optional. Description. Default.
  * @return type Description.
  */
 }}}

 Notes:
 * All of these annotations are optional and may not be present on a
 particular test, so most of the time the DocBlock would be much shorter.
 But if they are present, the order should be consistent across the test
 suite.
 * `@since` and `@ticket` are grouped together because they are both
 related to when a test was introduced.
 * `@group` and `@covers` are separated into their own sections for better
 readability when a test belongs to multiple groups and/or covers multiple
 functions.
 * `@depends` and `@dataProvider` are grouped together and moved closer to
 globals and parameters, because they are both related to passing data to
 the test. When reviewing the current usage of `@depends` in the test
 suite, I found some instances that don't pass any data but seem to
 (incorrectly) assume that this annotation defines the order in which the
 tests are executed. That can be addressed separately.

 Any thoughts on using this DocBlock format or any suggestions for
 improving it are welcome.

--

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