The Complete Claude Code Testing Workflow Guide: From TDD to CI/CD

# Step 1: Red — Have Claude Code write tests first
> I want to implement a parseMarkdown function that converts markdown to HTML.
> Don't write the implementation yet, only write tests. Cover these scenarios:
> - Headings (h1-h3)
> - Bold and italic
> - Code blocks
> - Empty string input
> - Plain text (no markdown syntax)
 
# Step 2: Green — Have Claude Code write the implementation
> Now write the parseMarkdown implementation to make all tests pass. Keep it simple.
 
# Step 3: Refactor — Have Claude Code refactor
> All tests pass. Now refactor parseMarkdown:
> - Extract regexes into constants
> - Split each syntax parser into its own function
> - Run tests to confirm nothing breaks

// lib/__tests__/parse-markdown.test.ts
import { describe, it, expect } from 'vitest'
import { parseMarkdown } from '../parse-markdown'
 
describe('parseMarkdown', () => {
  describe('headings', () => {
    it('should parse h1', () => {
      expect(parseMarkdown('# Hello')).toBe('<h1>Hello</h1>')
    })
 
    it('should parse h2', () => {
      expect(parseMarkdown('## World')).toBe('<h2>World</h2>')
    })
 
    it('should parse h3', () => {
      expect(parseMarkdown('### Test')).toBe('<h3>Test</h3>')
    })
  })
 
  describe('inline styles', () => {
    it('should parse bold', () => {
      expect(parseMarkdown('**bold**')).toBe('<p><strong>bold</strong></p>')
    })
 
    it('should parse italic', () => {
      expect(parseMarkdown('*italic*')).toBe('<p><em>italic</em></p>')
    })
  })
 
  describe('code', () => {
    it('should parse inline code', () => {
      expect(parseMarkdown('`code`')).toBe('<p><code>code</code></p>')
    })
  })
 
  describe('edge cases', () => {
    it('returns empty string for empty input', () => {
      expect(parseMarkdown('')).toBe('')
    })
 
    it('wraps plain text in p tags', () => {
      expect(parseMarkdown('hello world')).toBe('<p>hello world</p>')
    })
  })
})

// lib/parse-markdown.ts
export function parseMarkdown(input: string): string {
  if (!input) return ''
 
  const lines = input.split('\n')
  const result: string[] = []
 
  for (const line of lines) {
    // Headings
    const headingMatch = line.match(/^(#{1,3})\s+(.+)$/)
    if (headingMatch) {
      const level = headingMatch[1].length
      result.push(`<h${level}>${headingMatch[2]}</h${level}>`)
      continue
    }
 
    // Inline styles
    let processed = line
    processed = processed.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
    processed = processed.replace(/\*(.+?)\*/g, '<em>$1</em>')
    processed = processed.replace(/`(.+?)`/g, '<code>$1</code>')
 
    if (processed) {
      result.push(`<p>${processed}</p>`)
    }
  }
 
  return result.join('\n')
}

> Refactor parseMarkdown: extract regexes into constants, split each syntax
> parser into its own function. Run tests to confirm.

<!-- .claude/commands/tdd.md -->
Implement $ARGUMENTS using TDD:
 
1. Write the test file first (tests only, no implementation)
2. Confirm all tests fail
3. Write the minimal implementation to make tests pass
4. Refactor the code while keeping tests green
5. Check for missing edge cases and add tests
 
Test framework: vitest
Test files go in __tests__/ next to the source file
After each step, tell me the current state (Red/Green/Refactor)

# Bad — jump straight in
> Write tests for src/lib/posts.ts
 
# Good — analyze first
> Read src/lib/posts.ts and list all public functions with:
> 1. Parameter types and return types
> 2. External dependencies (filesystem, network, database)
> 3. Possible edge cases
> Then write the tests

> Write tests for all utility functions in src/lib/. Process file by file:
> 1. List all .ts files in src/lib/
> 2. Skip files that already have tests (check __tests__ directory)
> 3. Generate tests one by one
> 4. Run tests after each file to confirm they pass

> Review the test quality of src/lib/__tests__/posts.test.ts:
> 1. Does it only test the happy path?
> 2. Are error handling paths tested?
> 3. Are boundary values tested (empty array, null, very long strings)?
> 4. Are assertions specific enough (not just toBeTruthy)?
> 5. Do tests have implicit dependencies (shared state)?
> List issues and fix them

import { describe, it, expect, vi } from 'vitest'
import { fetchUserProfile } from '../api'
 
vi.stubGlobal('fetch', vi.fn())
 
describe('fetchUserProfile', () => {
  it('successfully fetches user info', async () => {
    const mockUser = { id: 1, name: 'Alice' }
    vi.mocked(fetch).mockResolvedValueOnce(
      new Response(JSON.stringify(mockUser), { status: 200 })
    )
 
    const result = await fetchUserProfile(1)
    expect(result).toEqual(mockUser)
    expect(fetch).toHaveBeenCalledWith('/api/users/1')
  })
 
  it('handles 404 errors', async () => {
    vi.mocked(fetch).mockResolvedValueOnce(
      new Response(null, { status: 404 })
    )
 
    await expect(fetchUserProfile(999)).rejects.toThrow('User not found')
  })
})

import { describe, it, expect, vi } from 'vitest'
import fs from 'fs'
import { getPostSlugs } from '../posts'
 
vi.mock('fs', () => ({
  default: {
    readdirSync: vi.fn(),
    readFileSync: vi.fn(),
  },
}))
 
describe('getPostSlugs', () => {
  it('returns slugs for all mdx files', () => {
    vi.mocked(fs.readdirSync).mockReturnValue(
      ['hello.mdx', 'world.mdx', 'readme.txt'] as any
    )
 
    const slugs = getPostSlugs('content/en')
    expect(slugs).toEqual(['hello', 'world'])
  })
 
  it('returns empty array for empty directory', () => {
    vi.mocked(fs.readdirSync).mockReturnValue([] as any)
 
    const slugs = getPostSlugs('content/en')
    expect(slugs).toEqual([])
  })
})

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { isNewPost } from '../utils'
 
describe('isNewPost', () => {
  beforeEach(() => {
    vi.useFakeTimers()
    vi.setSystemTime(new Date('2026-03-20'))
  })
 
  afterEach(() => {
    vi.useRealTimers()
  })
 
  it('marks posts within 7 days as new', () => {
    expect(isNewPost('2026-03-15')).toBe(true)
  })
 
  it('does not mark posts older than 7 days', () => {
    expect(isNewPost('2026-03-01')).toBe(false)
  })
})

import { describe, it, expect, vi } from 'vitest'
import { getRandomPost } from '../posts'
 
describe('getRandomPost', () => {
  it('returns the post at the random index', () => {
    const posts = [{ slug: 'a' }, { slug: 'b' }, { slug: 'c' }]
    vi.spyOn(Math, 'random').mockReturnValue(0.5)
 
    const result = getRandomPost(posts)
    // Math.floor(0.5 * 3) = 1, returns second post
    expect(result.slug).toBe('b')
 
    vi.restoreAllMocks()
  })
})

> Read src/services/notification.ts, analyze its dependencies,
> tell me what needs to be mocked and what doesn't, and why.
> Then write the tests based on your analysis.

// vitest.config.ts
import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    coverage: {
      provider: 'v8', // or 'istanbul'
      reporter: ['text', 'html', 'json-summary'],
      include: ['src/lib/**', 'src/utils/**'],
      exclude: [
        'src/**/*.test.ts',
        'src/**/*.d.ts',
        'src/**/types.ts',
      ],
      thresholds: {
        statements: 80,
        branches: 75,
        functions: 80,
        lines: 80,
      },
    },
  },
})

npx vitest run --coverage

> Run npx vitest run --coverage and analyze the report:
> 1. Which files are below 80% coverage?
> 2. Which specific branches/functions are uncovered?
> 3. Prioritize — cover the most critical ones first
> 4. Generate the supplementary tests

> Run npx vitest run — 3 tests are failing.
> Analyze the failures following these steps:
> 1. Read the error messages, identify the failure pattern
> 2. Check if the test code has issues (uncleaned mocks, unawaited async)
> 3. Check if the code under test has bugs
> 4. Fix the issues and re-run tests to confirm

# Scenario: Test passes alone, fails when run together
> tests/lib/posts.test.ts passes when run alone but fails in the full suite.
> This is usually a mock leakage issue. Help me investigate:
> 1. Check beforeEach/afterEach in all test files
> 2. Find which test file's mock is affecting posts.test.ts
> 3. Add proper cleanup logic

# Scenario: Passes in CI but fails locally
> This test passes on GitHub Actions but fails locally.
> Possible causes:
> - Timezone difference (CI is UTC)
> - File path separators (CI is Linux)
> - Missing environment variables
> Help me find the specific cause and fix it

// app/api/posts/__tests__/route.test.ts
import { describe, it, expect } from 'vitest'
import { GET } from '../route'
import { NextRequest } from 'next/server'
 
describe('GET /api/posts', () => {
  it('returns the post list', async () => {
    const request = new NextRequest('http://localhost/api/posts?locale=en')
    const response = await GET(request)
    const data = await response.json()
 
    expect(response.status).toBe(200)
    expect(Array.isArray(data.posts)).toBe(true)
    expect(data.posts[0]).toHaveProperty('title')
    expect(data.posts[0]).toHaveProperty('slug')
  })
 
  it('returns 400 for invalid locale', async () => {
    const request = new NextRequest('http://localhost/api/posts?locale=fr')
    const response = await GET(request)
 
    expect(response.status).toBe(400)
  })
})

> Write a Playwright E2E test:
> 1. Open the blog homepage
> 2. Click the first article
> 3. Verify the article title displays correctly
> 4. Verify the table of contents exists
> 5. Scroll to the bottom, verify the comments section loads

// e2e/blog-flow.spec.ts
import { test, expect } from '@playwright/test'
 
test('blog article reading flow', async ({ page }) => {
  // 1. Open blog homepage
  await page.goto('/en/blog')
  await expect(page).toHaveTitle(/Blog/)
 
  // 2. Click the first article
  const firstPost = page.locator('article a').first()
  const postTitle = await firstPost.textContent()
  await firstPost.click()
 
  // 3. Verify article title
  await expect(page.locator('h1')).toHaveText(postTitle!)
 
  // 4. Verify table of contents
  await expect(page.locator('nav[aria-label="Table of contents"]')).toBeVisible()
 
  // 5. Scroll to bottom, verify comments
  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
  await expect(page.locator('.giscus')).toBeVisible({ timeout: 10000 })
})

# Test Conventions
 
## Framework & Tools
- Test framework: vitest
- Assertions: vitest built-in expect
- Mocking: vi.mock() / vi.spyOn()
- Coverage: v8 provider
 
## File Organization
- Test files go in __tests__/ next to the source file
- Naming: [source-file].test.ts
- Example: src/lib/posts.ts → src/lib/__tests__/posts.test.ts
 
## Naming Conventions
- describe blocks use module/function names
- it blocks describe behavior: "returns empty array for no matches"
- Never use meaningless names like "test case 1"
 
## Structure
- Every test follows Arrange-Act-Assert pattern
- Group related tests with describe
- Edge cases get their own describe block
 
## Mock Rules
- Only mock external dependencies (network, filesystem, database, time)
- Never mock internal functions of the module under test
- Clean up mocks after each test: afterEach(() => vi.restoreAllMocks())
- Prefer vi.spyOn() over fully replacing modules
 
## Coverage Requirements
- Core business logic: >= 90%
- Utility functions: >= 85%
- API routes: >= 80%
- Don't require 100% — don't write meaningless tests to pad coverage
 
## Prohibited
- Don't test implementation details (private functions, internal state)
- Don't write tests that depend on execution order
- Don't hardcode environment-specific values (paths, timezones)
- Don't use snapshot tests for logic (snapshots are for UI structure only)

# .github/workflows/test.yml
name: Test
 
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
 
      - run: npm ci
 
      - name: Run tests with coverage
        run: npx vitest run --coverage
 
      - name: Check coverage thresholds
        run: npx vitest run --coverage --coverage.thresholds.100=false
 
      - name: Upload coverage report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/

// thresholds in vitest.config.ts
thresholds: {
  statements: 80,
  branches: 75,
  functions: 80,
  lines: 80,
}

# Append to .github/workflows/test.yml
      - name: Test Report
        if: github.event_name == 'pull_request'
        uses: dorny/test-reporter@v1
        with:
          name: Vitest Results
          path: 'test-results/junit.xml'
          reporter: jest-junit
 
      - name: Coverage Comment
        if: github.event_name == 'pull_request'
        uses: MishaKav/jest-coverage-comment@main
        with:
          coverage-summary-path: coverage/coverage-summary.json
          title: 'Test Coverage Report'

// vitest.config.ts
export default defineConfig({
  test: {
    reporters: ['default', 'junit'],
    outputFile: {
      junit: 'test-results/junit.xml',
    },
    // ... coverage config
  },
})

> I want to add an estimateReadingTime function to the blog.
> Rules:
> - Chinese: 300 characters/minute
> - English: 200 words/minute
> - Code blocks are excluded from reading time
> - Return format: "X min"
> - Minimum 1 minute
>
> Write tests first, no implementation.

// lib/__tests__/reading-time.test.ts
import { describe, it, expect } from 'vitest'
import { estimateReadingTime } from '../reading-time'
 
describe('estimateReadingTime', () => {
  describe('Chinese content', () => {
    it('300 Chinese characters should be 1 minute', () => {
      const content = '测'.repeat(300)
      expect(estimateReadingTime(content, 'zh')).toBe('1 分钟')
    })
 
    it('900 Chinese characters should be 3 minutes', () => {
      const content = '测'.repeat(900)
      expect(estimateReadingTime(content, 'zh')).toBe('3 分钟')
    })
  })
 
  describe('English content', () => {
    it('200 English words should be 1 minute', () => {
      const content = Array(200).fill('word').join(' ')
      expect(estimateReadingTime(content, 'en')).toBe('1 min')
    })
 
    it('600 English words should be 3 minutes', () => {
      const content = Array(600).fill('word').join(' ')
      expect(estimateReadingTime(content, 'en')).toBe('3 min')
    })
  })
 
  describe('code block filtering', () => {
    it('excludes code block content from reading time', () => {
      const content = '测'.repeat(300) + '\n```js\nconsole.log("hello")\n```\n'
      expect(estimateReadingTime(content, 'zh')).toBe('1 分钟')
    })
  })
 
  describe('edge cases', () => {
    it('returns minimum 1 minute for empty content', () => {
      expect(estimateReadingTime('', 'zh')).toBe('1 分钟')
    })
 
    it('returns minimum 1 minute for very short content', () => {
      expect(estimateReadingTime('Hi', 'en')).toBe('1 min')
    })
  })
})

> Tests are ready. Now write the estimateReadingTime implementation to pass all tests.

// lib/reading-time.ts
import type { Locale } from '@/i18n/routing'
 
const READING_SPEED = {
  zh: 300, // characters per minute
  en: 200, // words per minute
}
 
export function estimateReadingTime(content: string, locale: Locale): string {
  // Remove code blocks
  const cleaned = content.replace(/```[\s\S]*?```/g, '')
 
  let count: number
  if (locale === 'zh') {
    // Chinese: count characters (excluding whitespace and punctuation)
    count = cleaned.replace(/[\s\p{P}]/gu, '').length
  } else {
    // English: count words
    count = cleaned.split(/\s+/).filter(Boolean).length
  }
 
  const minutes = Math.max(1, Math.round(count / READING_SPEED[locale]))
  return locale === 'zh' ? `${minutes} 分钟` : `${minutes} min`
}

> All tests pass. Review the code quality and suggest improvements.
> Run tests after any changes to confirm nothing breaks.

> Run coverage and check reading-time.ts.
> If any branches are uncovered, add tests.

> Integrate estimateReadingTime into the blog post page:
> 1. Call it in blog/[slug]/page.tsx
> 2. Display next to the date below the title
> 3. Use i18n for the "min"/"分钟" label

> Check the GitHub Actions config to make sure the new tests run in CI.
> Let me know if coverage thresholds need adjusting.