Files
clean-architecture-frontend…/docs/testing/taxonomy.md
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

7.9 KiB

테스트와 증거 분류

각 gate는 선언된 범위 안에서 차단한다. 실패를 continue-on-error나 경고만 내는 script로 낮추지 않는다.

실행 단계

단계 명령 담당 범위 / 전제 조건 증거
runtime schema pnpm test:runtime-schema 순수 runtime schema 계약 artifacts/tests/runtime-schema.xml
unit pnpm test:unit Node만 쓰는 domain·application·순수 정책·runtime 단위. systemd·bwrap·cgroup 전제 조건 없음 artifacts/tests/unit.xml
capability contract pnpm test:contract 재사용하는 capability의 소비자 계약 artifacts/tests/contract.xml
component pnpm test:component React·hook·UI 동작 artifacts/tests/component.xml
integration pnpm test:integration HTTP/MSW, IndexedDB, 조립된 browser-runtime 경계, 자식 프로세스·파일 시스템·IPC 통합 artifacts/tests/integration.xml
system / CI runner pnpm test:system systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제를 갖춘 호환 Linux host. 그 host에서 bubblewrap이 권한 없는 user namespace와 network namespace를 만들 수 있어야 한다. CI와 scripts/verify.sh는 FE-GATE-013을 scripts/run-in-system-container.sh가 띄우는 컨테이너 안에서 돌린다 artifacts/tests/system.xml
end-to-end pnpm test:e2e 버전을 고정한 브라우저 엔진 artifacts/tests/e2e/
accessibility pnpm test:a11y 버전을 고정한 브라우저 엔진 artifacts/tests/a11y.json

test:all은 평소 제품 개발 루프다. 다음을 순서대로 돌린다: test:runtime-schema, test:unit, test:contract, test:component, test:integration, test:coverage가 돌리는 나머지(tests/features, 설치된 각 feature의 테스트, tests/scripts, tests/scale/browser-soak.contract.test.ts), test:platform(tests/platform과 tests/architecture), check:release-coherence, test:recipes (package.json의 test:all). 그래서 merge gate의 coverage 실행이 덮는 Vitest 경로는 모두 여기서도 돈다(tests/unit/test-all-paths.test.ts, 0929/10-05). test:system은 들어 있지 않다. CI runner 보증과 공급망 보증은 host 전제 조건이 달라서, 보증 경로에서 따로 명시적으로 부른다.

결정적인 테스트 프로세스

Vitest package script는 모두 scripts/run-vitest.ts를 거쳐 실행한다.

이 runner는 다음을 한다.

  1. suite가 시작하기 전에 repository가 지원하는 >=24.11.0 <25.0.0 범위 밖의 Node version을 거부한다.
  2. 부모 shell을 믿지 않고 NODE_ENV=test를 직접 정한다.
  3. Vitest가 시작하기 전에 host마다 다른 npm_config_userconfig, npm_config_prefix, npm_config_globalconfig 값을 지운다.

vitest.config.ts도 NODE_ENV=test를 고정한다. 그래서 Vitest를 직접 불러도 React의 production 동작이 실수로 선택되지 않는다.

테스트 파일 하나만 돌릴 때도 같은 runner를 쓴다.

node scripts/run-vitest.ts run tests/component/router.test.tsx

runner는 gitignore된 src/.generated/ 제품 index를 먼저 만든다(scripts/run-vitest.ts). 그래서 새로 clone한 곳에서도 동작한다. pnpm exec vitest run <file>를 직접 부르면 그 단계를 건너뛰고, Failed to resolve import "../.generated/product-feature-index.ts"로 실패한다. pnpm test:unit -- <file>은 실행 범위를 좁히지 않는다. script가 이미 tests/unit 디렉터리 전체를 넘기기 때문이다.

vitest.config.ts는 tests/**/*.test.{ts,tsx}만 모은다. Playwright의 *.spec.ts 파일은 Vitest 테스트가 아니다. tests/system/은 명령이 그 경로를 직접 지정할 때만 모은다(test:system이 그렇게 한다). 그래서 맨 vitest 실행은 CI runner suite를 시작하지 않는다.

저장소 사본을 build하는 e2e spec(fixture build)은 e2e 실행 하나에 한 번만 build한다. playwright.config.ts의 global setup이 공유 폴더를 만들고, 브라우저 project 셋 가운데 그 build에 처음 닿은 worker만 build한다. 나머지 worker는 그 결과를 기다려 쓴다 (tests/e2e/support/shared-fixture-builds.ts). 공유 폴더가 없는 실행(Vitest 시험, 다른 Playwright 설정)은 부를 때마다 자기 사본을 만든다. 다른 project가 같은 폴더를 쓰므로 시험은 build 폴더에 쓰지 않는다. 사본을 고치는 일은 build 전의 edit에서만 한다.

system suite는 추가로 scripts/check-system-test-prerequisites.ts를 돌린다. CI runner host가 필요한 Linux 기능을 갖추지 않으면 전제 조건 보고서 하나를 내고 실패한다. 실행 파일, cgroup v2, systemd bus 말고도, provider sandbox와 같은 namespace 옵션으로 bubblewrap을 /bin/true에 한 번 돌려 본다. 그래서 권한 없는 user namespace를 거부하는 host(kernel.apparmor_restrict_unprivileged_userns=1인 Ubuntu 23.10 이상)는 provider 테스트가 아니라 여기서 이름이 밝혀진 채 실패한다(1105/12-01, docs/operations/ci-quality-gates.md).

개발 경로

제품 feature:

  • 대상을 좁힌 feature·unit·component 테스트
  • 재사용 경계가 바뀌면 capability contract 테스트
  • type·lint·architecture
  • test:all

재사용 capability:

  • 대상을 좁힌 unit 테스트
  • capability contract 테스트
  • integration 테스트
  • type·lint·architecture

CI·release 보증:

  • test:system
  • 공급망·승격(promotion)·release gate

host 수준 프로세스·sandbox 테스트를 Vitest를 쓴다는 이유만으로 tests/unit에 두면 안 된다. 분류는 테스트 framework가 아니라 system 경계와 전제 조건을 따른다.

  • systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제가 필요한 테스트는 tests/system에 둔다.
  • 오래 사는 자식 프로세스 protocol의 테스트는 tests/integration에 둔다. 예를 들어 provider guardian 트랜잭션 protocol 테스트는 tests/integration/provider-guardian-transaction.test.ts에 있다. 그 handshake 시간 제한은 테스트용 watchdog이지, production protocol의 마감 시간이 아니다.
  • script 자신의 테스트는 명령줄 계약을 확인하려고 그 script, Node, Vitest를 짧게 사는 자식 프로세스로 띄울 수 있다. 이런 테스트는 그 script의 다른 테스트 옆 tests/unit에 그대로 둔다. 이런 suite는 전역 시간 제한을 올리지 않고 자기 시간 제한을 childProcessTimeout(<desktop에서 잰 가장 긴 ms>) (tests/helpers/child-process-timeout.ts)로 선언한다. 예를 들어 tests/unit/risk-coverage.test.ts의 CLI 시험이 그렇다. 정하는 법과 검사는 docs/work/reference/testing.md 2절이다.

end-to-end 시나리오와 자동 접근성 시나리오는 버전을 고정한 Chromium, Firefox, WebKit 엔진에서 돈다. responsive 계약은 320px reflow, 모바일 navigation drawer, 넓은 화면의 2열 gallery를 명시적으로 확인한다. 테마 시나리오는 선택값 저장, 운영체제 설정 변경, 어두운 surface의 axe 결과를 검증한다. native modal focus와 검증 오류 연결은 component 테스트와 브라우저 테스트 양쪽에서 확인한다.

통제는 양성(positive) fixture가 통과하고, 일부러 실패하게 만든 음성(negative) fixture가 거부될 때만 검증된 것으로 본다. 생성된 증거는 CI가 보관한다. repository는 증거 디렉터리 구조만 추적한다.

승격은 AND 그래프다.

  1. merge gate
  2. merge gate와 release gate
  3. release gate와 rollback·runbook drill
  4. production 승격과, 조건을 만족하는 현장(field) Web Vitals 증거

더 넓은 테스트 설계는 frontend platform 테스트 전략에 있다. 이 파일은 테스트가 어디에 속하고 어떤 환경이 그 테스트를 돌려도 되는지를 정하는, 실행 가능한 분류다.