Test Results Processor
Relevant source files
The following files were used as context for generating this wiki page:
The Test Results Processor is a critical component of the TDD Guard system responsible for parsing, validating, and formatting raw JSON data produced by various language-specific test reporters. Its primary purpose is to transform technical test output into a human-readable summary that the AI validator uses to determine TDD compliance, specifically checking if implementation changes are justified by preceding test failures.
This processor bridges the gap between language-specific tools (like pytest, vitest, or go test) and the core TDD validation logic. By normalizing disparate output formats into a consistent string representation, it enables the system to evaluate whether the Red-Green-Refactor cycle is being followed regardless of the programming language being used.
Sources: src/processors/testResults/TestResultsProcessor.ts:7-25, src/validation/prompts/tools/test-output.ts:1-12, CLAUDE.md:65-75
Architecture and Data Flow
The processor operates as a pipeline that takes raw JSON strings, validates them against expected schemas, calculates aggregate statistics, and generates a formatted text report.
Processing Pipeline
The process method orchestrates the transformation through several private helper stages. It supports multiple frameworks, primarily defaulting to vitest but accommodating pytest specific schemas as well.
The diagram shows the logical flow from raw input to the final human-readable string used for AI context.
Sources: src/processors/testResults/TestResultsProcessor.ts:7-25, src/processors/testResults/TestResultsProcessor.ts:173-195
Key Components
| Component | Description |
|---|---|
parseAndValidate | Handles double-encoded JSON and validates data against VitestTestResultSchema or PytestResultSchema. |
countTestsAndModules | Aggregates pass/fail counts for both individual tests and entire test modules (files). |
formatModules | Generates the visual tree of test results, using symbols like ✓ for pass and ❯ for fail. |
formatUnhandledErrors | Captures stack traces and error names for failures occurring outside specific test blocks (e.g., import errors). |
Sources: src/processors/testResults/TestResultsProcessor.ts:27-60, src/processors/testResults/TestResultsProcessor.ts:77-100, src/processors/testResults/TestResultsProcessor.ts:133-157
Handling Test Failures and Stubs
A significant feature of the processor is its ability to identify "invisible" failures, such as when a test run fails completely due to missing imports or compilation errors.
Import and Compilation Errors
If a test run fails but no tests were collected, the processor injects a specific warning: "Test run failed - This is likely when an imported module can not be found". This is crucial for TDD Guard to allow the creation of initial stubs or classes even when standard assertion output is missing.
In the Go reporter, synthetic tests are added for compilation errors to ensure the processor can report them correctly:
func addCompilationError(results parser.Results, compilationError *parser.CompilationError) {
results[compilationError.Package] = parser.PackageResults{
"CompilationError": parser.StateFailed,
}
}
Sources: src/processors/testResults/TestResultsProcessor.ts:120-131, reporters/go/cmd/tdd-guard-go/main.go:106-110
Formatting Logic
The processor uses specific visual indicators to represent the state of the test suite:
✓: Indicates a passing module or test.❯: Indicates a failing module.×: Indicates a failing test or unhandled error.→: Prefixes specific error messages or assertion failures (e.g.,expected 5 to be 6).
Sources: src/processors/testResults/TestResultsProcessor.ts:83-95, src/processors/testResults/TestResultsProcessor.test.ts:78-90
TDD Validation Context
The output of the TestResultsProcessor is directly injected into the AI prompt to provide context for the current modification. This output is evaluated against specific TDD rules defined in the project.
Failure Type Mapping
The processor's output allows the validator to match implementation changes to specific failure types:
| Detected Failure Output | Allowed Implementation |
|---|---|
| "X is not defined" | Create empty class/function stub only |
| "X is not a constructor" | Create empty class only |
| "X is not a function" | Add method stub only |
| Assertion error | Implement logic to pass assertion |
Sources: src/validation/prompts/file-types.ts:20-30, src/validation/prompts/operations/edit.ts:38-48
The sequence shows how the formatted output becomes the "evidence" for the AI validator.
Sources: src/validation/context/context.test.ts:98-115, src/validation/prompts/tools/test-output.ts:1-12
Summary of Processing Rules
The processor follows strict rules for summarizing counts:
- Module Failure: A module is marked as failed if it contains at least one failing test OR if the total test run failed with zero tests collected in that module.
- Double Encoding: The processor automatically attempts a second
JSON.parseif the initial result is a string, ensuring compatibility with reporters that stringify the payload twice. - Empty Results: If no modules are present after parsing, it returns "No test results found."
Sources: src/processors/testResults/TestResultsProcessor.ts:10-14, src/processors/testResults/TestResultsProcessor.ts:40-45, src/processors/testResults/TestResultsProcessor.ts:178-185
Conclusion
The Test Results Processor serves as the primary data translator for TDD Guard. By converting raw, framework-specific JSON into a structured, readable format, it provides the necessary "Red Phase" evidence required for the AI to validate that subsequent implementation changes are both minimal and justified by existing test failures.