Jest Reporter
Relevant source files
The following files were used as context for generating this wiki page:
The Jest Reporter is a language-specific test result collector for the tdd-guard ecosystem. Its primary purpose is to intercept test results from the Jest test runner and persist them in a standardized format that the TDD Guard CLI can analyze. By capturing assertion failures, module import errors, and overall test suite status, it provides the necessary telemetry for the AI-driven TDD principle validation.
This reporter integrates directly with Jest's reporter API, extending the BaseReporter class. It is designed to work within various environments, including standard Node.js projects, monorepos, and Storybook test-runner configurations.
Sources: README.md:1-20, reporters/jest/src/JestReporter.ts:13-20, reporters/jest/package.json:1-10
Architecture and Data Flow
The JestReporter operates as a lifecycle observer during a Jest test run. It collects individual test results as they complete and aggregates them into a final report when the entire run finishes.
Lifecycle Hooks
- onTestResult: Triggered after each test file completes. The reporter stores the
TestandTestResultobjects in an internal map keyed by the file path. - onRunComplete: Triggered after all tests have finished. The reporter transforms the collected internal data into a
CapturedTestRunobject and saves it using a storage provider.
Sources: reporters/jest/src/JestReporter.ts:39-55
Data Transformation Flow
The following diagram illustrates how Jest-native results are converted into TDD Guard internal schemas:
The diagram shows the sequence from Jest execution to final data persistence, highlighting the specific methods used to transform native Jest objects into TDD Guard structures.
Sources: reporters/jest/src/JestReporter.ts:46-135
Configuration
The reporter can be configured via jest.config.js or through programmatic instantiation.
Reporter Options
The reporter accepts a TDDGuardReporterOptions object which controls where data is saved.
| Option | Type | Description |
|---|---|---|
projectRoot | string | The absolute path to the project root. Essential for monorepos to ensure results are saved to the correct .claude/tdd-guard directory. |
storage | Storage | A custom storage implementation (e.g., MemoryStorage for testing). |
Sources: reporters/jest/src/JestReporter.ts:27-37, reporters/jest/src/JestReporter.test.ts:32-55
Example Integration
// jest.config.js
module.exports = {
reporters: [
'default',
['tdd-guard-jest', {
projectRoot: '/absolute/path/to/project'
}]
]
};
Sources: README.md:100-115, reporters/test/factories/jest.ts:35-47
Error Processing Logic
A critical feature of the JestReporter is its ability to extract granular error details that TDD Guard uses to identify specific TDD violations (e.g., "not defined" vs "assertion error").
Assertion Failures
For standard test failures, the reporter attempts to extract expected and actual values. It first looks at Jest's failureDetails object; if unavailable, it uses regex to parse the values directly from the failureMessages string.
Sources: reporters/jest/src/JestReporter.ts:77-108
Module Import Errors
If a test file fails to execute (e.g., due to a missing import), Jest provides a testExecError. The reporter synthesizes a virtual test result named Module failed to load (ErrorType) so that the TDD Guard validator can detect premature implementation or missing stubs.
This diagram demonstrates the handling of fatal execution errors that prevent tests from actually running.
Sources: reporters/jest/src/JestReporter.ts:109-135, reporters/jest/src/JestReporter.test.ts:125-150
Dependencies and Environment
The reporter is packaged as tdd-guard-jest and requires Node.js 22+.
| Dependency | Version | Role |
|---|---|---|
tdd-guard | ^1.1.0 | Core library providing Storage and Config classes. |
jest | >=30.0.5 | Peer dependency for the Jest reporter API. |
@jest/reporters | ^30.0.5 | Type definitions and base classes. |
Sources: reporters/jest/package.json:20-35
Summary
The Jest Reporter acts as the bridge between the Jest testing framework and TDD Guard's validation engine. By meticulously capturing test states, error messages, and execution failures, it ensures that the AI validator has a precise "Red" or "Green" context for every file operation. Its support for custom project roots makes it versatile for complex repository structures, while its robust error parsing provides the technical detail required to enforce incremental TDD development.
Sources: reporters/jest/src/JestReporter.ts:50-60, reporters/test/reporters.integration.test.ts:500-520