Files
clean-architecture-frontend…/docs/work/reference/testing.md
T
DongHyeonka ed8c62041a
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
Merge remote-tracking branch 'origin/main' into fix/r9-reserved-probe-feature-ids
2026-11-13 04:29:30 +09:00

109 lines
10 KiB
Markdown

# 테스트 기준
테스트는 **결함을 막는지**로 평가한다. 테스트가 있다는 사실, 커버리지 숫자는 근거가 아니다. 이 repo의 테스트 결함은 여러 라운드 동안 같은 모양으로 반복됐다. 괄호 안 `결함 패턴 X0`은 [defect-patterns.md](defect-patterns.md)의 행이다.
```text
결함을 고쳐도·규칙을 지워도 통과한다 → 변이로 확인한다 (3절)
템플릿 원래 상태·작은 입력에서만 맞다 → 기능 추가·확장 지점 채움·입력 3개 이상으로도 돈다 (3절)
속도·부하·브라우저 추정에 기댄다 → 결정적 재현으로 원인을 찾는다 (5절)
고정 경로·포트·로컬 생성물에 기댄다 → 깨끗한 clone·한 checkout 두 실행으로 확인한다 (4절)
```
## 1. 정본
| 무엇 | 정본 |
| --- | --- |
| 테스트 층, 명령, 실행 환경, 층을 정하는 기준 | `docs/testing/taxonomy.md` |
| 넓은 테스트 설계, flaky 정책, 금지 패턴 | `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md`. 쓴 때의 설계서라 지금 코드와 다른 곳이 있다. 다르면 코드가 맞다 |
| Vitest 수집 범위, `.only` 금지, 전역 timeout | `vitest.config.ts` |
| Vitest 실행 runner(Node 버전, `NODE_ENV`, 생성물) | `scripts/run-vitest.ts` |
| Playwright skip·fixme의 quarantine 조건, `forbidOnly` | `scripts/check-test-evidence.ts` |
| 테스트 공통 대기 기한 | `tests/setup.ts` |
| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci:gating`(main 단계 FE-GATE-029), 예외 목록 `config/ci/ungated-tests.json` |
| 지워도 되는 문서를 테스트가 읽지 않는다 | `tests/unit/deletable-history-documents.test.ts` |
## 2. 테스트를 어디에 둘까
`docs/testing/taxonomy.md`가 기준이다. **프레임워크가 아니라 필요한 실행 환경**이 층을 정한다.
| 필요한 것 | 둘 곳 | 명령 |
| --- | --- | --- |
| Node만(도메인·정책·순수 함수, 스크립트의 짧은 CLI 계약) | `tests/unit` | `test:unit` |
| 재사용 capability의 소비자 계약 | `tests/contract` | `test:contract` |
| React·hook·UI 동작 | `tests/component` | `test:component` |
| HTTP/MSW, IndexedDB, 조립된 경계, 오래 사는 자식 프로세스 | `tests/integration` | `test:integration` |
| systemd·bubblewrap·cgroup v2 | `tests/system` | `test:system`(FE-GATE-013) |
| 실제 브라우저 3엔진 | `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook` | FE-GATE-008·009 |
| 한 기능의 테스트 | `tests/features/<id>/` | 기능 폴더와 함께 지워진다 |
- 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다.
- 값은 desktop에서 잰 가장 긴 실행으로 정한다: `childProcessTimeout(<ms>)`(`tests/helpers/child-process-timeout.ts`). 부하가 높은 desktop에서 자식 프로세스 테스트가 평소보다 몇 배 느려진 실측을 근거로 둔다.
- 기본 timeout인 테스트가 자식 프로세스를 띄우면 `tests/setup.ts`가 그 호출에서 실패시킨다. helper나 import한 스크립트가 띄워도 같다. hook(`beforeAll` 등)은 보지 않는다.
- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 템플릿 시험이 저장소 사본에 만드는 기능과 생성물 탐침의 이름은 예약 접두어(`typecheck-probe-*`, `scripts/lib/template-probe-features.ts`)를 쓴다. 사본에는 제품 기능이 들어 있어, 흔한 업무 이름이나 매뉴얼 예시 이름을 쓰면 그 이름의 기능을 만든 제품에서 생성 명령이 거부한다.
- 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다([structure.md](structure.md) 4절).
- 테스트 작성의 편집 직후 규칙은 `.claude/rules/tests.md`다(Claude Code는 테스트 파일을 열 때 읽는다).
## 3. 테스트가 결함을 막는지 확인하는 법
**RED 먼저.** 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 커밋 본문에 RED와 GREEN을 적는다. 이 규칙을 강제하는 게이트는 없다. 리뷰가 커밋 본문으로 확인한다.
**변이로 검출력을 잰다.**
- 보호 규칙 한 줄을 지우거나 바꾸는 변이를 넣어, 그 규칙을 지키는 테스트가 실패하는지 본다. 결함 수정안을 넣었을 때 기존 테스트가 모두 통과하면 그 테스트는 결함을 막지 못했던 것이다(결함 패턴 T1).
- 커버리지 100%인 곳에서도 판정 경계의 변이가 살아남았다. 커버리지는 줄을 지나갔다는 뜻일 뿐이다.
- 변이 실험은 일괄 실행 목록으로 낸다. 리뷰어가 손으로 만들어 checkout 전체를 잠그며 돌리지 않는다([../delegate.md](../delegate.md) 4.2절).
**템플릿 원래 상태 밖에서도 돈다.** 수정을 템플릿 원래 상태나 작은 입력으로만 확인하면 다운스트림에서 다시 결함이 된다(결함 패턴 G2).
| 확인할 상태 | 지난 예 |
| --- | --- |
| 기능을 하나 이상 더한 상태(`create:feature`) | 기능을 더하면 시각 테스트가 실패했다 |
| 제품 확장 지점을 채운 상태 | 타입 검사 탐침이 제품 파일을 통째로 덮어써 제품 capability가 있는 사본에서 FE-GATE-005가 항상 실패했다 |
| 예제 기능을 지운 상태 | CHANGELOG 안내대로 예제를 지우면 문서 검사가 실패했다 |
| 입력·객체가 셋 이상 | purge 수정 테스트가 객체 0~1개만 써서 3개 이상의 결함을 놓쳤다 |
| 매뉴얼 예시 이름으로 만든 기능 | 템플릿 테스트의 글자가 제품 기능 이름과 부딪쳐 제거 드릴이 실패했다 |
**단언이 대상에 닿는가.** fixture가 비어 첫 줄에서 return하지 않는가. 전제(예: 포커스가 먼저 옮겨졌는가)를 함께 단언하는가. 실제 화면이 아니라 로딩 화면·오류 화면·fixture 자신을 검사하지 않는가. 접근성 e2e가 기능의 빈 목록이 아니라 오류 화면을 검사하고 "passed"로 적은 일이 있다(결함 패턴 T2).
## 4. 환경에 기대지 않는다
| 기대는 것 | 증상 | 기준 |
| --- | --- | --- |
| gitignore된 로컬 생성물 | 깨끗한 clone에서 실패 | 테스트가 필요한 생성물을 스스로 만든다. 한 파일 실행도 `scripts/run-vitest.ts`를 거친다 |
| 작성자 PC의 글꼴·CPU | 다른 호스트에서 시각·규모 테스트 실패 | 글꼴은 `fonts.conf`로 고정한다. 규모 테스트는 CPU와 무관한 비교만 단언한다 |
| 바깥 env(빌드 식별값, `CI=true`) | 실제 CI에서만 실패 | 테스트가 띄우는 빌드·dev server의 env는 테스트가 정한다([gates.md](gates.md) 4절) |
| 고정 출력 경로·고정 포트 | 한 checkout에서 두 실행이 부딪힌다 | 브라우저 테스트는 실행마다 `TEST_RUN_ID`, 서버는 빈 포트. `ci:gate`는 한 checkout에서 하나씩(결함 패턴 G4) |
| 호스트 권한(user namespace 등) | 사전 점검 PASS 뒤 원문 오류 | 사전 점검이 본 단계와 같은 방법으로 한 번 실행해 본다([gates.md](gates.md) 5절) |
| 옆 checkout(짝 백엔드) | 기계마다 결과가 다르다 | 없으면 "확인 못 함"으로 보고한다 |
## 5. 가끔 떨어지는 테스트
**금지.**
- 재시도, timeout 늘리기, worker 줄이기, `force` 클릭·합성 이벤트로 덮지 않는다.
- skip은 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`). 빠른 계층에는 quarantine이 없다. 고치거나 느린 층으로 옮긴다(소유자 결정 2026-11-03).
- "부하 탓"으로 닫지 않는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다. 부하 탓으로 적었던 두 실패가 모두 테스트 결함이었다.
**조사 절차.**
1. 반복 실행으로 빈도를 잰다. 같은 조건에서 30회씩 돌려 실패 수를 적는다.
2. 실패 기록을 남긴다. 이벤트 순서(pointerdown·pointerup·click 대상), 위치, 시각, 네트워크 로그를 실패한 실행에서 모은다. 진단용 코드는 별도 브랜치에 둔다.
3. 결정적 재현을 만든다. 원인이라고 본 조건을 강제로 만들어 매번 실패하게 한다. 예: mousedown 때 앱 높이를 늘리면 세 엔진 6/6 실패, 모듈 응답을 3.5초 늦추면 WebKit 경고 2/2.
4. 고친다. 고친 뒤 결정적 재현이 통과하고, 실제 조건 반복 실행에서 실패 0인지 본다(예: 660/660).
5. 검사가 약해지지 않았는지 변이로 본다. 경고를 무시하게 고쳤으면, 원래 잡아야 할 것(정말 안 쓴 preload)을 여전히 잡는지 확인한다.
**브라우저 테스트에서 반복된 원인.**
| 원인 | 예 | 기준 |
| --- | --- | --- |
| 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 "preload를 안 썼다" 추정. 곧 쓰일 preload로 가끔 실패하고, 정말 안 쓴 preload는 놓쳤다 | 경고 대신 확인하려는 사실(preload가 평가됐는가)을 직접 검사한다(결함 패턴 T4) |
| 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 12 px 밀려 클릭이 닿지 않았다 | 테스트가 붙이는 조작 요소는 앱 레이아웃과 무관한 고정 층에 둔다. "다 그려질 때까지 기다리기"는 신호가 없어 쓰지 않는다(결함 패턴 T5) |
| 짧은 상태를 폴링으로 잡는다 | 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려다 두 엔진에서 실패 | 상태 변화를 이벤트·기록으로 받는다 |
| 고정 상한과 첫 실행 비용 | provider 테스트 10개가 10초 상한에 묶이고, 하나만 고르면 첫 테스트가 fixture 빌드를 떠안아 실패 | 무거운 준비는 suite 준비 단계로 옮기고 suite가 자기 timeout을 선언한다 |
## 6. 테스트 실행 비용
- 빠른 계층(`tests/unit`)에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이면 전체가 느려진다(결함 패턴 T8).
- merge 단계가 같은 파일을 두 번 돌리지 않는지 본다.
- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 선택 runtime 드릴 셋을 FE-GATE-030(main 단계)으로 넘기기 전 desktop 630초, runner 13분 13초였다(2026-11-13, PR #19). job 상한(45분)과의 여유를 본다.