Community라이팅 & 에디팅github.com

sametcelikbicak/coverage-guard

JavaScript/TypeScript 프로젝트에서 100% 테스트 커버리지를 강제하는 AI 에이전트 스킬입니다. Vitest, Jest, react-scripts 등 다양한 테스트 러너와 호환되며, opencode, Claude Code, Cursor, Windsurf, GitHub Copilot에서 사용할 수 있습니다.

coverage-guard란 무엇인가요?

이 스킬은 JavaScript/TypeScript 프로젝트에서 100% 테스트 커버리지를 달성하도록 설계된 AI 에이전트 도구입니다. Vitest, Jest, react-scripts를 포함한 여러 테스트 러너를 자동으로 감지하고, 필요한 인프라가 없으면 설정하며, 커버되지 않은 소스 파일에 대한 테스트를 생성하고, 커버리지 갭을 반복적으로 채워 최종적으로 모든 파일이 100% 커버리지에 도달할 때까지 루프를 돌립니다. opencode, Claude Code, Cursor, Windsurf, GitHub Copilot과 같은 다양한 AI 코딩 플랫폼과 호환됩니다. 이 스킬의 핵심은 환경 감지, 소스 파일 스캔, 누락된 인프라 설정, 테스트 생성, 커버리지 실행, 갭 분석 및 채우기, 검증의 8단계 파이프라인을 통해 완전 자동화된 워크플로우를 제공한다는 점입니다. 사용자는 명령어를 통해 쉽게 커버리지 상태를 확인하고 개선할 수 있습니다.

지원 대상✓Claude Code~Codex CLI✓Cursor✓OpenCode✓Windsurf
npx skills add sametcelikbicak/coverage-guard

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Coverage Guard

JavaScript/TypeScript 프로젝트에서 100% 테스트 커버리지를 보장합니다. 테스트 러너를 자동으로 감지하고, 누락된 테스트 인프라를 설정하며, 커버되지 않은 컴포넌트에 대한 테스트를 작성하고, 모든 파일이 100% 커버리지에 도달할 때까지 반복합니다.

개요

이 스킬은 완전한 파이프라인을 따릅니다:

  1. 감지 러너 및 인프라 → 2. 스캔 소스 파일 및 테스트 → 3. 설정 누락된 경우 → 4. 생성 새 테스트 → 5. 실행 커버리지 → 6. 채우기 갭 → 7. 검증 → 100%까지 반복

단계별 워크플로우

1단계: 환경 감지

프로젝트 루트의 package.json을 확인하여 다음을 판별합니다:

cat package.json

테스트 러너 및 커버리지 도구 식별:

지표러너커버리지 명령어
"vitest" in devDependenciesVitestnpx vitest --coverage
"jest" in devDependenciesJestnpx jest --coverage
"react-scripts" in devDependenciesreact-scripts (Jest)npx react-scripts test --coverage
"next" in devDependenciesNext.js (Jest)npx next test --coverage 또는 jest.config 확인
"@angular/core" in dependenciesAngular (Karma/Jasmine)ng test --code-coverage
"@playwright/test" in devDependenciesPlaywrightnpx playwright test (내장 커버리지 없음; @playwright/test와 istanbul 사용)
"mocha" in devDependenciesMochanpx mocha (c8/nyc를 통한 커버리지)
"cypress" in devDependenciesCypressnpx cypress run (@cypress/code-coverage를 통한 커버리지)
"ava" in devDependenciesAVAnpx 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.tsx
  • src/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단계: 테스트되지 않은 소스 파일에 대한 테스트 작성

테스트 파일이 없는 각 소스 파일에 대해 소스 코드를 분석합니다:

  1. 소스 파일을 읽습니다.
  2. 다음을 식별합니다:
    • 모든 내보내진 함수, 클래스, 컴포넌트
    • 반환 유형 및 가능한 반환 경로
    • 매개변수 및 해당 유형 (필수, 선택, 기본값)
    • Props 인터페이스 (React 컴포넌트의 경우)
    • 비동기 동작 (Promise, async/await)
    • 부작용 (API 호출, localStorage 등)
    • 오류 상태 및 엣지 케이스
  3. 프로젝트 규칙에 따라 테스트 파일을 생성합니다:
    • 감지된 테스트 러너의 API를 사용합니다 (describe/it/expect for Jest/Vitest 등)
    • React의 경우: @testing-library/react 사용 (render, screen, fireEvent)
    • 외부 의존성을 모의(Mock) 처리합니다.
    • 모든 분기, 엣지 케이스 및 오류 경로를 다룹니다.

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단계: 커버리지 리포트 실행

감지된 러너에 따라 적절한 커버리지 명령어를 실행합니다:

러너명령어
Vitestnpx vitest --coverage --reporter=verbose
Jestnpx jest --coverage --verbose
react-scriptsnpx react-scripts test --coverage --watchAll=false
기타프로젝트에 구성된 커버리지 명령어 사용

출력을 파싱하여 다음을 식별합니다:

  • 100% 미만의 파일
  • 커버되지 않은 라인, 분기, 함수 및 구문
  • 테스트가 필요한 특정 라인 번호
  • 0% 커버리지 파일 (테스트가 존재하지 않음)

6단계: 커버리지 갭 분석 및 채우기

100% 미만의 각 파일에 대해 (이제 테스트가 있지만 100%에 도달하지 못한 4단계의 파일 포함):

  1. 소스 파일과 해당 테스트 파일을 나란히 읽습니다.
  2. 커버되지 않은 라인/함수/분기가 무엇을 하는지 이해합니다.
  3. 테스트에서 누락된 엣지 케이스를 식별합니다.
  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 */
  • 소스 코드 로직은 수정하지 마십시오 — 테스트만 추가 또는 업데이트합니다.
  • 프로젝트의 기존 테스트 패턴(파일 이름 지정, 폴더 구조, 모킹 스타일)을 따릅니다.
  • 테스트가 0개인 파일의 경우, 먼저 모든 주요 경로를 다루는 포괄적인 테스트 파일을 만든 다음 반복합니다.

감지 우선순위

소스 파일을 스캔할 때, 일반적인 디렉토리 구조 순서로 확인합니다:

  1. src/
  2. app/ (Next.js app 디렉토리)
  3. components/
  4. lib/
  5. utils/
  6. server/ (Next.js/Node.js)
  7. pages/ (Next.js pages 디렉토리)
  8. 루트 수준의 *.ts / *.tsx 파일

예시

사용자: "커버리지 리포트에 login.ts가 72%로 나와요, 수정해주세요"

에이전트 동작:

  1. npx vitest --coverage --reporter=verbose 실행, login.ts의 45-52라인이 커버되지 않음 확인 (validateEmail의 오류 분기)
  2. 소스를 읽고, validateEmail이 유효하지 않은 이메일에 대해 예외를 던짐을 이해
  3. login.test.ts에 유효하지 않은 이메일 입력에 대한 테스트 케이스 추가
  4. 커버리지 재실행 — login.ts 이제 100%

사용자: "jest를 사용합니다, 커버리지 확인해주세요"

  1. npx jest --coverage --verbose 실행, 커버되지 않은 파일 식별
  2. src/components/Header.tsx가 0%임을 발견 — 테스트 없음
  3. Header.tsx 소스를 읽고, src/components/Header.test.tsx 생성
  4. 커버리지 재실행 — Header.tsx 이제 100%

사용자: "이 프로젝트에 테스트 설정이 없어요, 커버리지를 추가해주세요"

  1. package.json에서 테스트 러너 없음 감지
  2. 사용자에게 질문: "테스트 프레임워크가 감지되지 않았습니다. Vitest를 설치하시겠습니까? (권장)"
  3. 사용자 확인 → vitest + @vitest/coverage-v8 설치, vitest.config.ts 생성
  4. src/ 스캔, 8개의 소스 파일, 0개의 테스트 파일 발견
  5. 8개 파일 모두에 대한 테스트 작성
  6. 커버리지 실행 — 모두 100%

관련 스킬