TDD Workflow

Освойте Test-Driven Development с навыком tdd-workflow для Claude Code. Обеспечьте 80% покрытие тестами с помощью Jest, Vitest и Playwright для надёжной AI-разработки.

Безопасность и тестирование ★ 172,651 GitHub (172,651 ★)

Этот навык предоставляет структурированный фреймворк для реализации Claude строгих принципов разработки через тестирование (TDD). Он проводит ИИ через процесс «красный-зеленый-рефакторинг», требуя, чтобы пользовательские сценарии и падающие тесты были определены до написания любой логики реализации. Используя Jest/Vitest для тестирования логики и Playwright для E2E-сценариев в браузере, он гарантирует, что каждая новая функция, исправление ошибки или рефакторинг подкреплены всеобъемлющей сетью безопасности автоматизированных тестов и проверенными порогами покрытия.

Ключевые особенности

01Принудительное применение автоматизированного рабочего процесса «Красный-Зеленый-Рефакторинг»

02Всестороннее покрытие модульных, интеграционных и E2E-тестов Playwright

03Строгая проверка минимального порога покрытия кода в 80%

04Генерация тестовых сценариев на основе пользовательских путей для планирования функций

05172 651 звезда на GitHub

06Стандартизированные шаблоны имитации для сервисов Redis, Supabase и OpenAI

Варианты использования

01Отладка путем написания падающих воспроизводящих тестов перед применением исправлений

02Рефакторинг устаревшего кода с обеспечением отсутствия функциональных регрессий

03Создание критически важных функций с высокими требованиями к надежности

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.

metadata

origin	version
ECC	1.0

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:

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)

npm test
# Tests should fail - we haven't implemented yet

Step 4: Implement Code

Write minimal code to make tests pass:

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

Step 5: Run Tests Again

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

npm run test:coverage
# Verify 80%+ coverage achieved

Testing Patterns

Unit Test Pattern (Jest/Vitest)

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

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)

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="https://github.com/affaan-m/everything-claude-code/blob/841beea45cb25ba51f29fa45b7e272938d19b80a/.kiro/skills/tdd-workflow//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

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

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

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

npm run test:coverage

Coverage Thresholds

{
  "jest": {
    "coverageThresholds": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

Common Testing Mistakes to Avoid

FAIL: WRONG: Testing Implementation Details

// Don't test internal state
expect(component.state.count).toBe(5)

PASS: CORRECT: Test User-Visible Behavior

// Test what users see
expect(screen.getByText('Count: 5')).toBeInTheDocument()

FAIL: WRONG: Brittle Selectors

// Breaks easily
await page.click('.css-class-xyz')

PASS: CORRECT: Semantic Selectors

// Resilient to changes
await page.click('button:has-text("Submit")')
await page.click('[data-testid="submit-button"]')

FAIL: WRONG: No Test Isolation

// Tests depend on each other
test('creates user', () => { /* ... */ })
test('updates same user', () => { /* depends on previous test */ })

PASS: CORRECT: Independent Tests

// 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

npm test -- --watch
# Tests run automatically on file changes

Pre-Commit Hook

# Runs before every commit
npm test && npm run lint

CI/CD Integration

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

Best Practices

Write Tests First - Always TDD
One Assert Per Test - Focus on single behavior
Descriptive Test Names - Explain what's tested
Arrange-Act-Assert - Clear test structure
Mock External Dependencies - Isolate unit tests
Test Edge Cases - Null, undefined, empty, large
Test Error Paths - Not just happy paths
Keep Tests Fast - Unit tests < 50ms each
Clean Up After Tests - No side effects
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.

🧪 Что это

TDD Workflow — это навык (skill), который внедряет дисциплину разработки через тестирование (Test-Driven Development) прямо в ваш процесс написания кода. Он не просто напоминает писать тесты, а жёстко задаёт пошаговый регламент: сначала тест, потом реализация, потом рефакторинг. Целевая аудитория — разработчики, работающие над новыми функциями, исправлением багов или рефакторингом, особенно в проектах, где требуется высокая надёжность и минимальное количество регрессий.
Ключевое требование — покрытие кода не ниже 80%, включая модульные (unit), интеграционные (integration) и сквозные (E2E) тесты. Навык подходит для проектов на JavaScript/TypeScript, использующих Jest, Playwright и подобные инструменты.

⚙️ Как работает

Процесс строго цикличен и состоит из семи шагов. Нарушать порядок нельзя.

📝 Шаг 1: Формулировка пользовательских историй

Перед написанием кода вы описываете сценарий использования по шаблону:
As a [роль], I want to [действие], so that [польза].
Пример: «Как пользователь, я хочу искать рынки семантически, чтобы находить релевантные результаты без точных ключевых слов». Это даёт контекст и критерии успеха.

🔬 Шаг 2: Генерация тестовых случаев

Для каждой пользовательской истории создаются тесты. Навык предлагает сразу описывать тесты для счастливого пути (happy path), граничных условий и обработки ошибок.
Пример структуры теста на Jest/Vitest:

describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {
    // Тест реализации
  })
  it('handles empty query gracefully', async () => {
    // Проверка граничного случая
  })
  it('falls back to substring search when Redis unavailable', async () => {
    // Тест fallback-поведения
  })
})

💥 Шаг 3: Запуск тестов (они должны упасть)

Запускаем npm test. Тесты обязаны упасть — ведь реализации ещё нет. Этот шаг подтверждает, что тесты работают и действительно проверяют то, что нужно.

💻 Шаг 4: Реализация кода

Пишется минимальный код, достаточный для прохождения проваленных тестов. Никаких избыточных оптимизаций или «на будущее» — только то, что требуется тестами.

export async function searchMarkets(query: string) {
  // Минимальная реализация
}

✅ Шаг 5: Повторный запуск тестов

Снова npm test. На этот раз все тесты должны пройти зелёным. Если нет — возвращаемся к шагу 4.

🧹 Шаг 6: Рефакторинг

Улучшаем код: убираем дублирование, улучшаем именование, оптимизируем производительность, повышаем читаемость. Тесты остаются зелёными — это страховка, что рефакторинг ничего не сломал.

📊 Шаг 7: Проверка покрытия

Команда npm run test:coverage — проверяем, что покрытие кода (ветки, функции, строки, операторы) не ниже 80%. Если ниже — возвращаемся к шагу 2 и добавляем пропущенные тесты.

🧩 Структура тестов и моки

Unit-тесты (Jest / Vitest)

Проверяют отдельные функции, компоненты, хелперы.
Пример: тест кнопки — рендер, клик, состояние disabled.

Интеграционные тесты (Jest + NextRequest)

Проверяют работу API-эндпоинтов, взаимодействие с базой данных и внешними сервисами.
Пример: тест GET /api/markets — проверка успешного ответа, валидации параметров, обработки ошибок БД.

E2E-тесты (Playwright)

Имитируют действия пользователя в браузере. Проверяют полные пользовательские сценарии: навигацию, поиск, отправку форм и т.д.
Пример: пользователь заходит на страницу, вводит поисковый запрос, проверяет количество и содержимое карточек.

📁 Организация файлов

Тесты кладутся рядом с кодом (Component.test.tsx) или в отдельную папку e2e/. Это стандартная практика, которая упрощает навигацию и обнаружение тестов.

🎭 Моки для внешних сервисов

Чтобы тесты были быстрыми и надёжными, все внешние зависимости (Supabase, Redis, OpenAI) мокаются на уровне импортов. Навык приводит готовые примеры моков с использованием jest.mock.

🚦 Когда использовать

Навык активируется, когда вы:

✏️ Пишете новую функциональность — модули, API, компоненты.
🐛 Исправляете баги — сначала пишете тест, воспроизводящий баг, потом чините код.
🔄 Рефакторите существующий код — тесты гарантируют, что поведение не изменилось.
🧩 Создаёте новые компоненты или API-эндпоинты.

Не рекомендуется использовать этот навык для экспериментального кода, быстрых прототипов или одноразовых скриптов — затраты на TDD там не оправданы.

💡 Важно знать

Тесты первичны, а не просто «хорошая практика». Навык explicitly запрещает писать код до тестов.
Одно утверждение на тест — каждый it проверяет только одно поведение. Это упрощает поиск проблемы при падении.
Не тестируйте детали реализации — тестируйте то, что видит пользователь или другие части системы. Например, вместо проверки внутреннего состояния компонента (component.state.count) проверяйте текст на экране (screen.getByText('Count: 5')).
Изолируйте тесты — каждый тест должен создавать свои данные и не зависеть от других тестов. Общие моки — да, общее состояние — нет.
Семантические селекторы — в E2E-тестах избегайте хрупких CSS-классов, используйте data-testid, роли и текст.
Непрерывное тестирование — запускайте тесты в watch-режиме (npm test -- --watch) во время разработки, добавляйте их в pre-commit hook и в CI/CD (GitHub Actions, Codecov).
Быстрота — unit-тесты должны выполняться быстрее 50 мс каждый. Если тесты стали медленными, пересмотрите моки или разбейте сценарии.
Критерии успеха: 80%+ покрытия, все тесты зелёные, ни одного пропущенного или отключённого теста, E2E покрывают критические пути пользователя.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code tdd-workflow

Источник: https://mcpmarket.com/tools/skills/tdd-workflow-1777849919190