unit-test

name	unit-test
description	기능 단위 테스트 오케스트레이터. Git Diff/사용자 지정 범위에서 테스트 대상을 결정하고, 사용자 시나리오 스토리보드 → 테스트케이스 생성 → Playwright MCP 실행 → 결과 보고. '/unit-test', '단위테스트', '테스트해줘', '기능 테스트' 등 언급 시 호출. 시나리오 단위 회귀 검증(PASS/FAIL/WARN)에 사용하며, 버그 원인 특정·로그 삽입 디버깅이 필요하면 debugger 계열 스킬을 쓴다.
argument-hint	[테스트 대상 기능명 또는 범위] [--happy-only] [--auto] [--fix] [--no-ux-review] [--strict-visual] [--gate-visual]

UNIT-TEST 기능 단위 테스트

$ARGUMENTS 에 대해 아래 파이프라인을 실행한다.

SCOPE → STORYBOARD → GENERATE → EXECUTE (+ 4.5 VISUAL-UX) → REPORT

---

분기 — 검증 vs 디버깅

상황	사용 방식	이유
기능이 의도대로 동작하는지 검증 (PASS/FAIL/WARN)	/unit-test	시나리오 단위 회귀 검증
버그 현상 발생 — 원인 특정 필요	디버깅 워크플로우(예: debugger 스킬)	가설 도출 → 로그 삽입 → 재현 → 수정/정리
신규 구현 직후 동작 확인	/unit-test --happy-only	빠른 정상 흐름 검증
FAIL 발견 후 원인 추적·수정	디버깅 워크플로우로 전환	unit-test는 검증만, 로그 삽입·정리 미수행

--fix 플래그가 있어도 unit-test는 단순 재실행(최대 2회)만 수행. 원인 분석·로그 삽입·grep 검증이 필요하면 디버깅 워크플로우로 전환한다.

정적 단위 테스트 게이트와의 관계 (네이밍 주의): 이 스킬은 이름은 "unit-test"지만 실제로는 Playwright 기반 E2E/시나리오 동적 검증이다. vitest/jest 같은 정적 단위 테스트와는 레이어가 다르다 — 둘은 충돌이 아니라 상보다. 정적 단위 테스트(npm test)는 CI/빌드 게이트에서, 시나리오 동적 검증은 이 스킬에서 담당한다.

---

옵션 플래그

플래그	설명
--happy-only	Happy Path 시나리오만 생성 (빠른 검증)
--auto	승인 없이 전체 파이프라인 연속 실행
--fix	FAIL 발견 시 자동 수정 + 재검증
--no-ux-review	Phase 4.5 Section B(LLM 폴리시 제안)만 스킵. Section A(design-lint 게이트)는 저비용이라 이 플래그와 무관하게 항상 실행(설치돼 있을 때)
--strict-visual	Phase 4.5 Section A에 design-lint --strict를 전달(형제 겹침 D-LAYOUT-11 활성, low-confidence 기본 off). design-lint 미설치 시 무의미
--gate-visual	Phase 4.5 Section A에 design-lint --gate-runtime을 전달(문서 레벨 가로 오버플로우만 error로 격상 — 해당 시나리오를 FAIL 취급). design-lint 미설치 시 무의미

---

Phase 1: SCOPE (테스트 범위 결정)

테스트 대상을 아래 우선순위로 결정한다.

우선순위	소스	조건	수집 방법
1	사용자 지정	$ARGUMENTS에 명시적 범위 존재	인자 파싱
2	Git Diff	인자 미지정 시	git diff HEAD~1 --name-only + git diff --cached --name-only → 변경 파일에서 기능 영역 추론
3	최근 작업 맥락	Diff도 없을 시 (non-git 또는 clean 상태)	프로젝트의 최근 완료 작업/이슈 기록(있으면)에서 대상 추론, 없으면 사용자에게 대상 확인

1-1. 변경 파일 분석

수집된 파일 목록에서:

1. 테스트와 무관한 파일 제외 (설정 파일, README, 스타일만 변경 등)
2. 남은 파일들의 기능 영역 분류 (컴포넌트, 훅, 유틸, 페이지 등)
3. 각 파일을 읽어 사용자에게 노출되는 동작 파악

1-2. 진입점 결정

프로젝트 설정(CLAUDE.md·README·package.json 스크립트 등)에서 개발 서버 포트를 확인하고, 대상 기능의 접근 경로를 결정한다.

1-3. 산출물

[테스트 범위]
대상 기능: {기능명}
소스: 사용자 지정 / Git Diff / 최근 작업 맥락
관련 파일: file1.tsx, file2.ts, ...
진입점 URL: http://localhost:{port}/{path}
선행 조건: {로그인 필요, 특정 데이터 존재 등}

---

Phase 2: STORYBOARD (사용자 시나리오 설계)

대상 기능의 코드를 읽고 실제 사용자가 수행할 동작 흐름을 예측한다.

2-1. 시나리오 분류

유형	설명	예시
Happy Path	정상 흐름 (필수, 항상 포함)	폼 입력 → 제출 → 성공 메시지
Edge Case	경계값·빈값·긴 문자열	빈 입력 제출, 특수문자 포함
Error Path	의도적 오류 유발	잘못된 형식 입력, 필수값 누락
Interaction	복합 인터랙션	드래그앤드롭, 키보드 단축키, 연속 클릭

--happy-only 플래그 시 Happy Path만 생성한다.

2-2. 시나리오 작성

각 시나리오를 아래 형식으로 작성한다:

[S-{N}] {시나리오명}
유형: Happy Path / Edge Case / Error Path / Interaction
전제 조건: {초기 상태 — 페이지, 데이터, 로그인 등}
사용자 동작:
  1. {동작} → 기대 반응: {UI 변화}
  2. {동작} → 기대 반응: {UI 변화}
  ...
최종 기대 결과: {상태 / UI / 데이터}

2-3. 사용자 승인

시나리오 목록을 사용자에게 보여주고 피드백을 받는다.

응답	동작
승인 ("ok", "진행해")	Phase 3으로 진행
수정 지시	시나리오 추가/제거/수정 후 재승인
취소	파이프라인 중단

--auto 플래그 시 승인 없이 즉시 Phase 3으로 진행한다.

---

Phase 3: GENERATE (테스트케이스 생성)

승인된 시나리오를 Playwright MCP 명령 시퀀스로 변환한다.

3-1. 시나리오별 생성 항목

항목	내용
입력 데이터	각 인터랙션에 사용할 구체적 값 (텍스트, 클릭 대상, 키 조합)
기대 출력	스냅샷에서 확인할 요소 (텍스트 내용, ARIA 속성, 요소 존재/부재)
검증 기준	PASS/FAIL 판정 조건 (정확히 어떤 상태를 확인하는지)
MCP 명령 시퀀스	Playwright MCP 도구 호출 순서

3-2. 명령 시퀀스 구성 규칙

시나리오 시작:
  → browser_navigate(url)          # 초기 상태로 이동
  → browser_snapshot()             # 초기 상태 확인

동작 수행:
  → browser_click(element)         # 클릭
  → browser_type(element, text)    # 텍스트 입력
  → browser_press_key(key)         # 키보드 입력
  → browser_select_option(...)     # 셀렉트 변경

검증:
  → browser_snapshot()             # 결과 상태 캡처
  → browser_console_messages()     # 콘솔 에러 수집
  → 기대 출력과 비교               # PASS / FAIL 판정

3-3. 검증 판정 기준

조건	판정
기대 요소 존재 + 콘솔 에러 없음	PASS
기대 요소 존재 + 콘솔 경고만 있음	WARN
기대 요소 부재 또는 콘솔 에러 존재	FAIL

이 표는 기능(콘솔·DOM) 판정 전용이며 상태값(PASS/FAIL/WARN)은 이 조건에서만 바뀐다. "동작은 정상인데 시각적으로 깨진 것"(오버플로우·텍스트 잘림·버튼 텍스트 초과)은 이 표를 건드리지 않는다 — Phase 4.5에서 별도 애노테이션(🎨 UX결함)으로만 부가한다. 두 레이어를 섞지 않는 이유: 기능 회귀와 시각 폴리시는 원인·수정 담당·긴급도가 다르고, 섞으면 "왜 PASS였던 시나리오가 갑자기 FAIL됐지"를 콘솔 에러 때문인지 레이아웃 때문인지 구분 못 하게 된다.

3-4. 안전장치

• 스냅샷 전 핵심 DOM 요소 존재 확인 — SPA 라우팅/렌더링 완료 대기
• 비결정적 데이터(타임스탬프, UUID 등)는 존재 여부만 검증, 정확한 값 비교 제외
• 암호화 필드는 UI 레벨 표시값으로만 검증

---

Phase 4: EXECUTE (테스트 실행)

4-0. 사전 체크

① 테스트용 백엔드 서비스 확인 (해당 시)

테스트에 DB·Redis 등 백엔드 서비스가 필요하면, 프로젝트의 기존 방식(예: docker-compose up -d, 로컬 서비스, .env의 테스트용 접속 정보)으로 기동한다. 이 스킬은 별도 인프라를 제공하지 않는다 — 운영 데이터를 건드리지 않도록 테스트 전용 인스턴스/DB를 사용하는 것을 권장한다.

• 백엔드가 필요 없는 순수 프론트엔드/정적 대상이면 이 단계는 스킵.

② 개발 서버 실행 여부 확인

browser_navigate → 진입점 URL

미실행 시 → 사용자에게 안내 후 파이프라인 중단

⚠ 개발 서버가 실행되지 않았습니다.
→ 개발 서버를 실행한 후 다시 /unit-test 를 실행해 주세요.

4-1. 실행 루프

각 시나리오를 순서대로 실행한다:

for each scenario S-{N}:
  1. browser_navigate → 초기 URL (매 시나리오마다 초기화)
  2. browser_snapshot → 초기 상태 확인
  3. 동작 시퀀스 실행 (click, type, press_key 등)
     - 각 동작 후 필요 시 중간 스냅샷으로 상태 확인
     - 시나리오 유형이 Interaction(드래그앤드롭·키보드단축키·연속클릭 등 과도기 상태가 있는 유형)이면
       중간 스냅샷 시점에도 Phase 4.5 Section A를 조건부 실행한다 — 드롭다운 열림·호버 툴팁처럼
       "동작 중"에만 나타나고 최종 정착 상태에선 사라지는 시각 결함은 최종 스냅샷만 봐서는 놓친다.
  4. browser_snapshot → 최종 상태 캡처
  5. browser_console_messages → 에러 수집
  6. 기대 출력 vs 실제 결과 비교 → PASS / FAIL / WARN (기능 판정, 3-3 기준)
  7. Phase 4.5 VISUAL-UX 실행 → 이 시나리오의 시각 결함을 별도 애노테이션으로 수집 (상태값은 안 바꿈)

4-2. FAIL 처리

• 실패 시나리오의 스냅샷 상태 + 콘솔 에러 + 기대값/실제값 차이를 기록
• 다음 시나리오는 계속 진행 (전체 중단하지 않음)
• --fix 플래그 시: FAIL 발견 즉시 코드 수정 → 해당 시나리오만 재실행 (최대 2회)
• Phase 4.5의 시각 결함(UX결함)은 --fix 트리거 대상이 아니다. --fix는 기능 FAIL(3-3 기준: 기대요소 부재/콘솔에러) 전용이며, 시각 결함은 게이트가 아니라 보고 항목이므로 자동 수정 흐름에 섞이지 않는다.

4-3. Chrome DevTools MCP 에스컬레이션 (FAIL 원인 불명 시, 선택)

Playwright browser_console_messages로 원인 특정 불가 시, chrome-devtools MCP가 설치돼 있으면 순차 사용한다(이 플러그인은 playwright만 동봉하므로 chrome-devtools는 별도 설치 시에만 사용 가능). Playwright 도구 완료 후에만 호출 — 동시 사용 금지.

증상	사용할 DevTools 도구
API 요청 실패 의심	getNetworkRequests
응답 데이터 확인 필요	getNetworkRequests + 응답 바디
렌더링 성능 문제	getCoreWebVitals
원인 불명 — 현재 DOM 구조 확인	getDocument

DevTools 수집 완료 후 → Phase 5 REPORT에 원인 포함해서 보고. (chrome-devtools 미설치 시 이 단계는 스킵하고, 수집된 스냅샷·콘솔 정보만으로 보고한다.)

---

Phase 4.5: VISUAL-UX (동작은 정상, 시각만 깨진 것 검사)

왜 별도 Phase인가: Phase 3-3의 기능 판정(PASS/FAIL/WARN)은 "의도대로 동작하는가"만 본다. "동작은 되는데 인터랙션 후 섹션이 틀어지거나, 버튼 텍스트가 잘리거나, 카드가 겹치는" 건 기능 버그가 아니라 UX 결함이라 별도 레이어로 다룬다. 각 시나리오의 (최종, 그리고 Interaction 유형은 필요 시 중간) 스냅샷 직후 실행하며, Section A/B는 신뢰수준이 다르므로 REPORT에서 항상 구분 표기한다.

각 시나리오의 관측 대상 상태(4-1 step 3~4)에서:

사전 공통 — DOM 덤프 (Section A/B 공유 입력)

먼저 현재 상태의 DOM outerHTML을 인라인 <style> 형태로 1회 덤프한다. 이 덤프는 Section A(설치 시)와 Section B(실행 시) 양쪽이 재사용하므로, design-lint 설치 여부·--no-ux-review 여부와 무관하게 항상 생성한다(재수집 금지).

A. 결정론 게이트 — design-lint 런타임 detector (design-lint 플러그인이 함께 설치돼 있으면)

같은 마켓의 design-lint 플러그인이 설치돼 있으면 아래를 실행한다(미설치 시 Section A 전체 스킵 — 이 스킬은 자립적으로 동작하며 design-lint는 선택적 강화다):

1. browser_evaluate('document.fonts.ready')로 폰트 로딩 완료를 먼저 대기한다(웹폰트 스왑 전 관측은 폴백폰트 metric으로 인한 일시적 오버플로우 오탐을 유발).
2. design-lint의 --observe-snippet으로 관측 스니펫을 얻어 browser_evaluate에 주입 → 반환 배열을 obs.json으로 저장 (뷰포트 1280×800 고정 필수 — Section A 전체의 결정론 전제).
3. design-lint를 <dump.html>(위 공통 덤프) --observed obs.json [--strict-visual 시 --strict] [--gate-visual 시 --gate-runtime]로 실행한다.
4. D-LAYOUT-08(가로 오버플로우) · D-LAYOUT-09(텍스트 잘림) · D-LAYOUT-10(버튼 텍스트 초과) · (--strict-visual 시) D-LAYOUT-11(형제 겹침, low-confidence) warn을 수집.
5. 판정에 영향 없음 — 기능 PASS는 그대로 유지, 발견된 항목은 시나리오에 🎨 UX결함 애노테이션으로만 부가한다. 단 --gate-visual로 문서 레벨(html/body) 가로 오버플로우가 error로 격상된 경우는 해당 시나리오를 예외적으로 FAIL 취급한다(명시적 opt-in 시에만).

design-lint를 호출할 때 플러그인 설치 경로를 하드코딩하지 않는다 — 슬래시 커맨드/스킬로 노출된 형태를 사용하거나, 프로젝트에 스크립트가 존재하면 그 경로로 호출한다. 경로를 모르면 Section A를 건너뛰고 Section B(스크린샷 기반)만 수행한다.

B. 폴리시 제안 — LLM 리뷰 (--no-ux-review 시 스킵)

• 입력: 현재 상태 스크린샷 + 위 공통 DOM 덤프(재수집 금지).
• references/interface-polish-rules.md의 9룰(concentric radius·optical alignment·shadow depth·text-wrap·font-smoothing·image outline·motion enter/exit 비대칭·press state·tabular-nums)을 참고해 "동작은 OK지만 미감이 아쉬운" 항목을 제안.
• 게이트 아님, 참고용(비재현) — PASS/FAIL/WARN 상태값도, --fix 트리거도 건드리지 않는다.
• 비용 통제: Section A(설치 시)가 이미 결함을 찾은 시나리오만 우선 실행하거나(권장), --no-ux-review로 전체 스킵 가능. --happy-only와는 무관하게 저비용 항목은 유지하고 고비용 LLM 리뷰만 통제한다.

---

Phase 5: REPORT (결과 보고)

5-1. 결과 요약

╔══════════════════════════════════════╗
║  Unit Test 결과                       ║
╠══════════════════════════════════════╣
║  대상: {기능명}                        ║
║  시나리오: {총}개 실행                  ║
║  ✅ PASS: {n}  ❌ FAIL: {n}  ⚠ WARN: {n} ║
║  🎨 UX결함: {n} (시각, 기능 상태 무관)   ║
╚══════════════════════════════════════╝

🎨 UX결함은 Phase 4.5에서 수집된 시각 결함 개수다. PASS/FAIL/WARN 집계와 별도이며 콘솔 경고(기존 WARN)와 절대 합산하지 않는다 — 원인(콘솔 vs 시각)을 구분 못 하게 되는 걸 막기 위함.

5-2. 시나리오별 상세

[S-1] ✅ {시나리오명} — PASS
[S-2] ❌ {시나리오명} — FAIL
  ├ 실패 지점: 동작 {N} 이후
  ├ 기대: {기대 상태}
  ├ 실제: {실제 상태}
  └ 콘솔: {에러 메시지 또는 "없음"}
[S-3] ⚠ {시나리오명} — WARN
  └ 경고: {콘솔 경고 내용}
[S-4] ✅ {시나리오명} — PASS  🎨 UX결함 2건
  ├ [A/게이트] D-LAYOUT-09 텍스트 잘림(말줄임 없음): .card-title
  ├ [A/게이트] D-LAYOUT-10 버튼 텍스트 초과: button.submit
  └ [B/제안·비재현] .cart-count에 tabular-nums 권장(자릿수 변할 때 흔들림)

5-3. 후속 액션

결과	동작
전체 PASS	완료 메시지 출력
FAIL 존재 + --fix	자동 수정 시도 (Phase 4-2에서 이미 처리)
FAIL 존재 + --fix 없음	사용자에게 수정 여부 확인

사용자 응답:

입력	동작
"수정해줘"	실패 원인 분석 → 코드 수정 → 실패 시나리오만 재실행
"괜찮아" / "종료"	보고서 출력 후 종료

---

Known Pitfalls

본 skill 실행 중 반복 발생한 실패 패턴. 신규 패턴 발견 시 entry를 추가한다.

(현재 누적 entry 없음.)

작성 형식

• [패턴명] — YYYY-MM-DD
  • 상황: 어떤 단계(시나리오 생성/실행/검증)·조건에서 발생
  • 원인: 무엇 때문에 실패 (시나리오 누락 / mock 오류 / 환경 문제 등)
  • 회피: 다음 실행 시 적용할 가이드

---