[wp-trac] [WordPress Trac] #53010: Tests: introduce namespacing for the test classes

[WordPress Trac]

#53010: Tests: introduce namespacing for the test classes
------------------------------+-------------------------------------
 Reporter:  jrf               |       Owner:  (none)
     Type:  task (blessed)    |      Status:  new
 Priority:  normal            |   Milestone:  Awaiting Review
Component:  Build/Test Tools  |     Version:  trunk
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:  docs, coding-standards
------------------------------+-------------------------------------
Description changed by jrf:

Old description:

> 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]/Class_Under_Test/FunctionUnderTest[OptionalSubsetIndicator]Test.php`
> * Namespace: `WordPress\Tests\WP_[Includes|Admin]\Class_Under_Test`
> * 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:

 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/53010#comment:2>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform