[wp-trac] [WordPress Trac] #65208: Introduce namespacing for the test classes for 7.1

[WordPress Trac]

#65208: Introduce namespacing for the test classes for 7.1
------------------------------+---------------------
 Reporter:  desrosj           |       Owner:  (none)
     Type:  task (blessed)    |      Status:  new
 Priority:  normal            |   Milestone:  7.1
Component:  Build/Test Tools  |     Version:
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:  tests
------------------------------+---------------------
Changes (by desrosj):

 * keywords:  has-patch has-unit-tests =>


Old description:

> This ticket is for continuing to introduce namespacing for test classes
> during the 7.1 release cycle.
>
> Previous releases:
> - 7.0: #53010
>
> Overview copied directly from #53010 (please read the discussion on that
> ticket):
>
> Introducing namespaces in the production code for WordPress Core is a hot
> topic, so I very purposely do NOT want to touch that in this ticket.
>
> However, for the test suite, which doesn't get shipped with the WordPress
> production code, it's a whole other matter.
>
> == Benefits
>
> Using namespaces in the test suite provides us with the following
> benefits:
> 1. If used consistently and providing they follow a set pattern (more
> about this below), they will make it very easy for contributors to find
> the test files/classes they are looking for.
> 2. It will allow for shorter file and test class names, while those will
> still be descriptive.
> 3. And... it will allow for mocking PHP native functions by declaring a
> namespaced version of that same function in the test class.
> 4. It will also allow more easily for multiple test classes to be created
> to test one particular feature/function, which the current naming scheme
> does not allow for. This will allow for tests for the same functionality,
> but which need different fixtures (setup/teardown) to be encapsulated in
> their own test classes.
>
> == Caveats:
>
> As the WordPress Core test suite is used not only by Core, but also by
> plugins and themes for integration tests, the test class namespacing
> should be reserved for actual test classes and - for now - not be applied
> to test utility classes / Abstract base test classes (i.e. the
> `tests/phpunit/includes` directory should NOT be touched for now).
>
> == Proposed pattern
>
> The current directory structure for tests is, to put it mildly, confusing
> and inconsistent.
>
> To solve that, I would like to propose the following pattern:
> * File paths:
> `tests/phpunit/tests/wp-[includes|admin]/[SubFolder/]*Class_Under_Test/FunctionUnderTest[OptionalSubsetIndicator]Test.php`
> * Namespace:
> `WordPress\Tests\WP_[Includes|Admin]\[SubFolder\]*Class_Under_Test`
> * Classname: `FunctionUnderTest[OptionalSubsetIndicator]Test`
>
> For WP Core files which only contain functions outside of a class
> structure, the following pattern is proposed:
> * File paths:
> `tests/phpunit/tests/wp-[includes|admin]/[SubFolder/]*Functions_FileName/FunctionUnderTest[OptionalSubsetIndicator]Test.php`
> * Namespace:
> `WordPress\Tests\WP_[Includes|Admin]\[SubFolder\]*Functions_FileName`
> * Classname: `FunctionUnderTest[OptionalSubsetIndicator]Test`
>

> The pattern I'm proposing does imply a re-organisation of the test suite
> directory and file structure, but that IMO is for the better.
>
> It also follows a PSR4-like pattern which will be more intuitive for new
> contributors to work with, as well as follow the PHPUnit recommended test
> class name pattern with having the `Test` as the end of the class name.
>
> This will also allow for using PSR-4 autoloading for the tests classes
> and adding the `autoload-dev` directive to the `composer.json` file.
>

>
> == Planning
>
> This should be regarded as a small project and not all renaming needs to
> be done at the same time.
>
> New tests should start following the above proposed pattern as soon as
> consensus has been reached about this proposal.
> Existing tests can be gradually switched over to the new pattern over
> time.
>
> == Additional tasks associated with this project
>
> - [ ] Updating the contributors handbook for Core.
> - [ ] Verify that the WordPressCS sniffs will validate this pattern
> correctly.
> - [ ] Write a Make post about the decision once consensus has been
> reached.

New description:

 This ticket is for continuing to introduce namespacing for test classes
 during the 7.1 release cycle.

 Previous releases:
 - 7.0: #53010

 Overview copied directly from #53010 (please read the discussion on that
 ticket):

 > Introducing namespaces in the production code for WordPress Core is a
 hot topic, so I very purposely do NOT want to touch that in this ticket.
 >
 > However, for the test suite, which doesn't get shipped with the
 WordPress production code, it's a whole other matter.
 >
 > == Benefits
 >
 > Using namespaces in the test suite provides us with the following
 benefits:
 > 1. If used consistently and providing they follow a set pattern (more
 about this below), they will make it very easy for contributors to find
 the test files/classes they are looking for.
 > 2. It will allow for shorter file and test class names, while those will
 still be descriptive.
 > 3. And... it will allow for mocking PHP native functions by declaring a
 namespaced version of that same function in the test class.
 > 4. It will also allow more easily for multiple test classes to be
 created to test one particular feature/function, which the current naming
 scheme does not allow for. This will allow for tests for the same
 functionality, but which need different fixtures (setup/teardown) to be
 encapsulated in their own test classes.
 >
 > == Caveats:
 >
 > As the WordPress Core test suite is used not only by Core, but also by
 plugins and themes for integration tests, the test class namespacing
 should be reserved for actual test classes and - for now - not be applied
 to test utility classes / Abstract base test classes (i.e. the
 `tests/phpunit/includes` directory should NOT be touched for now).
 >
 > == Proposed pattern
 >
 > The current directory structure for tests is, to put it mildly,
 confusing and inconsistent.
 >
 > To solve that, I would like to propose the following pattern:
 > * File paths:
 `tests/phpunit/tests/wp-[includes|admin]/[SubFolder/]*Class_Under_Test/FunctionUnderTest[OptionalSubsetIndicator]Test.php`
 > * Namespace:
 `WordPress\Tests\WP_[Includes|Admin]\[SubFolder\]*Class_Under_Test`
 > * Classname: `FunctionUnderTest[OptionalSubsetIndicator]Test`
 >
 > For WP Core files which only contain functions outside of a class
 structure, the following pattern is proposed:
 > * File paths:
 `tests/phpunit/tests/wp-[includes|admin]/[SubFolder/]*Functions_FileName/FunctionUnderTest[OptionalSubsetIndicator]Test.php`
 > * Namespace:
 `WordPress\Tests\WP_[Includes|Admin]\[SubFolder\]*Functions_FileName`
 > * Classname: `FunctionUnderTest[OptionalSubsetIndicator]Test`
 >
 >
 > The pattern I'm proposing does imply a re-organisation of the test suite
 directory and file structure, but that IMO is for the better.
 >
 > It also follows a PSR4-like pattern which will be more intuitive for new
 contributors to work with, as well as follow the PHPUnit recommended test
 class name pattern with having the `Test` as the end of the class name.
 >
 > This will also allow for using PSR-4 autoloading for the tests classes
 and adding the `autoload-dev` directive to the `composer.json` file.
 >
 >
 >
 > == Planning
 >
 > This should be regarded as a small project and not all renaming needs to
 be done at the same time.
 >
 > New tests should start following the above proposed pattern as soon as
 consensus has been reached about this proposal.
 > Existing tests can be gradually switched over to the new pattern over
 time.
 >
 > == Additional tasks associated with this project
 >
 > - [ ] Updating the contributors handbook for Core.
 > - [ ] Verify that the WordPressCS sniffs will validate this pattern
 correctly.
 > - [ ] Write a Make post about the decision once consensus has been
 reached.

--

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