Tdd Workflow

TDD Workflow

Enforce test-driven development: write tests first, implement to pass, then refactor.

The Cycle: RED -> GREEN -> REFACTOR

RED: Write Failing Tests

Define expected behavior before writing any implementation:

describe('searchMarkets', () => {
  it('returns relevant markets for query', async () => {
    const results = await searchMarkets('election')
    expect(results).toHaveLength(5)
    expect(results[0].relevanceScore).toBeGreaterThan(0.8)
  })

  it('returns empty array for no matches', async () => {
    const results = await searchMarkets('zzz_nonexistent')
    expect(results).toEqual([])
  })

  it('handles empty query gracefully', async () => {
    const results = await searchMarkets('')
    expect(results).toEqual([])
  })
})

Run tests -- they MUST fail:

npm test -- --run [test-file]

GREEN: Write Minimal Implementation

Write just enough code to make all tests pass. No more.

npm test -- --run [test-file]
# All tests should now pass

REFACTOR: Improve While Green

Improve code quality with tests as safety net:

• Remove duplication
• Improve naming
• Optimize performance
• Extract helpers

Run tests after each change to confirm nothing broke.

Test Types and When to Use

| Type | What to Test | Tool | Speed Target | |------|-------------|------|-------------| | Unit | Single function/class, pure logic | Vitest/Jest |

Coverage Requirement

Target 80%+ across all metrics:

npm run test:coverage

Check branches, functions, lines, and statements individually.

Testing Rules

1. Test behavior, not implementation

• WRONG: expect(component.state.count).toBe(5)
• RIGHT: expect(screen.getByText('Count: 5')).toBeInTheDocument()

1. Each test is independent -- set up own data, no shared mutable state

1. Use semantic selectors

• WRONG: page.click('.css-xyz')
• RIGHT: page.click('[data-testid="submit"]') or page.click('button:has-text("Submit")')

1. Mock external dependencies -- isolate the unit under test

1. Test edge cases -- null, undefined, empty, boundary values, error paths

1. Arrange-Act-Assert structure in every test

Mocking Patterns

Database/ORM

vi.mock('@/lib/prisma', () => ({
  prisma: { user: { findUnique: vi.fn() } }
}))

External APIs

vi.mock('@/lib/external-api', () => ({
  fetchData: vi.fn(() => Promise.resolve({ data: 'mocked' }))
}))

Error Handling

• If tests pass immediately (no RED phase): the test is not testing anything meaningful. Add assertions that verify specific behavior.
• If coverage is below 80%: run npm run test:coverage and check the uncovered lines report. Add tests for missed branches.
• If E2E tests are flaky: replace waitForTimeout with waitForSelector or expect().toBeVisible(). Never use fixed timeouts.
• If mocks leak between tests: add vi.restoreAllMocks() in afterEach or use vi.mock at module level.
• If tests are slow (unit > 50ms): check for unmocked network calls or missing test isolation.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Cor-Incorporated
• Source: Cor-Incorporated/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.