Move the test-data config layer into TestCaseTrait so consumers can drop their base TestCase

[remyperona]

🤖 AI-generated — created with Claude Code, reviewed by @Tabrisrp. Surfaced while migrating wp-media/mcp-oauth to wp-media/phpunit v3.2. Contributes to #30.

Problem

Consumer plugins ship their own near-identical base TestCase classes (Tests/Unit/TestCase.php, Tests/Integration/TestCase.php) that add a thin, fully generic test-data convenience layer on top of the library's existing getTestData(). The layer contains zero plugin-specific code, so it's pure duplicated boilerplate.

Current state

src/TestCaseTrait.php already provides getTestData($dir, $filename) (maps a Unit/Integration dir to the sibling Fixtures dir and requires the matching fixture file) and is used by both src/Unit/TestCase.php and src/Integration/TestCase.php.

Consumers typically add, on top of that:

• protected $config; — holds the loaded fixture.
• configTestData(): array — returns $this->config['test_data'] ?? $this->config; used as a PHPUnit @dataProvider.
• loadTestDataConfig(): void — new ReflectionObject($this) to find the current test file, then $this->config = $this->getTestData( dirname($file), basename($file, '.php') ).

Some also override set_up() to eagerly call loadTestDataConfig().

Evidence it's pure, duplicated boilerplate

• In wp-media/mcp-oauth, the Unit and Integration TestCase.php files are identical except for the namespace and the visibility of set_up() (protected in Unit, public in Integration). The only project-specific token in either file is the namespace line.
• 35 test files consume this solely via @dataProvider configTestData; zero tests read $this->config directly in a test body. So the eager set_up() hook is redundant — data providers run before set_up(), and configTestData() already lazy-loads when $config is empty.

Proposed solution

Move $config, configTestData(), and loadTestDataConfig() into src/TestCaseTrait.php, right next to the getTestData() they depend on. Both Unit\TestCase and Integration\TestCase already use TestCaseTrait, so they inherit it automatically.

Do not add a set_up() hook inside the trait: it's unnecessary (lazy-loading via configTestData() covers all real usage) and would collide with the differing set_up() signatures/visibility of the Brain\Monkey (Unit) vs WP-integration (Integration) base classes.

Impact

Consumers can then delete both Tests/{Unit,Integration}/TestCase.php and extend WPMedia\PHPUnit\Unit\TestCase / WPMedia\PHPUnit\Integration\TestCase directly (a one-line use/extends change per test file, or a one-line project alias during migration). This advances the #30 goal of moving common, non-plugin-specific test infrastructure into the library.

References

Contributes to #30.

[remyperona]

Note

Generated by the AI delivery pipeline (grooming-agent · Claude Opus 4.8).

Grooming Plan — Issue #53

Approach: Move $config, configTestData(), and loadTestDataConfig() from consumers' duplicated base TestCase classes into src/TestCaseTrait.php, right below the existing getTestData(). Both Unit\TestCase and Integration\TestCase already use TestCaseTrait; and inherit the new members automatically — no change needed to either class. No set_up() hook is added to the trait, per the issue's explicit instruction (the Unit/BrainMonkey and Integration/WPIntegration base classes declare set_up()/setUp() with different signatures/visibility, and laziness in configTestData() already covers the only real call site: the @dataProvider).

Effort: S · Risk: MEDIUM · Complexity: MEDIUM

Key decision — property-default collision: src/VirtualFilesystemTestTrait.php already declares protected $config = [];, and both Unit\VirtualFilesystemTestCase and Integration\VirtualFilesystemTestCase extend TestCase (which will now carry TestCaseTrait::$config via inheritance) while also use VirtualFilesystemTestTrait; directly. PHP fatal-errors when composing a trait-declared property with an inherited property of the same name if their default values differ — this exact restriction is already documented in src/Integration/HttpRequestTrait.php's docblock and guarded by Tests/Integration/testHttpRequestTraitWithVirtualFilesystem.php. The spec therefore mandates TestCaseTrait::$config be declared with the same visibility and default as VirtualFilesystemTestTrait::$config (protected $config = [];), not protected $config; (implicit null) as a naive read of the issue might suggest.

Other spec highlights:

• configTestData() (public, matching the providerTestData() convention already used by VirtualFilesystemTestTrait) lazily calls loadTestDataConfig() when $this->config is empty, then returns $this->config['test_data'] ?? $this->config.
• loadTestDataConfig() (protected) uses ReflectionObject( $this )->getFileName() to resolve the matching fixture via the existing getTestData().
• Both new camelCase methods need phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid annotations, consistent with getTestData() / getNonPublicPropertyValue() already in that file — src/TestCaseTrait.php is already in phpcs.xml.dist's allow-list and PHPStan's analyzed paths, so the moved code must be WPCS- and PHPStan-clean with no new baseline entries.
• New tests added under Tests/Unit/TestCaseTrait/ (configTestData.php, loadTestDataConfig.php) following the "one class per method" layout, with fixtures under Tests/Fixtures/TestCaseTrait/. Unit-only (no WP function in the call chain). The existing Tests/Integration/testHttpRequestTraitWithVirtualFilesystem.php and testHttpRequestTrait.php are left untouched and serve as the regression canary for the collision above.

Test plan: composer test-unit for the new trait tests; npm run test:php:integration (or equivalent) to confirm Test_HttpRequestTraitWithVirtualFilesystem still passes; composer phpcs / composer phpstan green.

Effort: S — no PR splitting plan required.

Open questions: none blocking; flagged in the spec for the implementer to double check while writing code — whether to add explicit : array / : void return type hints on the two new methods (recommendation: omit, to match the return-type-hint-free style of every other method already in TestCaseTrait).

[remyperona]

Note

Generated by the AI delivery pipeline (orchestrator · Claude Opus 4.8).

PR: #58 | Status: READY FOR REVIEW

Stage	Result	Notes
Grooming	✅	effort: S, risk: MEDIUM→LOW
Challenger	✅ Approved	verified $config collision analysis; 3 scaffolding fixes folded in
Implementation	✅	branch: enhancement/53-testcasetrait-config-layer
DOD L2	✅ PASS	file scope clean, trailer present
Lead Review	✅ PASS	details on PR #58
CI	✅ 9/9 Pass	PHP 7.4–8.5 + phpcs + phpstan; integration suite green
QA	✅ PASS	5/5 acceptance criteria; details on PR #58
Follow-up tickets	None (1 NTH discarded by request)	—