TDD Guard

Automated Test-Driven Development enforcement for Claude Code.

Overview

TDD Guard ensures Claude Code follows Test-Driven Development principles. When your agent tries to skip tests or over-implement, TDD Guard blocks the action and explains what needs to happen instead.

<p align="center"> <a href="https://nizar.se/uploads/videos/tdd-guard-demo.mp4"> <img src="docs/assets/tdd-guard-demo-screenshot.gif" alt="TDD Guard Demo" width="600"> </a> <br> <em>Click to watch TDD Guard in action</em> </p>

Features

• Test-First Enforcement - Blocks implementation without failing tests
• Minimal Implementation - Prevents code beyond current test requirements
• Lint Integration - Enforces refactoring using your linting rules
• Multi-Language Support - TypeScript, JavaScript, Python, PHP, Go, Rust, and Storybook
• Customizable Rules - Adjust validation rules to match your TDD style
• Flexible Validation - Choose faster or more capable models for your needs
• Session Control - Toggle on and off mid-session

Requirements

• Node.js 22+
• Claude Code or Anthropic API key
• Test framework (Jest, Vitest, Storybook, pytest, PHPUnit, Go 1.24+, or Rust with cargo/cargo-nextest)

Quick Start

1. Install TDD Guard

Using npm:

npm install -g tdd-guard

Or using Homebrew:

brew install tdd-guard

2. Add Test Reporter

TDD Guard needs to capture test results from your test runner. Choose your language below:

<details> <summary><b>JavaScript/TypeScript</b></summary>

Choose your test runner:

Vitest

Install the tdd-guard-vitest reporter in your project:

npm install --save-dev tdd-guard-vitest

Add to your vitest.config.ts:

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

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

Jest

Install the tdd-guard-jest reporter in your project:

npm install --save-dev tdd-guard-jest

Add to your jest.config.ts:

import type { Config } from 'jest'

const config: Config = {
  reporters: [
    'default',
    [
      'tdd-guard-jest',
      {
        projectRoot: '/Users/username/projects/my-app',
      },
    ],
  ],
}

export default config

Note: For both...