테스트 주도 개발 워크플로우
이 스킬은 모든 코드 개발이 TDD 원칙을 따르고 포괄적인 테스트 커버리지를 보장하도록 합니다.
활성화 시점
- 새 기능이나 기능 구현
- 버그 또는 이슈 수정
- 기존 코드 리팩터링
- API 엔드포인트 추가
- 새 컴포넌트 생성
핵심 원칙
1. 코드보다 테스트 먼저
항상 테스트를 먼저 작성한 후, 테스트를 통과하는 코드를 구현합니다.
2. 커버리지 요구사항
- 최소 80% 커버리지 (단위 + 통합 + E2E)
- 모든 엣지 케이스 처리
- 오류 시나리오 테스트
- 경계 조건 검증
3. 테스트 유형
단위 테스트
- 개별 함수 및 유틸리티
- 컴포넌트 로직
- 순수 함수
- 헬퍼 및 유틸리티
통합 테스트
- API 엔드포인트
- 데이터베이스 작업
- 서비스 간 상호작용
- 외부 API 호출
E2E 테스트 (Playwright)
- 주요 사용자 흐름
- 전체 워크플로우
- 브라우저 자동화
- UI 상호작용
TDD 워크플로우 단계
0단계: 테스트 러너 감지
npm test를 가정하지 마십시오. 아래 단계와 예제의 명령어는 실제 프로젝트 러너를 위한 <test>, <test-watch>, <coverage> 자리 표시자를 사용합니다. 시작하기 전에 한 번만 확인합니다:
-
프로젝트 러너를 찾습니다.
package.json(packageManager,scripts.test), lockfile,pyproject.toml/pytest.ini,go.mod,Cargo.toml을 읽습니다. 첫 번째 일치 항목을 사용하며npm test를 가정하지 않습니다. -
패키지 매니저와 테스트 러너를 구분합니다. 둘은 다릅니다. 프로젝트가 Bun으로 종속성을 설치하면서도 Jest나 Vitest를 실행할 수 있습니다.
package.json의scripts.test와 테스트 파일을 검사합니다:scripts.test가jest/vitest를 호출 -> 감지된 PM을 통해 실행 (npm test,pnpm test,yarn test,bun run test).scripts.test가bun test이거나, 테스트 파일이import { test, expect } from "bun:test"를 사용하거나, jest/vitest 설정이 없지만 Bun이 존재하는 경우 -> Bun의 네이티브 러너 (bun test) 사용. 아래 Bun 네이티브 테스트 패턴을 참조하세요.- Python:
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80. Go:go test ./...및go test -cover ./.... Rust:cargo test.
러너 명령어 매트릭스:
| 러너 | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun (스크립트가 jest/vitest 실행) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun (네이티브 bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(Bun 내장 러너)는bun run test(package.json의 test 스크립트 실행)와 다릅니다. 잘못 선택하는 것은 흔한 실패 원인입니다. 예를 들어 ESM 전용 프로젝트에서npx/bun run을 통해 Jest를 호출하면 깨지지만,bun test는 네이티브로 실행됩니다. RED 게이트 전에 프로젝트가 어떤 것을 기대하는지 확인한 후 아래의npm test를<test>/<coverage>로 대체합니다.
1단계: 사용자 여정 작성하기
[역할]로서, [행위]를 하고 싶습니다. 그래서 [이점]을 얻습니다.
예시:
사용자로서, 시장을 의미적으로 검색하고 싶습니다.
그래서 정확한 키워드 없이도 관련 시장을 찾을 수 있습니다.
2단계: 테스트 케이스 생성하기
각 사용자 여정에 대해 포괄적인 테스트 케이스를 만듭니다:
describe('의미 검색', () => {
it('쿼리에 대해 관련 시장을 반환합니다', async () => {
// 테스트 구현
})
it('빈 쿼리를 적절히 처리합니다', async () => {
// 엣지 케이스 테스트
})
it('Redis를 사용할 수 없을 때 부분 문자열 검색으로 대체합니다', async () => {
// 대체 동작 테스트
})
it('유사도 점수로 결과를 정렬합니다', async () => {
// 정렬 로직 테스트
})
})
3단계: 테스트 실행 (실패해야 함)
<test>
# 아직 구현하지 않았으므로 테스트가 실패해야 합니다
4단계: 코드 구현하기
테스트를 통과하는 최소한의 코드를 작성합니다:
// 테스트에 의해 안내되는 구현
export async function searchMarkets(query: string) {
// 구현 내용
}
5단계: 테스트 다시 실행하기
<test>
# 이제 테스트가 통과해야 합니다
6단계: 리팩터링하기
테스트가 통과하는 상태에서 코드 품질을 개선합니다:
- 중복 제거
- 네이밍 개선
- 성능 최적화
- 가독성 향상
7단계: 커버리지 확인하기
<coverage>
# 80% 이상 커버리지 달성 확인
테스트 패턴
단위 테스트 패턴 (Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button 컴포넌트', () => {
it('올바른 텍스트로 렌더링됩니다', () => {
render(<Button>클릭하세요</Button>)
expect(screen.getByText('클릭하세요')).toBeInTheDocument()
})
it('클릭 시 onClick이 호출됩니다', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>클릭</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('disabled prop이 true이면 비활성화됩니다', () => {
render(<Button disabled>클릭</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Bun 네이티브 테스트 패턴 (bun:test)
프로젝트가 Bun의 내장 러너를 사용하는 경우 (0단계 참조), bun:test에서 가져오고 bun test로 실행합니다 (bun run test가 아님). API는 Jest와 유사하므로 describe / it / expect 및 대부분의 매처가 그대로 작동합니다.
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('빈 쿼리에 대해 빈 목록을 반환합니다', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('유사도 점수로 결과를 정렬합니다', async () => {
const results = await searchMarkets('election')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # 한 번 실행 (RED/GREEN 게이트)
bun test --watch # 개발 중 감시 모드
bun test --coverage # 커버리지 보고서
jest.mock(...)대신bun:test의mock.module(...)/mock(...)을 사용하여 모듈을 모킹합니다.- Jest의
coverageThresholds설정 블록 대신bunfig.toml의[test]아래에 커버리지 임계값을 설정합니다 (예:coverageThreshold).
API 통합 테스트 패턴
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('시장을 성공적으로 반환합니다', 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('쿼리 매개변수를 검증합니다', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalid')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('데이터베이스 오류를 적절히 처리합니다', async () => {
// 데이터베이스 실패 모킹
const request = new NextRequest('http://localhost/api/markets')
// 오류 처리 테스트
})
})
E2E 테스트 패턴 (Playwright)
import { test, expect } from '@playwright/test'
test('사용자가 시장을 검색하고 필터링할 수 있습니다', async ({ page }) => {
// 시장 페이지로 이동
await page.goto('/')
await page.click('a[href="/markets"]')
// 페이지 로드 확인
await expect(page.locator('h1')).toContainText('시장')
// 시장 검색
await page.fill('input[placeholder="시장 검색"]', 'election')
// 디바운스 및 결과 대기
await page.waitForTimeout(600)
// 검색 결과 표시 확인
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// 결과에 검색어 포함 확인
const firstResult = results.first()
await expect(firstResult).toContainText('election', { ignoreCase: true })
// 상태별 필터링
await page.click('button:has-text("활성")')
// 필터링된 결과 확인
await expect(results).toHaveCount(3)
})
test('사용자가 새 시장을 생성할 수 있습니다', async ({ page }) => {
// 먼저 로그인
await page.goto('/creator-dashboard')
// 시장 생성 폼 작성
await page.fill('input[name="name"]', '테스트 시장')
await page.fill('textarea[name="description"]', '테스트 설명')
await page.fill('input[name="endDate"]', '2025-12-31')
// 폼 제출
await page.click('button[type="submit"]')
// 성공 메시지 확인
await expect(page.locator('text=시장이 성공적으로 생성되었습니다')).toBeVisible()
// 시장 페이지로 리디렉션 확인
await expect(page).toHaveURL(/\/markets\/test-market/)
})
테스트 파일 조직
src/
├── components/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.test.tsx # 단위 테스트
│ │ └── Button.stories.tsx # Storybook
│ └── MarketCard/
│ ├── MarketCard.tsx
│ └── MarketCard.test.tsx
├── app/
│ └── api/
│ └── markets/
│ ├── route.ts
│ └── route.test.ts # 통합 테스트
└── e2e/
├── markets.spec.ts # E2E 테스트
├── trading.spec.ts
└── auth.spec.ts
외부 서비스 모킹
Supabase 모킹
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 모킹
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'test-market', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
OpenAI 모킹
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // 1536차원 임베딩 모킹
))
}))
테스트 커버리지 확인
커버리지 보고서 실행
<coverage>
커버리지 임계값
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
피해야 할 일반적인 테스트 실수
실패: 잘못된 예: 구현 세부 사항 테스트
// 내부 상태를 테스트하지 마세요
expect(component.state.count).toBe(5)
통과: 올바른 예: 사용자에게 보이는 동작 테스트
// 사용자가 보는 것을 테스트하세요
expect(screen.getByText('Count: 5')).toBeInTheDocument()
실패: 잘못된 예: 취약한 선택자
// 쉽게 깨집니다
await page.click('.css-class-xyz')
통과: 올바른 예: 의미론적 선택자
// 변경에 강합니다
await page.click('button:has-text("제출")')
await page.click('[data-testid="submit-button"]')
실패: 잘못된 예: 테스트 격리 없음
// 테스트가 서로 의존합니다
test('사용자 생성', () => { /* ... */ })
test('동일 사용자 업데이트', () => { /* 이전 테스트에 의존 */ })
통과: 올바른 예: 독립적인 테스트
// 각 테스트가 자체 데이터를 설정합니다
test('사용자 생성', () => {
const user = createTestUser()
// 테스트 로직
})
test('사용자 업데이트', () => {
const user = createTestUser()
// 업데이트 로직
})
지속적인 테스트
개발 중 감시 모드
<test-watch>
# 파일 변경 시 테스트 자동 실행
사전 커밋 훅
# 모든 커밋 전에 실행
<test> && <lint>
CI/CD 통합
# GitHub Actions
- name: 테스트 실행
run: <coverage>
- name: 커버리지 업로드
uses: codecov/codecov-action@v3
모범 사례
- 먼저 테스트 작성 - 항상 TDD
- 테스트당 하나의 단언 - 단일 동작에 집중
- 설명적인 테스트 이름 - 무엇을 테스트하는지 설명
- 준비-실행-단언 - 명확한 테스트 구조
- 외부 종속성 모킹 - 단위 테스트 격리
- 엣지 케이스 테스트 - null, undefined, 빈 값, 큰 값
- 오류 경로 테스트 - 행복한 경로만이 아님
- 테스트 속도 유지 - 각 단위 테스트 50ms 미만
- 테스트 후 정리 - 부작용 없음
- 커버리지 보고서 검토 - 격차 식별
성공 지표
- 80% 이상 코드 커버리지 달성
- 모든 테스트 통과 (초록색)
- 건너뛰거나 비활성화된 테스트 없음
- 빠른 테스트 실행 (단위 테스트 30초 미만)
- E2E 테스트가 주요 사용자 흐름을 포함
- 테스트가 프로덕션 전에 버그를 발견
명심하세요: 테스트는 선택 사항이 아닙니다. 자신 있는 리팩터링, 빠른 개발, 프로덕션 안정성을 가능하게 하는 안전망입니다.