Test-Driven Development Skill

Enforce test-first development workflow for JavaScript and TypeScript files.

Activation Rules

This skill auto-activates when:

• Creating a NEW JavaScript/TypeScript file (not editing existing)
• File is in a testable location (src/, lib/, components/, scripts/, services/, api/)

This skill stays SILENT when:

• Editing an existing file (test reminder only if test is missing)
• File is a config file (.config.js, .config.ts)
• File is in skip locations (see Skip Detection)
• Session has prototyping mode enabled (/tdd off)
• File is generated code (.generated., *.g.ts)

Mode Configuration

Advisory Mode (Default)

• Reminds to write tests first
• Provides test file path suggestion
• Shows skeleton test template
• Allows proceeding without tests

Strict Mode (Opt-in)

• Checks for test file existence before allowing implementation
• If test missing: outputs blocking message, suggests test file creation
• Composes with testing skill to scaffold test

TDD Workflow

1. THINK: Define what the code should do
       |
2. TEST: Write a failing test first
       |
3. CODE: Write minimal code to pass
       |
4. REFACTOR: Clean up while tests pass
       |
5. REPEAT: Add next test case

The cycle in short:

RED -> GREEN -> REFACTOR -> REPEAT
 |       |          |
 |       |          +-- Clean up code, tests still pass
 |       +-- Write minimal code to pass test
 +-- Write a failing test first

Test File Location Convention

Compose With Testing Skills

Based on file location, auto-compose with appropriate testing skill:

Skip Detection

Automatic Skips

Session-Based Skips

When prototyping mode is active (/tdd off), TDD checks are suspended.

Red Flags

Quick Start Template

When creating a test first, use this skeleton:

import { describe, it } from 'node:test';
import assert from 'node:assert';

describe('ModuleName', () => {
  describe('functionName', () => {
    it('should handle expected input', () => {
      // Arrange
      const input = 'test';

      // Act
      const result = functionUnderTest(input);

      // Assert
      assert.strictEqual(result, expected);
    });

    it('should handle edge case', () => {
      // Test edge case
    });

    it('should throw on invalid input', () => {
      assert.throws(() => {
        functionUnderTest(null);
      });
    });
  });
});

Mode Toggle Commands

Configuration

Project defaults in .claude/config/tdd.json:

{
  "mode": "advisory",
  "testDirectory": "test",
  "testSuffix": ".test"
}

Integration Points

Pre-Flight Check

TDD adds to JavaScript pre-flight checklist:

• Test file exists or will be created first
• Test covers the behavior being implemented

Completion Check

Before marking JS/TS file complete:

• Corresponding test file exists
• Tests pass: npm test

Related Skills

• unit-testing - Node.js native test runner patterns
• backend-testing - API and database testing
• vitest - Vite-based project testing
• e2e-testing - Playwright browser testing
• pre-flight-check - Git workflow and approach validation
• javascript-author - JavaScript coding patterns