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

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