tdd-guard

library0.5.3jsnpmunverified

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.

testing devops

npm install tdd-guard

github ↗package ↗

INSTALL

IMPORT

SIG · TDD-GUARD

tdd-guard

testingjavascriptv0.5.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VitestReporter

✓ import { VitestReporter } from 'tdd-guard/vitest';

✗ import { VitestReporter } from 'tdd-guard'; const VitestReporter = require('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

✓ import { RspecReporter } from 'tdd-guard/rspec';

✗ const RspecReporter = require('tdd-guard/rspec');

Load language-specific reporters from their respective sub-paths. `tdd-guard` is primarily ESM-first for its exposed utilities.

MinitestReporter

✓ import { MinitestReporter } from 'tdd-guard/minitest';

✗ import MinitestReporter from 'tdd-guard/minitest';

Ensure named imports for specific reporters, as they are not default exports from their sub-modules.

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.

Debug

Known issues

breakingThe `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.

affects: >=vitest-v0.2.0

gotchaCustomized 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.

affects: >=1.6.1

gotchaOlder 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.

affects: <1.6.3

gotchaTDD 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.

affects: >=1.0.0

securityA 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.

affects: <1.5.1

Errors

Common errors & fixes

Plugin blocked action: Premature implementation. Add a failing test first.

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.

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.

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.

Upgrade

Version history

0.5.3latest on npm

Audit

Dependencies

@anthropic-ai/claude-agent-sdkrequiredCore dependency for integrating with Claude Code. Pinned to specific versions in the past to mitigate upstream native-binary resolver bugs.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/nizos/tdd-guard ↗

packagehttps://www.npmjs.com/package/tdd-guard ↗