TDD Guard

1.6.3 · active · verified Tue Apr 21

TDD Guard is an npm package providing automated Test-Driven Development enforcement for AI agents, specifically within the Claude Code environment. It is currently at version 1.6.3 and exhibits a rapid release cadence, with frequent updates addressing bugs, introducing new features, and enhancing refactoring capabilities. Its primary function is to ensure AI agents adhere strictly to TDD principles by proactively blocking actions that violate test-first or minimal implementation rules, such as adding code without accompanying failing tests or implementing beyond the scope of current test requirements. Key differentiators include its broad multi-language support (e.g., JavaScript, TypeScript, Ruby, Python, Go, Rust, PHP) and integration with numerous test frameworks (including Vitest, Jest, RSpec, and PHPUnit). The package also offers customizable validation rules, lint integration for automated refactoring support, and granular control over validation models and session management.

Common errors

```
Plugin blocked action: Premature implementation. Add a failing test first.
```
cause Attempting to add or modify implementation code before a corresponding failing test exists, or engaging in certain refactor patterns not recognized by older validator versions.

fix Ensure a failing test is present that requires the new code. If refactoring, ensure you are on TDD Guard v1.6.3+ which has improved refactor recognition. Consider the 'adjusting an implementation's signature' or 'tidying existing tests' patterns now allowed.
```
Error: Node.js version is too old. TDD Guard requires Node.js >=22.0.0.
```
cause The system's Node.js version does not meet the minimum requirement specified in the package's `engines` field.

fix Update your Node.js installation to version 22.0.0 or later. Use a Node.js version manager like `nvm` (`nvm install 22 && nvm use 22`) for easier management.
```
Custom validation rules in .claude/tdd-guard/data/instructions.md are not working or outdated.
```
cause After updating TDD Guard, the custom `instructions.md` file was not refreshed or merged with new default rules, leading to unexpected validation behavior.

fix Backup your custom `instructions.md` file. Delete the original `.claude/tdd-guard/data/instructions.md`. Start a new Claude Code session to let TDD Guard regenerate the latest default instructions. Then, manually re-apply your specific customizations to the new file.

Warnings

breaking The `VitestReporter` constructor signature changed in `tdd-guard-vitest` v0.2.0. It now expects a single options object `{ projectRoot: string }` instead of a direct path string or `Storage` instance.
Fix: Update `VitestReporter` instantiation from `new VitestReporter('/path/to/project')` to `new VitestReporter({ projectRoot: '/path/to/project' })` in your `vitest.config.ts` or similar.
gotcha Customized validation rules in `.claude/tdd-guard/data/instructions.md` are not automatically updated when the plugin is upgraded. This means new improvements or bug fixes to the core validation logic may not apply.
Fix: Back up your custom `instructions.md`, delete the old file, and start a new Claude Code session to regenerate the default, updated instructions. Then, manually reapply your customizations.
gotcha Older versions of TDD Guard (pre-1.6.x) frequently blocked legitimate refactoring activities, such as moving type declarations, extracting functions, or tidying tests, as 'premature implementation'.
Fix: Upgrade to TDD Guard v1.6.3 or newer to benefit from improved refactor recognition during green-state operations. If on an older version, be mindful of these blocks and adjust your workflow or update the plugin.
gotcha TDD Guard requires Node.js version 22 or higher to run. Using older Node.js versions will result in installation or runtime errors.
Fix: Ensure your development environment is running Node.js 22.0.0 or a newer compatible version. Use a version manager like `nvm` to easily switch Node.js versions.
security A Time-of-Check to Time-of-Use (TOCTOU) race condition in file content reading (CodeQL `js/file-system-race`) was identified and patched.
Fix: Upgrade to TDD Guard v1.5.1 or newer to mitigate this security vulnerability related to file system operations.

Install

npm install tdd-guard npm
yarn add tdd-guard yarn
pnpm add tdd-guard pnpm

Imports

VitestReporter
wrong:
```
import { VitestReporter } from 'tdd-guard';
const VitestReporter = require('tdd-guard/vitest');
```
correct:
```
import { VitestReporter } from 'tdd-guard/vitest';
```
The `VitestReporter` is a named export from the dedicated 'tdd-guard/vitest' entry point. The constructor signature changed significantly in `tdd-guard-vitest` v0.2.0.
RspecReporter
wrong:
```
const RspecReporter = require('tdd-guard/rspec');
```
correct:
```
import { RspecReporter } from 'tdd-guard/rspec';
```
Load language-specific reporters from their respective sub-paths. `tdd-guard` is primarily ESM-first for its exposed utilities.
MinitestReporter
wrong:
```
import MinitestReporter from 'tdd-guard/minitest';
```
correct:
```
import { MinitestReporter } from 'tdd-guard/minitest';
```
Ensure named imports for specific reporters, as they are not default exports from their sub-modules.

Quickstart

Demonstrates the initial setup commands within Claude Code to install and configure TDD Guard.

/plugin marketplace add nizos/tdd-guard
/plugin install tdd-guard@tdd-guard
/tdd-guard:setup

# After installation, you might need to restart your terminal session or IDE extension for the setup skill to appear.
# You can then start a Claude Code session, and TDD Guard will begin enforcing TDD principles.
# Example: If you try to write code without a failing test, it will block the action.

view raw JSON →