Storybook Reporter

Relevant source files

The following files were used as context for generating this wiki page:

• reporters/storybook/src/StorybookReporter.test.ts
• reporters/storybook/README.md
• reporters/test/factories/storybook.ts
• reporters/test/reporters.integration.test.ts
• README.md
• CLAUDE.md

The Storybook Reporter is a specialized test result collector designed for the Storybook test-runner. Its primary purpose is to intercept interaction test results—specifically stories utilizing play functions—and format them into a standardized JSON structure required for TDD Guard validation. This allows the TDD Guard AI to verify if UI component changes adhere to Test-Driven Development principles by analyzing the success or failure of component-level interaction tests.

Sources: reporters/storybook/README.md:1-5, CLAUDE.md:38, README.md:100-110

Architecture and Integration

The Storybook Reporter acts as a bridge between the @storybook/test-runner (which uses Jest under the hood) and the TDD Guard core logic. It captures results during the postVisit phase of the test-runner execution.

Data Flow

1. Trigger: The Storybook test-runner visits a story.
2. Capture: If the story has a play function, the onStoryResult method is invoked.
3. Processing: The reporter maps Storybook-specific test states (passed, failed, skipped) to the TDD Guard internal schema.
4. Persistence: Upon completion (onComplete), the aggregated results are written to the local filesystem at .claude/tdd-guard/data/test.json.

The diagram shows the lifecycle of a test result from the runner to final storage.
Sources: reporters/storybook/README.md:36-42, reporters/storybook/src/StorybookReporter.test.ts:108-120

Key Components

Class: StorybookReporter

The main entry point for capturing results. It can be initialized with a specific project root or a storage instance.

• onStoryResult(context, status, errors): Processes individual story results. It captures the moduleId (usually the story ID) and individual test cases.
• onComplete(): Finalizes the test run, calculates the overall reason (passed/failed), and persists the data.

Sources: reporters/storybook/src/StorybookReporter.test.ts:11-30, reporters/storybook/README.md:52-65

Storage Integration

The reporter defaults to FileStorage, which utilizes the TDD Guard Config to determine the correct data directory. In monorepo setups, the projectRoot must be explicitly provided to ensure the results are saved in a location accessible to the Claude Code hook.

Sources: reporters/storybook/src/StorybookReporter.test.ts:12-25, reporters/storybook/README.md:27-34

Configuration

The reporter is integrated into the Storybook environment via the .storybook/test-runner.ts (or .js) configuration file.

Integration Parameters

Parameter	Type	Description	Default
projectRoot	string	Absolute path to the project root directory.	Current working directory
storage	Storage	An instance of TDD Guard storage (e.g., MemoryStorage for tests).	FileStorage

Sources: reporters/storybook/README.md:21-45, reporters/storybook/src/StorybookReporter.test.ts:20-30

Setup Example

const { StorybookReporter } = require('tdd-guard-storybook');
const reporter = new StorybookReporter();

module.exports = {
  async postVisit(page, context) {
    await reporter.onStoryResult(context);
  },
};

process.on('exit', () => {
  reporter.onComplete();
});

Sources: reporters/storybook/README.md:13-25

Test Result Mapping

The reporter standardizes various Storybook outputs into a uniform schema for the TDD Guard validator.

Storybook Status	TDD Guard State	Description
passed	passed	All assertions in the play function succeeded.
failed	failed	One or more assertions failed or an error was thrown.
skipped	skipped	The test was intentionally bypassed.

Sources: reporters/storybook/src/StorybookReporter.test.ts:110-120, reporters/test/reporters.integration.test.ts:250-270

Error Capture

For failed tests, the reporter extracts error messages and stack traces. This information is critical for TDD Guard to determine if a subsequent code edit is a "minimal implementation" addressing that specific failure.

The sequence diagram illustrates the extraction and persistence of error details.
Sources: reporters/storybook/src/StorybookReporter.test.ts:79-100, reporters/test/reporters.integration.test.ts:320-340

Integration Testing

The reporter is verified through integration tests that simulate full Storybook runs using a random port (8000-8999) to avoid conflicts. It ensures that moduleId accurately reflects the story name (e.g., single-failing.stories) and that the reason field correctly summarizes the entire run as passed or failed.

Sources: reporters/test/factories/storybook.ts:18-25, reporters/test/reporters.integration.test.ts:440-460

Summary

The Storybook Reporter provides necessary visibility into UI component testing for the TDD Guard system. By capturing interaction test results from Storybook's play functions, it enables automated enforcement of TDD cycles in frontend development, ensuring that UI logic is implemented incrementally and only in response to failing component tests.