Files
clean-architecture-frontend…/docs/work/reference/testing.md
T
DongHyeonka f81dda4913
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m23s
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-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (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
frontend-quality-gates / merge / tests (pull_request) Canceled after 11m31s
test(e2e): Firefox 브라우저 프로필을 RAM 파일시스템에 둔다
FE-GATE-008의 Firefox 시험이 가끔 첫 화면 5초 대기에서 실패한다
(old-tab-chunk-recovery.spec.ts, preload-use.spec.ts,
platform-overview.spec.ts). runner run 127과 desktop merge 검증에서
실패했고, 다시 돌리면 통과해 묻혔다.
Playwright는 Firefox 프로필을 os.tmpdir()에 만든다. desktop과 CI job
모두 /tmp가 같은 SATA SSD 위에 있다. Firefox는 시험 context의
localStorage·IndexedDB를 그 프로필(디스크)에 둔다. 그래서 디스크가
붐비면 context마다 첫 localStorage 접근이 디스크 일을 기다린다.
Chromium·WebKit은 시험 context 저장소를 메모리에 둔다. 앱은 첫 렌더
전에 색 구성 설정을 localStorage에서 읽어, 그 대기가 첫 화면 대기에
들어간다. desktop e2e 전체 8회(2026-11-13)에서 Firefox 앱 부팅 463회
중 19회가 0.7~3.8초 멈췄고, Chromium·WebKit은 16 ms를 넘지 않았다.

tests/support/browser/browser-test.ts가 Firefox worker의 프로필을 RAM
파일시스템에 둔다. os.tmpdir()가 이미 tmpfs면 그대로 쓴다. 아니면
/dev/shm에 worker 수 x 64 MB 자리가 있을 때 그 안에 폴더를 만든다.
Playwright의 browser fixture가 launch하는 동안만 TMPDIR를 그 폴더로
돌리고 바로 되돌린다. 그래서 fixture build 같은 다른 임시 파일은
디스크에 그대로 남는다. 프로필이 그 폴더에 생기지 않으면 시험을
실패시킨다. 자리가 없으면 이유를 한 줄 알리고 디스크에 둔다. strict
fixture와 strict를 쓰지 않는 spec 둘(preload-use, chunk-load-error)이
이 test를 바탕으로 쓴다. docs/work/reference/testing.md 5절 표에 원인을
적었다.

버린 대안:
- worker마다 localStorage를 미리 한 번 건드리는 예열: 브라우저 프로세스당
  한 번 드는 준비 비용으로 봤다. 예열 뒤에도 19/463이 멈췄다. 예열
  context를 바로 닫는 판은 21/464로 더 나빴다.
- toolkit.storage.synchronous=0(SQLite fsync 끔): 15/224로 그대로였다.
- 첫 화면 대기 timeout 늘리기, worker 줄이기: 원인을 덮는다.
- 시험 실행 전체에 TMPDIR 걸기: fixture build까지 RAM에 들어간다.

위험·한계:
- CI job 컨테이너는 /dev/shm이 64 MB다(2026-11-13 runner 확인). /tmp는
  같은 SSD 위에 있다. 그래서 CI에서는 프로필이 디스크에 남고 로그에
  이유가 한 줄 찍힌다. CI까지 고치려면 runner가 job 컨테이너에 RAM
  자리를 줘야 한다(--shm-size 또는 --tmpfs /tmp). runner 설정이라 이
  커밋에 넣지 않았다.
- 64 MB/worker는 Firefox worker 6개 프로필 합이 가장 컸을 때 211 MB(1개
  35 MB)인 것을 보고 잡은 여유다.
- Playwright의 두 동작에 기댄다. fixture 의존성을 적힌 순서로 준비하는
  것과, launch할 때 os.tmpdir()를 읽는 것이다. 어느 쪽이 바뀌어도
  폴더가 비므로 시험이 실패해 알린다.

검증(desktop):
- 재현: Firefox 6개를 동시에 띄우고 context 8개씩 localStorage 첫 접근을
  쟀다. 프로필 /tmp에서 최대 8,157 ms(384회), /dev/shm에서 최대 17 ms
  (384회).
- 수정본 e2e 전체 10회: 매번 189 passed. Firefox 부팅 576회 중 0.5초를
  넘는 멈춤 0회(최대 36 ms), 부하 15.9~31.2. 프로필은 매번 /dev/shm에
  5~6개, 디스크 0개, 끝난 뒤 남은 폴더 0개.
- 변이: launch 전에 TMPDIR를 돌리지 않게 하면 theme.spec.ts(firefox)가
  2 failed, 안전장치 메시지로 실패한다.
- check:types:test, eslint(바뀐 파일), check:test-evidence:source 통과.
- scripts/verify.sh gate FE-GATE-008(CI=true, main ee95573f 위): rc=0 205초,
  e2e 189 passed, browser-capabilities 69, storybook 11, visual 7.
- scripts/verify.sh docs, desktop verify:documentation 통과.
2026-11-13 18:13:17 +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-*, scripts/lib/template-probe-features.ts)를 쓴다. 사본에는 제품 기능이 들어 있어, 흔한 업무 이름이나 매뉴얼 예시 이름을 쓰면 그 이름의 기능을 만든 제품에서 생성 명령이 거부한다.
  • 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다(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을 선언한다
브라우저가 붐비는 디스크를 기다린다 Firefox는 시험 context의 localStorage를 디스크의 프로필에 둔다. runner와 같이 쓰는 desktop SSD에서 context마다 첫 접근이 최대 8.2초 멈췄고, 첫 화면 5초 대기 안에서 실패했다. 프로필을 /dev/shm에 두면 최대 17 ms Firefox 프로필은 RAM 파일시스템에 둔다(tests/support/browser/browser-test.ts). 자리가 없으면 그 사실과 이유를 한 줄로 알린다

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분)과의 여유를 본다.