Files
clean-architecture-frontend…/docs/work/reference/testing.md
T
DongHyeonka ceaf316f65
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 / main / self-tests and removal drills (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
test(setup): 시험 timeout을 모두 desktop 실측값으로 주고 손 숫자를 거절한다
문제: 자식 프로세스 시험의 timeout은 `childProcessTimeout(<잰 ms>)`로
정한다(docs/work/reference/testing.md 2절). 그런데 기본값이 아니라서
`tests/setup.ts` 검사에 걸리지 않는 손 숫자가 남았다. 리뷰가 센 54곳 중
둘(`browser-soak.contract.test.ts`의 `evaluateSoak` 인자)은 timeout이 아니고,
AST로 다시 세면 80곳이다: 시험·describe·hook에 쓴 숫자, `VERIFY_TIMEOUT`·
`PROCESS_HEAVY_TIMEOUT_MS`(파일 넷에 따로)·`PROVIDER_BASE_FIXTURE_TIMEOUT_MS`
같은 상수, `PROCESS_WATCHDOG_MS * 3` 같은 식. taxonomy는 옛 상수를 예로
들었다. 실측으로 보면 손 숫자 하나가 모자랐다: system 시험의 provider 묶음
30초는 desktop 여섯 번 중 두 번 넘겼다.

고친 것:
- 80곳을 desktop에서 잰 가장 긴 실행으로 `childProcessTimeout(<ms>)`에
  넘긴다. coverage 묶음(maxWorkers=4)·test:unit 각 9회, integration 3회,
  scale(traffic·session·composition·global-local) 3회, 시스템 컨테이너의
  tests/system 6회, JSON reporter로 받았다. hook은 파일 시간에서 시험 합을
  뺀 값이다. 시간 초과로 끝난 실행은 그 시간을 하한으로 넣었다.
- 상수 사본은 지운다. 한 파일 안에서 여럿이 쓰는 값만
  `const X = childProcessTimeout(...)`로 둔다(`VERIFY_TIMEOUT`). guardian
  시험의 lease는 시험 timeout이 아니라 `childProcessTimeout(0)`(helper의 최소
  30초)로 둔다.
- `tests/unit/test-timeout-declarations.test.ts`가 tests/의 Vitest 파일을
  Babel로 읽어 시험·describe·hook의 timeout 인자가 helper 호출(또는 그것을
  담은 파일 상수)이 아니면 파일과 줄로 실패한다. 프로세스 안에서 도는 긴
  시험(scale tier)도 같은 helper를 쓴다.
- taxonomy 예시, testing.md 2절, `.claude/rules/tests.md` 9번, helper 머리
  주석을 같은 방법으로 맞춘다.

버린 대안:
- `tests/setup.ts` 검사를 「helper가 만든 값이 아닌 timeout」까지 넓히기.
  helper 값은 30초 단위 숫자라 손으로 쓴 60_000과 가릴 수 없고, hook과
  프로세스 안 시험은 보지 못한다.
- 프로세스 안 시험은 손 숫자 그대로 두기. 근거 없는 숫자가 남고 검사가
  예외를 가져야 한다.

위험·한계:
- 값이 커진 곳이 있다(15배 규칙): `manual-code-blocks` 300초 → 900초,
  provider 묶음 30초 → 480초 등. hang을 늦게 잡는다. 줄어든 곳도 있다
  (scale traffic 60초 → 30초 등, 잰 값의 15배 안).
- 측정은 desktop 부하 6~35에서 했다. runner가 더 느리면 다시 잰다.
- 검사 시험은 Vitest 파일 전부를 파싱해 coverage 묶음에서 최대 13.5초
  걸렸고, 그 값으로 자기 timeout을 준다. 이름 있는 함수를 콜백으로 넘긴
  시험(`it("x", run, 30_000)`)은 못 찾는다.
- 다운스트림: 손 숫자 timeout이 있는 제품 시험은 test:unit에서 이 검사에
  걸린다. 메시지가 helper를 알린다.

검증(desktop):
- RED: 검사 시험이 고치기 전 80곳을 파일·줄로 내고 실패. GREEN: 검사·
  child-process-timeout 6개 통과. check:types·eslint(바뀐 34파일) rc=0,
  verify:documentation PASS_SCOPED, 노트북 `scripts/verify.sh docs` OK.
- 측정 원자료: /tmp/claude-gates/w2fe2-t08m, -t08m2, -t08m3.
- 게이트 결과는 PR 본문에 적는다.

Refs: 1112/03-08
2026-11-13 06:47:02 +09:00

11 KiB

테스트 기준

테스트는 결함을 막는지로 평가한다. 테스트가 있다는 사실, 커버리지 숫자는 근거가 아니다. 이 repo의 테스트 결함은 여러 라운드 동안 같은 모양으로 반복됐다. 괄호 안 결함 패턴 X0은 defect-patterns.md의 행이다.

결함을 고쳐도·규칙을 지워도 통과한다        → 변이로 확인한다 (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은 시험·describe·hook 모두 이 helper로만 준다. 자식 프로세스를 띄우지 않는 긴 시험(scale tier의 부하 시험 등)도 같다. 손으로 쓴 숫자(60_000)나 숫자 상수(PROCESS_HEAVY_TIMEOUT_MS = 30_000)는 tests/unit/test-timeout-declarations.test.ts가 파일과 줄로 거절한다. 여러 시험이 같은 값을 쓰면 파일 위에 const X = childProcessTimeout(<그 시험들 중 가장 긴 ms>)로 둔다.
    • 기본 timeout인 테스트가 자식 프로세스를 띄우면 tests/setup.ts가 그 호출에서 실패시킨다. helper나 import한 스크립트가 띄워도 같다. hook(beforeAll 등)은 보지 않는다.
  • 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(tests/mocks/)를 쓴다(결함 패턴 T7). 생성물 탐침 이름은 예약 접두어(typecheck-probe-*)를 쓴다.
  • 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다(structure.md 4절).
  • 테스트 작성의 편집 직후 규칙은 .claude/rules/tests.md다(Claude Code는 테스트 파일을 열 때 읽는다).

3. 테스트가 결함을 막는지 확인하는 법

RED 먼저. 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 커밋 본문에 RED와 GREEN을 적는다. 이 규칙을 강제하는 게이트는 없다. 리뷰가 커밋 본문으로 확인한다.

변이로 검출력을 잰다.

  • 보호 규칙 한 줄을 지우거나 바꾸는 변이를 넣어, 그 규칙을 지키는 테스트가 실패하는지 본다. 결함 수정안을 넣었을 때 기존 테스트가 모두 통과하면 그 테스트는 결함을 막지 못했던 것이다(결함 패턴 T1).
  • 커버리지 100%인 곳에서도 판정 경계의 변이가 살아남았다. 커버리지는 줄을 지나갔다는 뜻일 뿐이다.
  • 변이 실험은 일괄 실행 목록으로 낸다. 리뷰어가 손으로 만들어 checkout 전체를 잠그며 돌리지 않는다(../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 4절)
고정 출력 경로·고정 포트 한 checkout에서 두 실행이 부딪힌다 브라우저 테스트는 실행마다 TEST_RUN_ID, 서버는 빈 포트. ci:gate는 한 checkout에서 하나씩(결함 패턴 G4)
호스트 권한(user namespace 등) 사전 점검 PASS 뒤 원문 오류 사전 점검이 본 단계와 같은 방법으로 한 번 실행해 본다(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분)과의 여유를 본다.