Files
donghyeon.kang 32d7b06e0a
frontend-quality-gates / merge / static checks (push) Canceled after 0s
frontend-quality-gates / merge / tests (push) Canceled after 0s
frontend-quality-gates / merge / browser tests (push) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (push) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (push) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (push) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (push) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (push) Canceled after 0s
frontend-quality-gates / external-provenance-provider (push) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (push) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (push) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (push) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (push) Canceled after 0s
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (push) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (push) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (push) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (push) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (push) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (push) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (push) Canceled after 0s
Merge pull request 'docs(ledger): 흔들린 시험 기록을 두고 시간·순서 단언 규칙을 가리킨다' (#50) from donghyeon.kang/docs/flaky-ledger into main
2026-11-13 15:27:29 +00:00

12 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)을 여전히 잡는지 확인한다.
  6. 처음 본 날 docs/ledger/flaky-tests.jsonl에 한 줄 남긴다. 고치면 같은 test로 fixed_by를 채운 줄을 더한다(칸은 docs/ledger/README.md 「흔들림 기록」).

브라우저 테스트에서 반복된 원인.

원인 예 기준
브라우저의 추정에 기댄다 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분)과의 여유를 본다.