Tdd Gate Check

Enforces test-driven development by blocking edits to production code unless a corresponding test file already exists.

When to Use This Hook

Attach this hook when you need to:

• Enforce a strict write-tests-first discipline across the team
• Prevent production code changes without test coverage in place
• Build a TDD culture where tests are the specification, not an afterthought

Consider alternatives when:

• You are prototyping or spiking and test coverage is intentionally deferred
• Your project uses a different testing strategy like property-based or acceptance testing

Quick Start

Configuration

Copy
name: tdd-gate-check
type: hook
trigger: PreToolUse
category: quality-gates

Example Trigger

Copy
# Hook triggers before editing a production code file
claude> Edit src/services/UserService.ts
# Gate checks for corresponding test file existence

Example Output

TDD Gate: Checking test coverage for UserService.ts
  Looking for test files:
    src/services/UserService.test.ts ... NOT FOUND
    src/services/UserService.spec.ts ... NOT FOUND
    src/services/__tests__/UserService.test.ts ... FOUND
  Test file exists. Edit permitted.

Core Concepts

TDD Gate Rules Overview

Aspect	Details
Production Files	.cs, .py, .ts, .go, .rs, .rb, .php, .java, .kt, .swift, .dart
Auto-Excluded	Config files, migrations, DTOs, test files, infrastructure
Test Patterns	*Test.ext, *.test.ext, *_test.ext, test_*.ext
Matchers	Edit, MultiEdit, Write
Enforcement	Blocks edit with exit code 1 if no test file found

TDD Gate Workflow

Edit Requested
      |
  Is Production File?
   /           \
  No           Yes
  |             |
Allow      Is Excluded?
          (config, DTO, etc.)
           /        \
         Yes         No
          |           |
        Allow    Search for
                Test File
                   |
              ┌────┴────┐
              |         |
           Found    Not Found
              |         |
           Allow     BLOCK
                   "Write tests
                    first"

Configuration

Parameter	Type	Default	Description
production_extensions	string[]	[".ts",".py",".go",".rs",".java"]	File extensions considered production code
test_patterns	string[]	["*Test.*","*.test.*","*.spec.*","test_*.*"]	Naming patterns for test file discovery
excluded_patterns	string[]	["*.config.*","*migration*","*dto*"]	File patterns exempt from TDD gate
search_dirs	string[]	["__tests__","test","tests","spec"]	Additional directories to search for test files
block_on_missing	boolean	true	Block edit or just warn when test is missing

Best Practices

1. Exclude Infrastructure Code - Database migrations, config files, and generated code should bypass the TDD gate. These files have different testing strategies and blocking them creates unnecessary friction.

2. Support Multiple Test Patterns - Different languages and frameworks use different test naming conventions. Support all common patterns to avoid false blocking from naming mismatches.

3. Allow a Warm-Up Period - When introducing the TDD gate to an existing project, start in warning mode. Blocking immediately on a codebase without test coverage creates a deadlock.

4. Provide Clear Next Steps - When blocking an edit, tell the developer exactly which test file to create and where. A message like "Create src/services/UserService.test.ts first" is more helpful than "test not found."

5. Auto-Exclude Test Files Themselves - Ensure the gate does not block edits to test files. A test file should not need a test of its own to be editable.

Common Issues

1. Test File Naming Mismatch - If a test file uses a different naming convention (e.g., user_service_tests.py vs test_user_service.py), the gate fails to find it. Expand patterns to cover your project's conventions.

2. Monorepo Test Locations - In monorepos, test files may be in a separate packages/tests/ directory rather than alongside source code. Add custom search directories for your project structure.

3. Blocking Generated Code Edits - Code generators produce files without tests. Add generator output patterns (e.g., *.generated.ts, *.g.dart) to the exclusion list.