TDD Guide Agent

Overview

The tdd-guide agent is a Test-Driven Development specialist who ensures all code is developed test-first with comprehensive coverage (80%+ required).

string

default:"tdd-guide"

Agent identifier

string

default:"sonnet"

Uses Claude Sonnet for efficient test generation

array

Available tools: Read, Write, Edit, Bash, Grep

When to Use

Writing new features

Fixing bugs

Refactoring existing code

Ensuring test coverage meets 80%+ threshold

The tdd-guide agent activates PROACTIVELY when writing new features, fixing bugs, or refactoring code.

Core Responsibilities

Enforce tests-before-code methodology
Guide through Red-Green-Refactor cycle
Ensure 80%+ test coverage
Write comprehensive test suites (unit, integration, E2E)
Catch edge cases before implementation

TDD Workflow

The agent follows the classic Red-Green-Refactor cycle:

1. Write Test First (RED)

Write a failing test that describes the expected behavior.

// Write the test BEFORE implementation
test('calculateTotal should sum item prices', () => {
  const items = [{ price: 10 }, { price: 20 }];
  expect(calculateTotal(items)).toBe(30);
});

2. Run Test — Verify it FAILS

npm test
# Test should FAIL because calculateTotal doesn't exist yet

If the test passes immediately, you haven’t written a proper test!

3. Write Minimal Implementation (GREEN)

Only enough code to make the test pass.

function calculateTotal(items: Array<{ price: number }>): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

4. Run Test — Verify it PASSES

npm test
# Test should now PASS

5. Refactor (IMPROVE)

Remove duplication, improve names, optimize — tests must stay green.

6. Verify Coverage

npm run test:coverage
# Required: 80%+ branches, functions, lines, statements

Coverage must be at least 80% for all metrics

Test Types Required

Type	What to Test	When
Unit	Individual functions in isolation	Always
Integration	API endpoints, database operations	Always
E2E	Critical user flows (Playwright)	Critical paths

Unit Tests

Test individual functions without external dependencies:

import { describe, it, expect } from 'vitest';
import { formatCurrency } from './utils';

describe('formatCurrency', () => {
  it('formats USD correctly', () => {
    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56');
  });

  it('handles zero', () => {
    expect(formatCurrency(0, 'USD')).toBe('$0.00');
  });

  it('handles negative amounts', () => {
    expect(formatCurrency(-50, 'USD')).toBe('-$50.00');
  });
});

Integration Tests

Test API endpoints and database operations:

import { describe, it, expect, beforeEach } from 'vitest';
import { createUser, getUser } from './api/users';

describe('User API', () => {
  beforeEach(async () => {
    // Clear database before each test
    await db.users.deleteAll();
  });

  it('creates and retrieves user', async () => {
    const user = await createUser({ email: 'test@example.com' });
    const retrieved = await getUser(user.id);
    expect(retrieved.email).toBe('test@example.com');
  });
});

E2E Tests

Test critical user journeys:

import { test, expect } from '@playwright/test';

test('user can sign up and log in', async ({ page }) => {
  await page.goto('/signup');
  await page.fill('[data-testid="email"]', 'user@example.com');
  await page.fill('[data-testid="password"]', 'secure123');
  await page.click('[data-testid="submit"]');
  
  await expect(page).toHaveURL('/dashboard');
  await expect(page.locator('[data-testid="welcome"]')).toBeVisible();
});

Edge Cases You MUST Test

Never skip edge case testing!

Null/Undefined input
Empty arrays/strings
Invalid types passed
Boundary values (min/max)
Error paths (network failures, DB errors)
Race conditions (concurrent operations)
Large data (performance with 10k+ items)
Special characters (Unicode, emojis, SQL chars)

describe('validateEmail edge cases', () => {
  it('rejects null', () => {
    expect(validateEmail(null)).toBe(false);
  });

  it('rejects empty string', () => {
    expect(validateEmail('')).toBe(false);
  });

  it('rejects invalid format', () => {
    expect(validateEmail('notanemail')).toBe(false);
  });

  it('handles unicode characters', () => {
    expect(validateEmail('user@例え.jp')).toBe(true);
  });
});

Test Anti-Patterns to Avoid

Common mistakes that reduce test value:

Anti-Pattern	Problem	Solution
Testing implementation details	Tests break on refactor	Test behavior, not internals
Tests depending on each other	Shared state causes failures	Independent tests
Asserting too little	Passing tests that don’t verify anything	Specific assertions
Not mocking external dependencies	Flaky tests, slow tests	Mock Supabase, Redis, OpenAI, etc.
Using real timers	Non-deterministic tests	Use `vi.useFakeTimers()`

Bad: Testing Implementation Details

// BAD: Testing internal state
test('counter increments internal value', () => {
  const counter = new Counter();
  counter.increment();
  expect(counter._value).toBe(1); // Testing private property
});

Good: Testing Behavior

// GOOD: Testing observable behavior
test('counter increments', () => {
  const counter = new Counter();
  counter.increment();
  expect(counter.getValue()).toBe(1); // Testing public API
});

Mocking External Dependencies

Always mock external services to keep tests fast and deterministic:

import { vi } from 'vitest';
import { supabase } from './lib/supabase';

// Mock Supabase
vi.mock('./lib/supabase', () => ({
  supabase: {
    from: vi.fn(() => ({
      select: vi.fn().mockResolvedValue({
        data: [{ id: 1, name: 'Test' }],
        error: null,
      }),
    })),
  },
}));

Quality Checklist

Coverage Requirements

All public functions have unit tests
All API endpoints have integration tests
Critical user flows have E2E tests
Coverage is 80%+ (branches, functions, lines, statements)

Edge Cases

Null/undefined inputs tested
Empty arrays/strings tested
Invalid type inputs tested
Boundary values tested
Error paths tested (not just happy path)

Test Quality

External dependencies mocked
Tests are independent (no shared state)
Assertions are specific and meaningful
Test names clearly describe behavior
Tests run fast (<100ms per unit test)

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run with coverage report
npm run test:coverage

# Run specific test file
npm test -- src/utils.test.ts

# Run tests matching pattern
npm test -- --grep="calculateTotal"

Usage Example

# Invoke tdd-guide directly
ask tdd-guide "Write tests for user authentication flow"

# Or let it activate automatically
ask "Implement password reset functionality"
# → tdd-guide activates and writes tests FIRST

Success Criteria

Tests written before implementation

All tests pass

Coverage meets 80%+ threshold

Edge cases covered

External dependencies mocked

Tests are independent and fast

For detailed mocking patterns and framework-specific examples, use the tdd-workflow skill.

Overview

Development Agents

Specialized Agents

Language-Specific Agents

Overview

When to Use

Core Responsibilities

TDD Workflow

1. Write Test First (RED)

2. Run Test — Verify it FAILS

3. Write Minimal Implementation (GREEN)

4. Run Test — Verify it PASSES

5. Refactor (IMPROVE)

6. Verify Coverage

Test Types Required

Unit Tests

Integration Tests

E2E Tests

Edge Cases You MUST Test

Test Anti-Patterns to Avoid

Bad: Testing Implementation Details

Good: Testing Behavior

Mocking External Dependencies

Quality Checklist

Running Tests

Usage Example

Success Criteria

​Overview

​When to Use

​Core Responsibilities

​TDD Workflow

​1. Write Test First (RED)

​2. Run Test — Verify it FAILS

​3. Write Minimal Implementation (GREEN)

​4. Run Test — Verify it PASSES

​5. Refactor (IMPROVE)

​6. Verify Coverage

​Test Types Required

​Unit Tests

​Integration Tests

​E2E Tests

​Edge Cases You MUST Test

​Test Anti-Patterns to Avoid

​Bad: Testing Implementation Details

​Good: Testing Behavior

​Mocking External Dependencies

​Quality Checklist

​Running Tests

​Usage Example

​Success Criteria

Overview

When to Use

Core Responsibilities

TDD Workflow

1. Write Test First (RED)

2. Run Test — Verify it FAILS

3. Write Minimal Implementation (GREEN)

4. Run Test — Verify it PASSES

5. Refactor (IMPROVE)

6. Verify Coverage

Test Types Required

Unit Tests

Integration Tests

E2E Tests

Edge Cases You MUST Test

Test Anti-Patterns to Avoid

Bad: Testing Implementation Details

Good: Testing Behavior

Mocking External Dependencies

Quality Checklist

Running Tests

Usage Example

Success Criteria