PHPUnit Reporter
Relevant source files
The following files were used as context for generating this wiki page:
The PHPUnit Reporter is a specialized component of the TDD Guard ecosystem designed to capture and normalize test results from PHPUnit execution. Its primary purpose is to provide the TDD Guard validation engine with accurate data regarding test passes, failures, and errors within PHP projects, ensuring that Claude Code adheres to Test-Driven Development principles.
The reporter supports a wide range of PHPUnit versions (9.0 through 12.0) and integrates directly into the PHPUnit execution lifecycle using either modern Extensions (for PHPUnit 10+) or legacy Listeners (for PHPUnit 9.x). It outputs standardized JSON data to a specific directory within the project, which is then analyzed to block over-implementation or premature coding.
Sources: reporters/phpunit/README.md:1-10, reporters/phpunit/composer.json:28-31, README.md:1-15
Architecture and Components
The reporter architecture is built to be compatible with different versions of the PHPUnit framework while maintaining a consistent internal logic for result collection and storage.
Core Classes and Interfaces
| Component | Description |
|---|---|
TddGuardExtension | The entry point for PHPUnit 10, 11, and 12. Implements the Extension interface to bootstrap the reporter. |
TddGuardListener | The entry point for PHPUnit 9.x. Implements TestListener to intercept test events. |
Storage | Internal utility (used by the reporter) to write the captured JSON results to the .claude/tdd-guard/data/ directory. |
PathValidator | Resolves and validates the project root to ensure relative paths are calculated correctly. |
Sources: reporters/phpunit/src/TddGuardListener.php:19-24, reporters/phpunit/README.md:15-55, reporters/phpunit/src/TddGuardExtension.php
Data Flow Diagram
The following diagram illustrates how the reporter intercepts test events and persists them for the TDD Guard validator.
The reporter normalizes various PHP states (passed, failed, errored, skipped) into a format compatible with the TDD Guard schema.
Sources: reporters/phpunit/src/TddGuardListener.php:50-100, reporters/phpunit/tests/TddGuardExtensionFailedTest.php:125-135
Integration and Configuration
The reporter must be registered in the phpunit.xml configuration file. The method of registration depends on the PHPUnit version being used.
PHPUnit 10/11/12 Configuration
Modern versions use the <extensions> block. The projectRoot parameter is critical for TDD Guard to map test results to specific files in the workspace.
<extensions>
<bootstrap class="TddGuard\PHPUnit\TddGuardExtension">
<parameter name="projectRoot" value="/absolute/path/to/project/root"/>
</bootstrap>
</extensions>
Sources: reporters/phpunit/README.md:19-30, README.md:144-150
PHPUnit 9.x Configuration
Older versions require the <listeners> block.
<listeners>
<listener class="TddGuard\PHPUnit\TddGuardListener">
<arguments>
<string>/absolute/path/to/project/root</string>
</arguments>
</listener>
</listeners>
Sources: reporters/phpunit/README.md:37-48, README.md:135-141
Result Normalization
A key feature of the PHPUnit reporter is the normalization of PHP-specific test outcomes into the global TDD Guard states. This ensures that the AI validator receives consistent signals regardless of the language.
State Mapping
The reporter maps PHPUnit's internal states as follows:
- Passed: Recorded as
passed. - Failure / Error / Warning / Risky: All normalized to
failedto trigger TDD enforcement. - Incomplete / Skipped: Recorded as
skipped.
Sources: reporters/phpunit/src/TddGuardListener.php:58-95, reporters/phpunit/tests/TddGuardExtensionFailedTest.php:154-158
Captured Data Structure
The reporter generates a JSON object containing testModules. Each module represents a file, and each test includes details such as the full name and error messages.
{
"testModules": [
{
"moduleId": "tests/FailingTest.php",
"tests": [
{
"name": "testFailing",
"fullName": "FailingTest::testFailing",
"state": "failed",
"errors": [
{ "message": "Math is broken!" }
]
}
]
}
]
}
Sources: reporters/phpunit/src/TddGuardListener.php:107-130, reporters/phpunit/tests/TddGuardExtensionFailedTest.php:68-80
Project Root Resolution
To accurately report moduleId (the relative path to the test file), the reporter must determine the project root. It follows a specific priority:
- Explicit Configuration: Value provided in
phpunit.xml. - Environment Variable:
TDD_GUARD_PROJECT_ROOT. - Automatic Detection: The directory containing
phpunit.xmlor the current working directory.
The reporter validates that the path is absolute; otherwise, it falls back to the current working directory.
Sources: reporters/phpunit/README.md:57-73, reporters/phpunit/src/TddGuardListener.php:29-32
Conclusion
The PHPUnit Reporter serves as the essential bridge between PHP environments and TDD Guard. By intercepting PHPUnit's execution lifecycle and normalizing complex test states into a simple JSON schema, it enables automated TDD enforcement for PHP developers using Claude Code. Its support for multiple PHPUnit versions and flexible path resolution makes it a robust tool for various project structures, from simple libraries to complex monorepos.