[policy, no patch] Secondary/additional test @group names

Open on Drupal.org →

Created on 3 July 2014, almost 11 years ago

Updated 29 January 2025, 4 months ago

Context

Each test class can define one or more groups.
The "primary" group of a test class SHOULD either be the component name or the module name.
There is no standard/guide for secondary/additional groups yet, but we need one.

Goal

Define a new policy for secondary @group names.

PHPUnit tests

Initial proposal from #2057905-47: [policy, no patch] Discuss the standards for phpunit based tests → :

For tests of Drupal core components, the test class MUST specify the (literal/capitalized) component name as the first @group. For example, @group Routing. Additional groups MAY only be specified if the test class MUST also be executed as part of the secondary groups, but that is NOT RECOMMENDED for component tests.

For tests of modules, the test class MUST specify the internal module name as the first @group. For example, @group entity_reference. Additional groups MAY be specified, if applicable.

For PHPUnit tests, every specified @group MUST reference an existing primary @group; i.e., either the name of a Component, or the internal name of a module. PHPUnit @group annotations MUST NOT invent new/custom group names that do not map to any other component or module.

Simpletest tests

First and foremost, the following paragraph from "PHPUnit tests" above should apply:

For tests of modules, the test class MUST specify the internal module name as the first @group. For example, @group entity_reference. Additional groups MAY be specified, if applicable.

With one single exception: System module holds tests for core components, separated by core component subdirectories. The @group for those tests MUST be the component name of the core component.
TBD: Selected integration tests for larger modules (e.g., Views) were using special snowflake group names in the past:
- Views module integration
- Views plugins
- Views handlers
(Those Views groups appear to be the only special case in core.)

It's not clear (1) whether anyone ever used these groups to run (all) contained tests, and if that happens to be the case, (2) whether we're able to derive a generic pattern of that idea.

Assuming the use-case is valid, the following naming aspects need to be taken into account:
1. The new primary group for Views module is 'views' (lowercase).
2. The "value" to a @group annotation MUST be a machine-readable identifier and MUST NOT be ambiguous with a possible PHPDoc description; i.e., @group names MUST NOT contain spaces.
3. The grouped tests SHOULD be run when tests are filtered by the (literal) @group name.
4. The grouped tests SHOULD NOT be run when tests are filtered by e.g. 'views'. (→ Check whether PHPUnit interprets --group as a wildcard prefix or terminated literal.)
5. Custom/secondary @group names MUST be namespaced by the owning/originating module to prevent group name clashes across contrib/custom extensions.
To thow out an initial proposal, secondary @group names may be:
1. views/integration
2. views/plugins
3. views/handlers
Discuss.