Files
clean-architecture-frontend…/docs/testing/taxonomy.md
T
DongHyeonka f6e2560e4d
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 22m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m54s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
docs: FE-GATE-013이 시스템 컨테이너에서 도는 것을 지침과 운영 문서에 적는다
문제: 작업 매뉴얼·루트 지침·스킬이 「desktop의 FE-GATE-013은 호스트 제약
실패로 적고 merge 가능 여부는 소유자가 정한다(결정 대기 D8)」라고 적고
있다. 1d3eb901 뒤로 workflow와 scripts/verify.sh는 이 게이트를
scripts/run-in-system-container.sh 안에서 돌리고, 다른 게이트처럼 rc로
센다. CHANGELOG에는 이 브랜치의 변경이 없다.

고른 방법:
- gates.md 3절 문단을 「시스템 컨테이너 안에서 돈다」로 바꾸고, AGENTS.md
  ·improve.md·new-feature.md·operate.md·desktop-gates 스킬의 기록법
  문구를 그 절을 가리키게 고친다.
- decisions.md: 소유자 결정(2026-11-11, design-docs template-program
  README 5절 e)을 2.1절 행으로 더하고 열린 결정 대기 D8을 닫는다.
  evidence.md의 근거 행을 새 규칙 이름과 runner 사건으로 고친다.
- docs/operations/ci-quality-gates.md, docs/testing/taxonomy.md,
  README.md에 컨테이너 경로와 그 한계(root라 비특권 userns 조건은 증명하지
  않음, privileged를 막는 runner에서는 깨짐)를 적는다.
- CHANGELOG 미출시 절에 이 브랜치의 변경을 적는다.

위험·한계: desktop·runner에서 FE-GATE-013이 실제로 초록인지는 이 브랜치
끝의 merge 단계 실행으로 확인한다.

검증: 노트북 scripts/verify.sh docs rc=0. desktop verify:documentation
PASS_SCOPED, 문서를 읽는 시험 넷(changelog-review-ids,
documentation-readiness, template-contract-documents,
deletable-history-documents) 29개 통과.
2026-11-12 19:52:09 +09:00

129 lines
7.2 KiB
Markdown

# 테스트와 증거 분류
각 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를 쓴다.
```sh
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 테스트 전략](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다.
이 파일은 테스트가 어디에 속하고 어떤 환경이 그 테스트를 돌려도 되는지를 정하는,
실행 가능한 분류다.