Vitest Reporter

The Vitest Reporter is a specialized module designed to integrate the Vitest testing framework with the TDD Guard ecosystem. Its primary purpose is to capture test results during execution and persist them in a structured format that TDD Guard can later analyze to enforce Test-Driven Development principles.

Sources: README.md:46-47, CLAUDE.md:6-12

Within the TDD Guard architecture, the reporter acts as a bridge between the test runner and the validation engine. By intercepting Vitest's internal test events, it extracts critical data such as module identifiers, test names, execution states (passed/failed), and detailed error messages, including expected and actual values for failed assertions.

Sources: CLAUDE.md:45-56, reporters/test/reporters.integration.test.ts:316-335

Integration and Configuration

The Vitest reporter is distributed as the tdd-guard-vitest package and must be explicitly added to the project's Vitest configuration. It requires the project root path to be specified to ensure that test results are stored in a location accessible to the TDD Guard CLI, typically within the .claude/tdd-guard/data/ directory.

Sources: README.md:76-85, reporters/vitest/package.json:2-10

Configuration Example

The reporter is initialized within vitest.config.ts (or .js) by adding it to the reporters array.

import { defineConfig } from 'vitest/config'
import { VitestReporter } from 'tdd-guard-vitest'

export default defineConfig({
  test: {
    reporters: [
      'default',
      new VitestReporter('/Users/username/projects/my-app'),
    ],
  },
})

Sources: README.md:88-99, reporters/test/factories/vitest.ts:40-49

Configuration Options

Sources: README.md:112-115, reporters/test/factories/vitest.ts:41-42

Data Capture Flow

The reporter follows a specific sequence to capture and save test data. It interacts with Vitest's hooks to gather information as tests finish and then uses a storage abstraction to write the final JSON output.

Process Flow Diagram

The following diagram illustrates how the Vitest Reporter captures data during a test run and saves it for TDD Guard.

Data Processing and Schema

Once the run is complete, the captured data is processed into a standardized schema. The TestResultsProcessor is responsible for transforming raw Vitest output into the internal TDD Guard format.

Captured Metadata

The reporter captures several key pieces of information for every test:

• Module ID: The file path of the test suite (e.g., single-failing.test.js).
• Full Test Name: The concatenated name of the test and its parent describe blocks (e.g., Calculator > should add numbers correctly).
• State: The outcome of the test, typically passed or failed.
• Error Details: For failing tests, it captures the error message and assertion details (e.g., expected 5 to be 6).

Sources: reporters/test/reporters.integration.test.ts:63-145, reporters/test/reporters.integration.test.ts:316-320

Processing Logic

The TestResultsProcessor performs the following operations:

1. Validation: Ensures the incoming JSON matches the expected Vitest result schema.
2. Counting: Calculates the number of passed/failed tests and modules.
3. Formatting: Generates human-readable summaries for the TDD Guard CLI.
4. Error Handling: Captures unhandled errors and stack traces.

Sources: src/processors/testResults/TestResultsProcessor.ts:7-25, src/processors/testResults/TestResultsProcessor.ts:110-136

Internal Architecture

The Vitest reporter relies on several core TDD Guard components to function correctly within the workspace.

Class Relationship

The relationship between the Vitest Reporter and the core TDD Guard library is shown below.

Summary

The Vitest Reporter is a critical integration component that enables automated TDD enforcement for projects using Vitest. By translating framework-specific test outcomes into a unified format and persisting them via FileStorage, it provides the necessary context for the TDD Guard validation engine to determine if implementation changes are justified by failing tests or if they constitute "over-implementation."

Sources: CLAUDE.md:6-12, README.md:15-25