Files
clean-architecture-frontend…/docs/testing/taxonomy.md
T
DongHyeonka 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
2026-11-08 21:57:47 +09:00

7.0 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를 만들 수 있어야 한다 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를 시작하지 않는다.

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는 전역 시간 제한을 올리지 않고 자기 시간 제한을 더 길게 선언한다. 예를 들어 tests/unit/risk-coverage.test.ts는 PROCESS_HEAVY_TIMEOUT_MS를 쓴다.

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 테스트 전략에 있다. 이 파일은 테스트가 어디에 속하고 어떤 환경이 그 테스트를 돌려도 되는지를 정하는, 실행 가능한 분류다.