Coverage Guard
JavaScript/TypeScript 프로젝트에서 100% 테스트 커버리지를 보장합니다. 테스트 러너를 자동으로 감지하고, 누락된 테스트 인프라를 설정하며, 커버되지 않은 컴포넌트에 대한 테스트를 작성하고, 모든 파일이 100% 커버리지에 도달할 때까지 반복합니다.
개요
이 스킬은 완전한 파이프라인을 따릅니다:
- 감지 러너 및 인프라 → 2. 스캔 소스 파일 및 테스트 → 3. 설정 누락된 경우 → 4. 생성 새 테스트 → 5. 실행 커버리지 → 6. 채우기 갭 → 7. 검증 → 100%까지 반복
단계별 워크플로우
1단계: 환경 감지
프로젝트 루트의 package.json을 확인하여 다음을 판별합니다:
cat package.json
테스트 러너 및 커버리지 도구 식별:
| 지표 | 러너 | 커버리지 명령어 |
|---|---|---|
"vitest" in devDependencies | Vitest | npx vitest --coverage |
"jest" in devDependencies | Jest | npx jest --coverage |
"react-scripts" in devDependencies | react-scripts (Jest) | npx react-scripts test --coverage |
"next" in devDependencies | Next.js (Jest) | npx next test --coverage 또는 jest.config 확인 |
"@angular/core" in dependencies | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" in devDependencies | Playwright | npx playwright test (내장 커버리지 없음; @playwright/test와 istanbul 사용) |
"mocha" in devDependencies | Mocha | npx mocha (c8/nyc를 통한 커버리지) |
"cypress" in devDependencies | Cypress | npx cypress run (@cypress/code-coverage를 통한 커버리지) |
"ava" in devDependencies | AVA | npx ava (c8를 통한 커버리지) |
| 없음 | 없음 → 2단계로 진행 → 3단계 설정 |
2단계: 소스 파일 및 기존 테스트 스캔
테스트가 필요한 모든 소스 파일(컴포넌트, 모듈, 유틸리티)을 찾습니다:
# 일반적인 소스 디렉토리
find src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.next/*"
기존 테스트 파일을 모두 찾습니다:
find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"
각 소스 파일을 테스트 파일에 매핑:
src/components/Button.tsx→src/components/Button.test.tsx또는src/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.ts또는src/utils/__tests__/format.test.ts- 테스트 파일 배치에 대한 기존 프로젝트 규칙을 따릅니다.
각 소스 파일을 분류:
- 테스트 있음 → 커버리지 분석 목록에 추가
- 테스트 없음 → 테스트 생성 대상으로 표시
3단계: 테스트 인프라 설정 (누락된 경우)
1단계에서 테스트 러너가 감지되지 않은 경우, 대화형으로 사용자에게 질문합니다:
? 테스트 프레임워크가 감지되지 않았습니다. 어떤 것을 설정하시겠습니까?
1) Vitest (권장 — 빠르고, 현대적이며, 네이티브 ESM)
2) Jest (가장 널리 사용됨)
3) react-scripts (Create React App)
4) 없음 — 건너뛰기, 수동으로 설정하겠습니다.
사용자가 선택하면 의존성을 설치하고 구성을 생성합니다:
Vitest 설정:
npm install -D vitest @vitest/coverage-v8
vitest.config.ts 생성:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
package.json 스크립트에 추가:
{
"scripts": {
"test": "vitest",
"test:coverage": "vitest --coverage"
}
}
Jest 설정:
npm install -D jest @types/jest ts-jest
npx ts-jest config:init
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
jest.config.ts 생성:
export default {
testEnvironment: 'jsdom',
transform: {
'^.+\\.tsx?$': 'ts-jest',
},
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}
package.json 스크립트에 추가:
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage"
}
}
react-scripts 설정:
npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
커버리지는 내장되어 있습니다:
{
"scripts": {
"test": "react-scripts test",
"test:coverage": "react-scripts test --coverage"
}
}
설정 후, 빠른 테스트를 실행하여 모든 것이 정상 작동하는지 확인합니다:
npm test
실패할 경우, 계속 진행하기 전에 구성 문제를 해결합니다.
4단계: 테스트되지 않은 소스 파일에 대한 테스트 작성
테스트 파일이 없는 각 소스 파일에 대해 소스 코드를 분석합니다:
- 소스 파일을 읽습니다.
- 다음을 식별합니다:
- 모든 내보내진 함수, 클래스, 컴포넌트
- 반환 유형 및 가능한 반환 경로
- 매개변수 및 해당 유형 (필수, 선택, 기본값)
- Props 인터페이스 (React 컴포넌트의 경우)
- 비동기 동작 (Promise, async/await)
- 부작용 (API 호출, localStorage 등)
- 오류 상태 및 엣지 케이스
- 프로젝트 규칙에 따라 테스트 파일을 생성합니다:
- 감지된 테스트 러너의 API를 사용합니다 (
describe/it/expectfor Jest/Vitest 등) - React의 경우:
@testing-library/react사용 (render,screen,fireEvent) - 외부 의존성을 모의(Mock) 처리합니다.
- 모든 분기, 엣지 케이스 및 오류 경로를 다룹니다.
- 감지된 테스트 러너의 API를 사용합니다 (
React 컴포넌트 예시 (src/components/Button.tsx → src/components/Button.test.tsx):
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button', () => {
it('label로 렌더링됩니다', () => {
render(<Button label="Click me" />)
expect(screen.getByText('Click me')).toBeInTheDocument()
})
it('클릭 시 onClick이 호출됩니다', () => {
const onClick = vi.fn() // Jest의 경우 jest.fn()
render(<Button label="Click" onClick={onClick} />)
fireEvent.click(screen.getByText('Click'))
expect(onClick).toHaveBeenCalledTimes(1)
})
it('disabled prop이 true이면 비활성화됩니다', () => {
render(<Button label="Click" disabled />)
expect(screen.getByText('Click')).toBeDisabled()
})
})
유틸리티 함수 예시 (src/utils/format.ts → src/utils/format.test.ts):
import { formatCurrency, truncate } from './format'
describe('formatCurrency', () => {
it('정수 금액을 포맷팅합니다', () => {
expect(formatCurrency(1000)).toBe('$1,000.00')
})
it('소수 금액을 포맷팅합니다', () => {
expect(formatCurrency(99.95)).toBe('$99.95')
})
it('0을 처리합니다', () => {
expect(formatCurrency(0)).toBe('$0.00')
})
it('음수 값을 처리합니다', () => {
expect(formatCurrency(-50)).toBe('-$50.00')
})
})
5단계: 커버리지 리포트 실행
감지된 러너에 따라 적절한 커버리지 명령어를 실행합니다:
| 러너 | 명령어 |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| 기타 | 프로젝트에 구성된 커버리지 명령어 사용 |
출력을 파싱하여 다음을 식별합니다:
- 100% 미만의 파일
- 커버되지 않은 라인, 분기, 함수 및 구문
- 테스트가 필요한 특정 라인 번호
- 0% 커버리지 파일 (테스트가 존재하지 않음)
6단계: 커버리지 갭 분석 및 채우기
100% 미만의 각 파일에 대해 (이제 테스트가 있지만 100%에 도달하지 못한 4단계의 파일 포함):
- 소스 파일과 해당 테스트 파일을 나란히 읽습니다.
- 커버되지 않은 라인/함수/분기가 무엇을 하는지 이해합니다.
- 테스트에서 누락된 엣지 케이스를 식별합니다.
- 갭을 채우기 위한 대상 테스트를 작성합니다:
- 커버되지 않은 분기:
if및else경로, 삼항 조건을 테스트합니다. - 커버되지 않은 함수: 가능한 모든 반환 경로를 테스트합니다.
- 커버되지 않은 라인: 로직을 추적하고 해당 라인에 도달하는 케이스를 작성합니다.
- 커버되지 않은 비동기 경로: 해결 및 거부된 Promise 분기를 모두 테스트합니다.
- 커버되지 않은 오류 처리: 오류 콜백, catch 블록, 오류 경계를 테스트합니다.
감지된 테스트 러너의 패턴을 사용합니다:
- Vitest:
vi.mock(),vi.spyOn(),vi.fn() - Jest:
jest.mock(),jest.spyOn(),jest.fn() - react-scripts: Jest와 동일
7단계: 검증
테스트를 추가/업데이트한 후 커버리지를 다시 실행합니다:
# 감지된 명령어 사용
npx vitest --coverage # Vitest의 경우
npx jest --coverage # Jest의 경우
모든 파일이 구문, 분기, 함수 및 라인에 대해 100%로 표시되는지 확인합니다.
8단계: 반복
커버리지가 여전히 100% 미만이면 6단계로 돌아갑니다.
러너별 구성
Vitest 커버리지 구성
vitest.config.ts 확인:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Jest 커버리지 구성
jest.config.ts에 다음이 포함되어 있는지 확인:
export default {
collectCoverage: true,
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: [
'src/**/*.{ts,tsx,js,jsx}',
'!src/**/*.d.ts',
'!src/**/*.test.*',
'!src/**/*.spec.*',
],
}
팁
- 기존 테스트가 있지만 커버리지가 낮은 파일부터 시작하세요 — 가장 빠른 성과
- 그 다음, 가장 간단한 로직을 가진 테스트되지 않은 파일을 처리하세요.
- React 컴포넌트의 경우: 렌더링, 사용자 상호작용, 조건부 렌더링, 오류 상태 및 빈/로딩 상태를 테스트합니다.
- 유틸리티 함수의 경우: 엣지 케이스(빈 문자열, null/undefined, 경계 값, 특수 문자)를 테스트합니다.
- API 서비스의 경우: 성공 응답, 오류 응답, 로딩 상태, 타임아웃 및 네트워크 실패를 테스트합니다.
- 죽은 코드(커버 불가능)가 발견되면 제거하거나 커버리지 무시 주석을 추가할 것을 제안합니다:
- Vitest/V8:
/* c8 ignore next */또는/* c8 ignore next 3 */ - Jest/Istanbul:
/* istanbul ignore next */또는/* istanbul ignore if */
- Vitest/V8:
- 소스 코드 로직은 수정하지 마십시오 — 테스트만 추가 또는 업데이트합니다.
- 프로젝트의 기존 테스트 패턴(파일 이름 지정, 폴더 구조, 모킹 스타일)을 따릅니다.
- 테스트가 0개인 파일의 경우, 먼저 모든 주요 경로를 다루는 포괄적인 테스트 파일을 만든 다음 반복합니다.
감지 우선순위
소스 파일을 스캔할 때, 일반적인 디렉토리 구조 순서로 확인합니다:
src/app/(Next.js app 디렉토리)components/lib/utils/server/(Next.js/Node.js)pages/(Next.js pages 디렉토리)- 루트 수준의
*.ts/*.tsx파일
예시
사용자: "커버리지 리포트에 login.ts가 72%로 나와요, 수정해주세요"
에이전트 동작:
npx vitest --coverage --reporter=verbose실행, login.ts의 45-52라인이 커버되지 않음 확인 (validateEmail의 오류 분기)- 소스를 읽고,
validateEmail이 유효하지 않은 이메일에 대해 예외를 던짐을 이해 login.test.ts에 유효하지 않은 이메일 입력에 대한 테스트 케이스 추가- 커버리지 재실행 — login.ts 이제 100%
사용자: "jest를 사용합니다, 커버리지 확인해주세요"
npx jest --coverage --verbose실행, 커버되지 않은 파일 식별src/components/Header.tsx가 0%임을 발견 — 테스트 없음- Header.tsx 소스를 읽고,
src/components/Header.test.tsx생성 - 커버리지 재실행 — Header.tsx 이제 100%
사용자: "이 프로젝트에 테스트 설정이 없어요, 커버리지를 추가해주세요"
- package.json에서 테스트 러너 없음 감지
- 사용자에게 질문: "테스트 프레임워크가 감지되지 않았습니다. Vitest를 설치하시겠습니까? (권장)"
- 사용자 확인 → vitest + @vitest/coverage-v8 설치, vitest.config.ts 생성
- src/ 스캔, 8개의 소스 파일, 0개의 테스트 파일 발견
- 8개 파일 모두에 대한 테스트 작성
- 커버리지 실행 — 모두 100%