tdd-workflow

TDD Workflow for React

Quality Gate Thresholds (ENFORCED)

Gate	Threshold	Status
TypeScript	0 type errors	REQUIRED
Tests	100% pass (0 failures)	REQUIRED
Coverage	≥ 80% line coverage	REQUIRED
ESLint	0 errors (warnings OK)	REQUIRED
Build	must pass	REQUIRED

⛔ BLOCKING: TDD workflow is NOT complete until ALL gates pass.

Step 0: Verify Coverage Configuration ⚠️ PREREQUISITE

Before starting ANY TDD cycle, verify Vitest coverage thresholds are configured:

grep -l "thresholds" vitest.config.ts

If NOT configured, update vitest.config.ts FIRST:

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './src/test/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'text-summary', 'html', 'lcov'],
      reportsDirectory: './coverage',
      thresholds: {
        lines: 80,
        branches: 70,
        functions: 80,
        statements: 80,
      },
      include: ['src/**/*.{ts,tsx}'],
      exclude: [
        'node_modules/',
        'src/test/',
        'src/**/*.d.ts',
        'src/main.tsx',
        'src/**/*.test.{ts,tsx}',
      ],
    },
  },
});

⛔ Do NOT start TDD without coverage thresholds configured.

The Red-Green-Refactor Cycle

    ┌──────────────────┐
    │       RED        │
    │  Write a failing │
    │      test        │
    └────────┬─────────┘
             │
             ▼
    ┌──────────────────┐
    │      GREEN       │
    │  Write minimal   │
    │  code to pass    │
    └────────┬─────────┘
             │
             ▼
    ┌──────────────────┐
    │    REFACTOR      │
    │  Improve code    │
    │  keeping green   │
    └────────┬─────────┘
             │
             └─────────────────┐
                               │
             Repeat for        ▼
             next behavior  ◄──┘

Step-by-Step Process for React Components

RED Phase: Write a Failing Test

import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import TodoItem from './TodoItem';

describe('TodoItem', () => {
  it('should render the todo title', () => {
    render(
      <TodoItem
        id="1"
        title="Test todo"
        completed={false}
        onToggle={() => {}}
        onDelete={() => {}}
      />
    );

    expect(screen.getByText('Test todo')).toBeInTheDocument();
  });
});

Run: npm test -- TodoItem.test.tsx

Expected: FAIL (component doesn't exist yet)

GREEN Phase: Write Minimal Code

// TodoItem.tsx
interface TodoItemProps {
  id: string;
  title: string;
  completed: boolean;
  onToggle: (id: string) => void;
  onDelete: (id: string) => void;
}

export default function TodoItem({ title }: TodoItemProps) {
  return <div>{title}</div>;
}

Run: npm test -- TodoItem.test.tsx

Expected: PASS

REFACTOR Phase: Improve While Green

// Add proper structure and styling
export default function TodoItem({
  id,
  title,
  completed,
  onToggle,
  onDelete,
}: TodoItemProps) {
  return (
    <li className="flex items-center gap-3 p-4 bg-white rounded-lg shadow-sm">
      <input
        type="checkbox"
        checked={completed}
        onChange={() => onToggle(id)}
      />
      <span className={completed ? 'line-through text-gray-400' : ''}>
        {title}
      </span>
      <button onClick={() => onDelete(id)}>Delete</button>
    </li>
  );
}

Run: npm test

Expected: ALL PASS

Continue with Next Behavior

it('should show checkbox as checked when completed', () => {
  render(<TodoItem {...defaultProps} completed={true} />);
  expect(screen.getByRole('checkbox')).toBeChecked();
});

Repeat RED → GREEN → REFACTOR.

Component TDD Strategy

Order of Tests

1. Render test - Component renders without error
2. Content test - Correct content is displayed
3. State test - State is reflected in UI
4. Interaction test - User interactions work
5. Edge case test - Empty, null, error states

Example: TodoInput Component

describe('TodoInput', () => {
  // 1. Renders
  it('should render an input field', () => {
    render(<TodoInput onAdd={() => {}} />);
    expect(screen.getByRole('textbox')).toBeInTheDocument();
  });

  // 2. Content
  it('should render a submit button', () => {
    render(<TodoInput onAdd={() => {}} />);
    expect(screen.getByRole('button', { name: /add/i })).toBeInTheDocument();
  });

  // 3. State
  it('should update input value on change', async () => {
    const user = userEvent.setup();
    render(<TodoInput onAdd={() => {}} />);

    await user.type(screen.getByRole('textbox'), 'New todo');
    expect(screen.getByRole('textbox')).toHaveValue('New todo');
  });

  // 4. Interaction
  it('should call onAdd with input value on submit', async () => {
    const onAdd = vi.fn();
    const user = userEvent.setup();
    render(<TodoInput onAdd={onAdd} />);

    await user.type(screen.getByRole('textbox'), 'New todo');
    await user.click(screen.getByRole('button', { name: /add/i }));

    expect(onAdd).toHaveBeenCalledWith('New todo');
  });

  // 5. Edge cases
  it('should not call onAdd when input is empty', async () => {
    const onAdd = vi.fn();
    const user = userEvent.setup();
    render(<TodoInput onAdd={onAdd} />);

    await user.click(screen.getByRole('button', { name: /add/i }));

    expect(onAdd).not.toHaveBeenCalled();
  });

  it('should show error message when submitting empty', async () => {
    const user = userEvent.setup();
    render(<TodoInput onAdd={() => {}} />);

    await user.click(screen.getByRole('button', { name: /add/i }));

    expect(screen.getByText(/required/i)).toBeInTheDocument();
  });

  it('should clear input after successful submit', async () => {
    const user = userEvent.setup();
    render(<TodoInput onAdd={() => {}} />);

    await user.type(screen.getByRole('textbox'), 'New todo');
    await user.click(screen.getByRole('button', { name: /add/i }));

    expect(screen.getByRole('textbox')).toHaveValue('');
  });
});

Error Recovery Protocol

When a Test Fails Unexpectedly

ATTEMPT 1:
  - Read error message carefully
  - Check the specific assertion that failed
  - Make targeted fix
  - Run test

ATTEMPT 2 (if still failing):
  - Use screen.debug() to see actual DOM
  - Check component props and state
  - Make targeted fix
  - Run test

ATTEMPT 3 (if still failing):
  - Check react-verification skill for error patterns
  - Add console.log to component
  - Make targeted fix
  - Run test

AFTER 3 ATTEMPTS:
  - STOP
  - Summarize what you've tried
  - Ask developer for guidance

Max Retry Rule

Do NOT:

• Keep trying the same fix
• Skip the failing test
• Comment out assertions
• Lower quality thresholds
• Use any type to fix TypeScript errors

DO:

• Diagnose before each fix attempt
• Try DIFFERENT approaches each time
• Use screen.debug() to understand actual state
• Ask for help after 3 attempts

Test Types for React

Unit Tests (Component Tests) - 70%

// Test individual components in isolation
describe('TodoItem', () => {
  it('should render title', () => {});
  it('should call onToggle when clicked', () => {});
});

Integration Tests - 25%

// Test components working together
describe('TodoList with TodoInput', () => {
  it('should add new todo to list', async () => {
    render(<TodoApp />);

    await user.type(screen.getByRole('textbox'), 'New todo');
    await user.click(screen.getByRole('button', { name: /add/i }));

    expect(screen.getByText('New todo')).toBeInTheDocument();
  });
});

E2E Tests - 5%

// Full user flows (use Playwright)
// See e2e-testing plugin

Coverage Guidelines

Component Type	Target	Focus
UI Components	80%+	Rendering, interactions
Form Components	90%+	Validation, submission
Hooks	80%+	State changes, side effects
Utils	90%+	All branches

Coverage Verification ⚠️ MANDATORY

Before declaring any implementation complete, you MUST verify coverage:

# Generate coverage report
npm test -- --coverage --run

# Check coverage in browser
open coverage/lcov-report/index.html

Coverage Thresholds (REQUIRED)

Metric	Minimum	Action if Below
Line Coverage	80%	Add more tests
Branch Coverage	75%	Test if/else paths
Function Coverage	80%	Test all functions
Statement Coverage	80%	Cover all statements

Coverage Verification Steps

1. Run coverage report:

   npm test -- --coverage --run
   

2. Check percentage:

   • Open coverage/lcov-report/index.html
   • Or parse coverage/coverage-summary.json

3. If below 80%:

   • Identify red (uncovered) lines in report
   • Add tests for those code paths
   • Re-run coverage
   • Repeat until ≥ 80%

4. Only then declare done

⛔ NEVER mark complete with coverage < 80%

A pre-completion hook enforces this requirement automatically.

What NOT to Test

• Third-party component internals
• CSS class names (unless behavior-related)
• Implementation details (internal state structure)
• Framework code (React's useState works)

What TO Test

• User-visible behavior
• Component output (what renders)
• User interactions (click, type, submit)
• Props effect on rendering
• Error states
• Loading states
• Empty states

TDD Benefits for React

1. Catches bugs early - Before UI exists
2. Documents behavior - Tests are specifications
3. Enables refactoring - Change with confidence
4. Forces good design - Testable = composable
5. Faster feedback - Run tests, not browser