Skip to main content
skill CX Codex

tdd-workflow · worldflowai — Claude Code skill: what it does, how to install

tdd-workflow makes the agent write tests before code and keep coverage at 80% or higher across unit, integration and Playwright E2E suites.

MIT ★ 6,739 updated 2026-01-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
Open on GitHub

What tdd-workflow does

The skill switches on when the agent adds a feature, fixes a bug, refactors code or creates an API endpoint. Work then follows seven steps: write the user journey, turn it into test cases, run npm test and watch them fail, add the smallest implementation that passes, run the suite again, refactor, check coverage with npm run test:coverage.

Coverage has to reach 80% across unit, integration and E2E tests combined. The skill ships patterns for each: component tests with Jest or Vitest and @testing-library/react, route handler tests for Next.js, browser flows in Playwright. A separate section covers mocks for Supabase, Redis and OpenAI calls so tests stay offline.

File layout is spelled out as well. Unit tests sit beside components as Button.test.tsx, integration tests beside route.ts, Playwright specs in e2e/. The last step calls npm run test:coverage, so that script has to exist in package.json.

What it helps with

  • write failing tests before the first line of a feature
  • split unit, integration and E2E coverage across the repo
  • mock Supabase, Redis and OpenAI calls in tests
  • push coverage to 80% before merging
  • turn a user story into test cases

Example prompts for the agent

  • Add semantic market search, tests first, then the implementation
  • Fix the empty-query bug starting from a failing test in route.test.ts
  • Run npm run test:coverage and list what is missing below 80%

How to install tdd-workflow

1Plugin marketplace

/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

This installs the whole everything-claude-code plugin with all its skills

2Skills CLI (Vercel)

npx skills add WorldFlowAI/everything-claude-code --skill tdd-workflow -a claude-code

3Manually: put the files in place

~/.claude/skills/tdd-workflow/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tdd-workflow/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tdd-workflow

How do I install tdd-workflow in Claude Code?

Run /plugin marketplace add WorldFlowAI/everything-claude-code, then /plugin install everything-claude-code@everything-claude-code. The skill comes with the plugin.

What does tdd-workflow do?

It keeps the agent inside the TDD loop: tests come first, they run until green, and the code is refactored afterwards. Coverage is verified as a separate step.

Which test types does it require?

Unit tests for functions and components, integration tests for endpoints and database work, and Playwright E2E flows. Combined coverage must stay at 80% or above.

Source text

SKILL.md · MIT
---
name: tdd-workflow
description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
---

# Test-Driven Development Workflow

This skill ensures all code development follows TDD principles with comprehensive test coverage.

## When to Activate

- Writing new features or functionality
- Fixing bugs or issues
- Refactoring existing code
- Adding API endpoints
- Creating new components

## Core Principles

### 1. Tests BEFORE Code
ALWAYS write tests first, then implement code to make tests pass.

### 2. Coverage Requirements
- Minimum 80% coverage (unit + integration + E2E)
- All edge cases covered
- Error scenarios tested
- Boundary conditions verified

### 3. Test Types

#### Unit Tests
- Individual functions and utilities
- Component logic
- Pure functions
- Helpers and utilities

#### Integration Tests
- API endpoints
- Database operations
- Service interactions
- External API calls

#### E2E Tests (Playwright)
- Critical user flows
- Complete workflows
- Browser automation
- UI interactions

## TDD Workflow Steps

### Step 1: Write User Journeys
```
As a [role], I want to [action], so that [benefit]

Example:
As a user, I want to search for markets semantically,
so that I can find relevant markets even without exact keywords.
```

### Step 2: Generate Test Cases
For each user journey, create comprehensive test cases:

```typescript
describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {
    // Test implementation
  })

  it('handles empty query gracefully', async () => {
    // Test edge case
  })

  it('falls back to substring search when Redis unavailable', async () => {
    // Test fallback behavior
  })

  it('sorts results by similarity score', async () => {
    // Test sorting logic
  })
})
```

### Step 3: Run Tests (They Should Fail)
```bash
npm test
# Tests should fail - we haven't implemented yet
```

### Step 4: Implement Code
Write minimal code to make tests pass:

```typescript
// Implementation guided by tests
export async function searchMarkets(query: string) {
  // Implementation here
}
```

### Step 5: Run Tests Again
```bash
npm test
# Tests should now pass
```

### Step 6: Refactor
Improve code quality while keeping tests green:
- Remove duplication
- Improve naming
- Optimize performance
- Enhance readability

### Step 7: Verify Coverage
```bash
npm run test:coverage
# Verify 80%+ coverage achieved
```

## Testing Patterns

### Unit Test Pattern (Jest/Vitest)
```typescript
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'

describe('Button Component', () => {
  it('renders with correct text', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('calls onClick when clicked', () => {
    const handleClick = jest.fn()
    render(<Button onClick={handleClick}>Click</Button>)

    fireEvent.click(screen.getByRole('button'))

    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('is disabled when disabled prop is true', () => {
    render(<Button disabled>Click</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
  })
})
```

### API Integration Test Pattern
```typescript
import { NextRequest } from 'next/server'
import { GET } from './route'

describe('GET /api/markets', () => {
  it('returns markets successfully', async () => {
    const request = new NextRequest('http://localhost/api/markets')
    const response = await GET(request)
    const data = await response.json()

    expect(response.status).toBe(200)
    expect(data.success).toBe(true)
    expect(Array.isArray(data.data)).toBe(true)
  })

  it('validates query parameters', async () => {
    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
    const response = await GET(request)

    expect(response.status).toBe(400)
  })

  it('handles database errors gracefully', async () => {
    // Mock database failure
    const request = new NextRequest('http://localhost/api/markets')
    // Test error handling
  })
})
```

### E2E Test Pattern (Playwright)
```typescript
import { test, expect } from '@playwright/test'

test('user can search and filter markets', async ({ page }) => {
  // Navigate to markets page
  await page.goto('/')
  await page.click('a[href="/markets"]')

  // Verify page loaded
  await expect(page.locator('h1')).toContainText('Markets')

  // Search for markets
  await page.fill('input[placeholder="Search markets"]', 'election')

  // Wait for debounce and results
  await page.waitForTimeout(600)

  // Verify search results displayed
  const results = page.locator('[data-testid="market-card"]')
  await expect(results).toHaveCount(5, { timeout: 5000 })

  // Verify results contain search term
  const firstResult = results.first()
  await expect(firstResult).toContainText('election', { ignoreCase: true })

  // Filter by status
  await page.click('button:has-text("Active")')

  // Verify filtered results
  await expect(results).toHaveCount(3)
})

test('user can create a new market', async ({ page }) => {
  // Login first
  await page.goto('/creator-dashboard')

  // Fill market creation form
  await page.fill('input[name="name"]', 'Test Market')
  await page.fill('textarea[name="description"]', 'Test description')
  await page.fill('input[name="endDate"]', '2025-12-31')

  // Submit form
  await page.click('button[type="submit"]')

  // Verify success message
  await expect(page.locator('text=Market created successfully')).toBeVisible()

  // Verify redirect to market page
  await expect(page).toHaveURL(/\/markets\/test-market/)
})
```

## Test File Organization

```
src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx          # Unit tests
│   │   └── Button.stories.tsx       # Storybook
│   └── MarketCard/
│       ├── MarketCard.tsx
│       └── MarketCard.test.tsx
├── app/
│   └── api/
│       └── markets/
│           ├── route.ts
│           └── route.test.ts         # Integration tests
└── e2e/
    ├── markets.spec.ts               # E2E tests
    ├── trading.spec.ts
    └── auth.spec.ts
```

## Mocking External Services

### Supabase Mock
```typescript
jest.mock('@/lib/supabase', () => ({
  supabase: {
    from: jest.fn(() => ({
      select: jest.fn(() => ({
        eq: jest.fn(() => Promise.resolve({
          data: [{ id: 1, name: 'Test Market' }],
          error: null
        }))
      }))
    }))
  }
}))
```

### Redis Mock
```typescript
jest.mock('@/lib/redis', () => ({
  searchMarketsByVector: jest.fn(() => Promise.resolve([
    { slug: 'test-market', similarity_score: 0.95 }
  ])),
  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
```

### OpenAI Mock
```typescript
jest.mock('@/lib/openai', () => ({
  generateEmbedding: jest.fn(() => Promise.resolve(
    new Array(1536).fill(0.1) // Mock 1536-dim embedding
  ))
}))
```

## Test Coverage Verification

### Run Coverage Report
```bash
npm run test:coverage
```

### Coverage Thresholds
```json
{
  "jest": {
    "coverageThresholds": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}
```

## Common Testing Mistakes to Avoid

### ❌ WRONG: Testing Implementation Details
```typescript
// Don't test internal state
expect(component.state.count).toBe(5)
```

### ✅ CORRECT: Test User-Visible Behavior
```typescript
// Test what users see
expect(screen.getByText('Count: 5')).toBeInTheDocument()
```

### ❌ WRONG: Brittle Selectors
```typescript
// Breaks easily
await page.click('.css-class-xyz')
```

### ✅ CORRECT: Semantic Selectors
```typescript
// Resilient to changes
await page.click('button:has-text("Submit")')
await page.click('[data-testid="submit-button"]')
```

### ❌ WRONG: No Test Isolation
```typescript
// Tests depend on each other
test('creates user', () => { /* ... */ })
test('updates same user', () => { /* depends on previous test */ })
```

### ✅ CORRECT: Independent Tests
```typescript
// Each test sets up its own data
test('creates user', () => {
  const user = createTestUser()
  // Test logic
})

test('updates user', () => {
  const user = createTestUser()
  // Update logic
})
```

## Continuous Testing

### Watch Mode During Development
```bash
npm test -- --watch
# Tests run automatically on file changes
```

### Pre-Commit Hook
```bash
# Runs before every commit
npm test && npm run lint
```

### CI/CD Integration
```yaml
# GitHub Actions
- name: Run Tests
  run: npm test -- --coverage
- name: Upload Coverage
  uses: codecov/codecov-action@v3
```

## Best Practices

1. **Write Tests First** - Always TDD
2. **One Assert Per Test** - Focus on single behavior
3. **Descriptive Test Names** - Explain what's tested
4. **Arrange-Act-Assert** - Clear test structure
5. **Mock External Dependencies** - Isolate unit tests
6. **Test Edge Cases** - Null, undefined, empty, large
7. **Test Error Paths** - Not just happy paths
8. **Keep Tests Fast** - Unit tests < 50ms each
9. **Clean Up After Tests** - No side effects
10. **Review Coverage Reports** - Identify gaps

## Success Metrics

- 80%+ code coverage achieved
- All tests passing (green)
- No skipped or disabled tests
- Fast test execution (< 30s for unit tests)
- E2E tests cover critical user flows
- Tests catch bugs before production

---

**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

© Affaan Mustafa · MIT · WorldFlowAI/everything-claude-code

Similar skills

All skills for Testing and QA →

tdd-workflow by other authors comes first.

tdd-workflow ruvnet tdd-workflow — a skill that walks the agent through London School TDD: a failing test against mocks, the smallest passing implementation, then refactor. Steps are logged through MCP hooks. CX Codex +1 743installs tdd-workflow travisjneuman tdd-workflow — a skill for Claude Code, Codex, Cursor and other platforms that enforces test-driven development: first a failing test (RED), then minimal code to pass (GREEN), then refactoring. CX Codex +1 141installs tdd-workflow davila7 tdd-workflow guides Claude Code through the test-driven development loop: write a failing test first, make it pass with simple code, then refactor. CX Codex +1 194installs tdd-guide alirezarezvani tdd-guide is a Claude Code skill that generates tests from requirements or code, reviews coverage, and guides Red-Green-Refactor to find untested scenarios. CX Codex +1 ★ 907repo stars tdd glebis tdd runs test-driven development cycles with strict context separation across subagents. Useful for writing clean features and reproducing bugs. CX Codex +1 262installs tdd-orchestrator davila7 tdd-orchestrator is a Claude Code skill that orchestrates test-driven development through red-green-refactor cycles. It coordinates multi-agent testing workflows and verifies test-first compliance. CX Codex +1 51installs test-automator zhaono1 test-automator writes unit, integration and E2E tests, sets up a framework and reports coverage. Useful when a project has few tests or they have drifted. CX Codex +1 823installs tdd-red Seth Hobson tdd-red — a slash command that writes only tests which must fail, and leaves production code alone. The first step of TDD, when behavior needs pinning down before implementation. CX Codex +1 ★ 42,780repo stars TDD Red Phase - Write Failing Tests First official github The TDD Red Phase - Write Failing Tests First subagent pulls GitHub issue context from branch names and creates failing tests for acceptance criteria before code is written. It enforces the red stage of TDD. CX Codex +1 ★ 41,430repo stars

From the same set29

The whole set →
tdd-guide The tdd-guide subagent guides feature work, bug fixes, and refactoring through a test-first workflow. It also checks test coverage against an 80% target. CX Codex ★ 6,739repo stars refactor-cleaner refactor-cleaner is a Claude Code subagent that finds and removes unused code, duplicates, and dependencies. It runs knip, depcheck, and ts-prune during codebase cleanup. CX Codex ★ 6,739repo stars tdd tdd enforces a strict test-driven development cycle in Claude Code by writing failing tests first, implementing minimal code, and checking for 80%+ coverage. CX Codex +1 ★ 6,739repo stars project-guidelines-example The project-guidelines-example skill gives an agent a sample project’s architecture, file layout, code patterns, and testing commands to reference while working on a codebase. CX Codex +1 ★ 6,739repo stars doc-updater doc-updater — a subagent that updates architecture codemaps and project guides from code. Helpful when repo structure evolves faster than manuals. CX Codex ★ 6,739repo stars build-error-resolver The build-error-resolver subagent diagnoses build and TypeScript failures, then applies small fixes without architectural changes. Use it when a build or type check breaks. CX Codex ★ 6,739repo stars security-reviewer The security-reviewer subagent for Claude Code scans code for SQL injections, hardcoded secrets, unsafe crypto, and OWASP Top 10 issues after work on user input, authentication, or API endpoints. CX Codex ★ 6,739repo stars e2e-runner e2e-runner automates Playwright end-to-end test execution and creation in Claude Code. It structures tests with Page Objects, captures debug traces, and quarantines unstable tests. CX Codex ★ 6,739repo stars

Project sponsors

Companies that keep this analytics open