Go Test Reporter
Relevant source files
The following files were used as context for generating this wiki page:
The Go Test Reporter (executable as tdd-guard-go) is a specialized component of the TDD Guard system designed to capture and transform Go test results. It acts as a CLI filter that intercepts go test -json output, processes it into a standardized JSON format, and saves it for validation by the AI-powered TDD Guard Core.
Its primary purpose is to provide the TDD Guard validation engine with the necessary context (test states, failure messages, and compilation errors) to enforce Test-Driven Development principles in Go projects. By piping test output through this reporter, developers ensure that Claude Code can accurately assess whether implementation changes are justified by failing tests.
Sources: README.md:154-159, CLAUDE.md:12-25
Architecture and Data Flow
The reporter operates as a pipe-based utility. It reads standard input (stdin), which is expected to be the output of go test -json, and performs three simultaneous actions: it passes the output to standard output (stdout), parses the JSON events, and transforms the results for storage.
Data Processing Pipeline
The process function manages the lifecycle of a reporting session, involving validation, buffering, parsing, and storage.
The flow ensures that users see their test results in real-time while the tool captures data in the background.
Sources: reporters/go/cmd/tdd-guard-go/main.go:34-58, reporters/go/cmd/tdd-guard-go/main_test.go:133-145
Core Components
| Component | Responsibility |
|---|---|
| Main/CLI | Handles the -project-root flag and sets up the I/O streams. |
| MixedReader | Distinguishes between JSON lines (test events) and non-JSON lines (compilation errors or plain text). |
| Parser | Deserializes Go TestEvent structures and aggregates them into Results. |
| Transformer | Converts Go-specific internal results into the unified TDD Guard schema. |
| Storage | Persists the transformed data to the project's local storage directory. |
Sources: reporters/go/cmd/tdd-guard-go/main.go:19-32, reporters/go/internal/transformer/transformer_test.go:21-44
Execution and Configuration
The reporter requires an absolute project root path to correctly locate the storage directory and validate the execution context.
CLI Arguments
| Flag | Type | Description |
|---|---|---|
-project-root | string | Required. The absolute path to the project root. The current working directory must be within this path. |
Validation Logic
Before processing, the reporter validates the project-root. It enforces that the path is absolute and that the current directory is a child of the root. This prevents security issues and ensures data is written to the correct project context.
func validateProjectRoot(projectRoot string) error {
if projectRoot == "" {
return nil
}
if !filepath.IsAbs(projectRoot) {
return errors.New("project root must be an absolute path")
}
cwd, _ := os.Getwd()
if !strings.HasPrefix(cwd, projectRoot) {
return errors.New("current directory must be within project root")
}
return nil
}
Sources: reporters/go/cmd/tdd-guard-go/main.go:88-103, reporters/go/cmd/tdd-guard-go/main_test.go:68-81
Test Result Transformation
The reporter maps Go's native JSON test events to a standardized schema. This mapping includes package paths, test names, and execution states.
State Mapping
The Transformer converts Go's internal TestState (passed, failed) into the strings expected by the TDD Guard validation engine.
| Go State | Transformed State |
|---|---|
parser.StatePassed | "passed" |
parser.StateFailed | "failed" |
Full Name Construction
To provide unique identifiers for tests, the Transformer concatenates the package path with the test name, using a forward slash as a separator (e.g., example.com/pkg/TestExample).
Sources: reporters/go/internal/transformer/transformer_test.go:58-94, reporters/test/reporters.integration.test.ts:167-172
Error Handling
Compilation Errors
A unique feature of the Go reporter is its ability to handle build failures. Since go test might fail before any tests run, the reporter looks for lines starting with # (indicating package build errors) and non-JSON output.
If a compilation error is detected:
- A synthetic test named
CompilationErroris added to the results. - The package where the failure occurred is identified.
- Each line of the error message is captured as a separate error entry.
Output Formatting
While capturing results, the reporter also acts as a formatter for the user's terminal. It intercepts JSON events and prints human-readable status lines (e.g., ok example.com/pkg 0.003s). Non-JSON lines are passed through unmodified to ensure build errors and logs remain visible.
Sources: reporters/go/cmd/tdd-guard-go/main.go:66-86, reporters/go/cmd/tdd-guard-go/main_test.go:96-107
Summary
The Go Test Reporter is a critical bridge between the Go toolchain and TDD Guard. By parsing go test -json output and handling edge cases like compilation failures, it provides a robust dataset for AI-driven TDD enforcement. Its design as a transparent filter allows it to be easily integrated into Makefiles or existing CI workflows without disrupting standard development practices.
Sources: README.md:162-167, reporters/go/cmd/tdd-guard-go/main.go:110-119