JoseAntonioNuevo/test-suite-doctor

test-suite-doctor은(는) 무엇을 하나요?

과도하게 큰 테스트 스위트(예: 2,000개 이상의 테스트, 특히 AI가 생성한 코드)를 실제 커버리지를 측정하여 작고 고품질의 스위트로 축소합니다. 추측이 아닌 측정 기반입니다.

하드 규칙

1. 메트릭이 우선, 의견은 그 다음. collect와 minimize가 계획을 생성하기 전에는 절대 테스트 삭제를 제안하지 마십시오. 테스트 코드를 읽고 "쓸모없다"고 판단하는 것은 증거가 아닙니다. 사소해 보이는 테스트가 분기를 유일하게 커버할 수 있습니다.
2. 계획은 제안일 뿐, 최종 판결이 아닙니다. 커버리지는 API 계약, 문서화된 회귀 사례 또는 속성 불변성을 볼 수 없습니다. 삭제 후보는 삭제 전에 3단계에서 검토됩니다.
3. 브랜치에서 작업하십시오. 삭제하기 전에 작업 트리가 깨끗한지 확인하고 브랜치를 생성하십시오 (예: test-doctor/minimize). 더티 트리나 기본 브랜치에서는 테스트를 절대 삭제하지 마십시오.
4. 검증하거나 되돌리십시오. verify가 0으로 종료될 때까지 작업이 완료되지 않습니다. 실패하면 보고된 간격에 대한 테스트를 재생성하고 다시 검증하거나, 삭제된 테스트를 복원하십시오.

요구 사항 확인 (먼저 수행)

• Node.js ≥ 22 및 로컬에 설치된 Vitest 또는 Jest를 사용하는 package.json (node <skill-root>/dist/cli.mjs collect --help).
• 커버리지 제공자가 설치되어 있어야 합니다 (Vitest: @vitest/coverage-v8, Jest는 내장). 누락된 경우 개발 의존성으로 설치하겠다고 제안하십시오.
• 변이 검증에는 추가로 대상 저장소에 @stryker-mutator/core가 구성되어 있어야 합니다. 이는 옵트인이므로 요청 없이 설치하지 마십시오.
• 시작하기 전에 스위트가 통과 상태여야 합니다. 기준 실행에서 실패가 보고되면 사용자에게 알리고 최소화 전에 처리 방법에 대한 동의를 얻으십시오 (실패하는 테스트는 신뢰할 수 없는 커버리지를 제공합니다).

아래 모든 명령은 대상 저장소 루트에서 실행되며, $SKILL은 이 스킬의 디렉토리입니다. 아티팩트는 .test-doctor/에 생성됩니다 (gitignore에 추가하는 것을 권장).

워크플로

1. 측정 (스크립트 — 항상 먼저)

node "$SKILL/dist/cli.mjs" collect --cwd .

러너를 감지하고, 전체 스위트를 한 번 실행하여 커버리지 기준을 만든 다음, 각 테스트 파일을 격리하여 다시 실행하여 커버된 라인/브랜치와 런타임을 기록합니다. .test-doctor/report.json을 작성합니다.

• 기본 세분성은 테스트 파일 단위입니다 (테스트별 격리는 정확하지만 모든 테스트를 개별적으로 실행하므로, 소규모 또는 이미 축소된 스위트에만 --granularity test를 제공하거나 --filter로 범위를 제한하십시오).
• 2,000개 테스트 스위트에서는 시간이 오래 걸리므로 백그라운드에서 실행하고 진행 상황을 보고하십시오. 보고서의 collectionErrors를 중요하게 다루십시오. 해당 단위는 기본적으로 최소화를 차단합니다. 사용자가 명시적으로 --keep-unmeasured를 선택하면 영향을 받는 모든 단위는 필수 유지 대상이 되며 계획은 신뢰할 수 없는 것으로 표시됩니다.
• --filter는 의도적으로 범위를 지정한 기준선을 만듭니다. 수집, 최소화 및 검증은 일치하는 테스트 파일에만 적용됩니다. 모든 권장 사항에 해당 범위를 명시하십시오. 전체 저장소 보장이 아닙니다.

2. 최소화 (스크립트)

node "$SKILL/dist/cli.mjs" minimize --coverage-floor 0.97 --target-count 200

그리디 가중치 합계 선택: 커버리지 기준에 도달할 때까지 런타임 1밀리초당 가장 많은 새로 커버된 라인/브랜치를 가진 단위를 반복적으로 유지합니다. .test-doctor/plan.json과 사람이 읽을 수 있는 .test-doctor/plan.md를 작성하며, 유지 및 삭제된 각 단위에 대한 설명이 포함됩니다.

• 명시되지 않은 경우 사용자에게 임계값을 물어보십시오. 기본값은 라인 기준 0.97, 브랜치 기준 없음, 대상 개수 없음입니다. --help에 모든 옵션이 나열됩니다.
• 알려진 계약/회귀 테스트는 사전에 강제 유지: --keep 'contract' --keep 'regression' (단위 ID에 대한 정규식).
• 계획의 warnings 배열에 주의하십시오. 예를 들어 기준에 도달할 수 없거나 대상 개수보다 더 많은 단위가 필요한 경우. 사용자에게 그대로 전달하십시오.

3. 검토 (판단 — 사용자)

references/slop-patterns.md를 읽고 plan.md의 삭제 목록을 검토하십시오:

• 커버리지에 보이지 않는 동작을 검증하는 테스트를 구출하십시오: 공개 API 계약, 이슈/버그 ID를 참조하는 회귀, 소비자가 의존하는 오류 메시지 표현, 속성/불변성 검사. 계획을 수동으로 편집하지 말고 추가 --keep 패턴으로 최소화를 다시 실행하십시오.
• 나머지가 안전한 삭제인지 확인하고, 각각이 삭제되는 이유를 사용자가 알 수 있도록 슬롭 패턴별로 분류하십시오 (패턴 파일에 카탈로그가 있습니다).

그런 다음 references/quality-rules.md에 대해 유지 목록을 검토하십시오: 냄새나는 유지 테스트(모의-모의, 동어 반복, 빈 스냅샷)는 제자리에서 다시 작성됩니다. 커버리지를 얻을 자격은 있지만, 깨끗하게 얻어야 합니다.

이 검토 후에만 브랜치에서 삭제된 테스트 파일/케이스를 삭제하십시오. 모든 단위가 삭제되면 전체 파일을 삭제하고, 파일 내 일부 테스트만 삭제되면 파일을 편집하십시오 (테스트 세분성).

4. 재생성 (판단 — 사용자)

verify를 한 번 실행하여 (실패할 수 있음) 커버리지 간격 보고서를 얻은 다음, verify가 나열한 가장 영향을 많이 받은 소스 파일에 대해 references/quality-rules.md에 따라 새 테스트를 작성하십시오: AAA 구조, 동작 중심 이름, 테스트당 하나의 동작, 외부 경계에서만 모의 사용. 세 개의 얕은 테스트보다 하나의 강력한 테스트가 실제 사용자 가시 동작을 커버하는 것을 선호하십시오.

5. 검증 (스크립트 — 완료를 결정)

node "$SKILL/dist/cli.mjs" verify --coverage-floor 0.97
# 선택적으로, 중요 모듈에만 해당 (느림):
node "$SKILL/dist/cli.mjs" verify --mutation --mutate "src/billing/**/*.ts" --mutation-floor 80

스위트를 다시 실행하고, 통과 상태여야 하며, 기준선 대비 라인 유지율이 기준을 충족해야 합니다. 종료 코드 0 = 완료; 종료 코드 1 = 수정 후 재실행 (더 많은 테스트 재생성 또는 삭제 복원); 종료 코드 2 = 환경 문제, 중지 및 보고. 변이 테스트는 느리기 때문에 모듈별로 옵트인됩니다. 사용자가 중요하다고 말하는 모듈에 대해 제공하십시오.

버전 2는 커버된 소스, 러너 구성, lockfile, 러너 및 커버리지 제공자의 지문을 기준선으로 삼습니다. verify가 출처 드리프트를 보고하면 새 기준선을 수집하십시오. --allow-provenance-drift는 명시적인 사용자 동의가 있을 때만 사용하고 결과 판결을 신뢰할 수 없는 것으로 보고하십시오. 레거시 v1 기준선도 마찬가지로 명시적인 --allow-legacy-baseline 이스케이프 해치가 필요합니다.

보고

사용자에게 요약: 이전 → 이후 단위 수, 라인/브랜치 유지율, 이전 → 이후 런타임, 발견된 슬롭 패턴 (개수 포함), 삭제 목록에서 구출된 테스트 및 이유, 재생성된 테스트, 최종 검증 판결. 전체 감사 추적을 위해 plan.md의 경로를 포함하십시오.

실패 모드

• 러너가 감지되지 않음 / 모호함 → CLI가 가이드와 함께 종료 코드 2로 종료됩니다. --runner 또는 --cwd를 전달하십시오 (모노레포: 패키지별로 실행).
• 불완전한 수집 → 격리된 실패를 수정하십시오. 계획을 통과시키기 위해 단순히 필터링하지 마십시오. 필터는 선언된 기준선 범위를 변경합니다. --keep-unmeasured는 보수적인 이스케이프 해치입니다.
• 재생성 후에도 검증이 계속 실패 → 약 3회 시도 후 루프를 중단하고, 남은 간격을 파일별로 제시하여 사용자가 기준을 낮출지 아니면 더 많은 테스트를 유지할지 결정하도록 하십시오.
• 시작 전에 스위트가 빨간색(실패) 상태 → 관련 없는 실패를 조용히 "수정"하지 말고 보고하고 먼저 범위에 동의하십시오.