Files
clean-architecture-frontend…/docs/testing/taxonomy.md
T
DongHyeonka fd11d08a89 fix(docs): 참조 기능 전용 script를 문서 검사가 요구하지 않게 적는다
문제
test:sample-removal은 참조 기능을 지울 때 그 전용 script
test:reference-feature도 package.json에서 지운다. 샘플을 지운 프로젝트도
같다. 그런데 docs/testing/taxonomy.md와 원장 두 행이 그 script를 백틱·명령
형태로 적어, 문서 검사가 "names package scripts that do not exist:
test:reference-feature"로 실패했다(b6bfc9b snapshot의 드릴 실행).

고른 방법
- 참조 기능 경로와 같은 규칙(patterns.md 첫머리): 참조 기능이 가진 script는
  백틱이나 `corepack pnpm` 없이 적고 "참조 기능과 함께 지워진다"를 붙인다.

위험·한계
- 템플릿에서도 문서 검사가 이 script 이름의 존재를 보지 않는다.

검증
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지우고 test:reference-feature를
  package.json에서 뺀 복사본(sim-sample-docs.sh)에서 verify:documentation
  PASS_SCOPED. 저장소에서도 PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 22:08:25 +09:00

122 lines
5.5 KiB
Markdown

# Test and evidence taxonomy
Each gate is blocking in its declared scope. Failures are not downgraded with
`continue-on-error` or warning-only scripts.
## Executable levels
| Level | Command | Ownership / prerequisite | Evidence |
| --- | --- | --- | --- |
| runtime schema | `pnpm test:runtime-schema` | pure runtime schema contracts | `artifacts/tests/runtime-schema.xml` |
| unit | `pnpm test:unit` | Node-only domain/application/pure policy/runtime units; no systemd/bwrap/cgroup prerequisite | `artifacts/tests/unit.xml` |
| capability contract | `pnpm test:contract` | reusable capability consumer contracts | `artifacts/tests/contract.xml` |
| component | `pnpm test:component` | React/hook/UI behavior | `artifacts/tests/component.xml` |
| integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, composed browser-runtime boundaries, child-process/filesystem/IPC integration | `artifacts/tests/integration.xml` |
| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls | `artifacts/tests/system.xml` |
| end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` |
| accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` |
`test:all` is the normal product-development loop. It runs, in order,
`test:runtime-schema`, `test:unit`, `test:contract`, `test:component`,
`test:integration`, test:reference-feature (removed with the reference sample), `test:platform` (`tests/platform`
and `tests/architecture`), `check:release-coherence` and `test:recipes`
(`package.json` `test:all`). It does not include `test:system`. CI-runner and
supply-chain assurance has different host prerequisites and is invoked
explicitly in the assurance path.
## Deterministic test process
All Vitest package scripts launch through `scripts/run-vitest.ts`.
That runner:
1. rejects Node versions outside the repository-supported
`>=24.11.0 <25.0.0` range before the suite starts,
2. owns `NODE_ENV=test` rather than trusting the parent shell,
3. removes host-specific `npm_config_userconfig`, `npm_config_prefix` and
`npm_config_globalconfig` values before Vitest starts.
`vitest.config.ts` also fixes `NODE_ENV=test` so a direct Vitest invocation
cannot accidentally select React's production behavior.
To run one test file, use the same runner:
```sh
node scripts/run-vitest.ts run tests/component/router.test.tsx
```
The runner renders the gitignored `src/.generated/` product index first
(`scripts/run-vitest.ts`), so this works in a fresh clone. A direct
`pnpm exec vitest run <file>` skips that step and fails there with
`Failed to resolve import "../.generated/product-feature-index.ts"`.
`pnpm test:unit -- <file>` does not narrow the run, because the script already
passes the whole `tests/unit` directory.
`vitest.config.ts` collects only `tests/**/*.test.{ts,tsx}`; Playwright
`*.spec.ts` files are not Vitest tests. `tests/system/` is collected only when
the command names it, as `test:system` does, so a bare `vitest` run does not
start the CI-runner suite.
The system suite additionally runs
`scripts/check-system-test-prerequisites.ts` and fails with one prerequisite
report when the CI-runner host does not provide its required Linux facilities.
## Development paths
Product feature:
- focused feature/unit/component test
- capability contract test when a reusable boundary changes
- type/lint/architecture
- `test:all`
Reusable capability:
- focused unit tests
- capability contract tests
- integration tests
- type/lint/architecture
CI / release assurance:
- `test:system`
- supply-chain / promotion / release gates
A host-level process/sandbox test must not be placed in `tests/unit` merely
because it uses Vitest. The classification follows the system boundary and
prerequisites, not the test framework:
- Tests that need systemd, bubblewrap, cgroup v2 or CI-provider process
controls belong in `tests/system`.
- Tests of a long-lived child-process protocol belong in `tests/integration`;
for example the provider guardian transaction protocol lives at
`tests/integration/provider-guardian-transaction.test.ts`. Its handshake
timeout is a test watchdog, not a production protocol deadline.
- A script's own tests may start that script, Node or Vitest as a short-lived
child process to check its command-line contract, and stay in `tests/unit`
next to the script's other tests. Such a suite declares its own longer
timeout instead of raising the global one; for example
`tests/unit/risk-coverage.test.ts` uses `PROCESS_HEAVY_TIMEOUT_MS`.
End-to-end and automated accessibility scenarios run on the pinned Chromium,
Firefox, and WebKit engines. The responsive contract explicitly exercises
320px reflow, a mobile navigation drawer, and a wide two-column gallery.
Theme scenarios verify persistence, operating-system changes, and dark-surface
axe results. Native modal focus and validation association are exercised in
both component and browser tests.
A control is verified only when a positive fixture passes and its deliberately
failing negative fixture is rejected. Generated evidence is retained by CI;
the repository tracks only the evidence directory structure.
Promotion is an AND graph:
1. merge gates
2. merge gates plus release gates
3. release gates plus rollback/runbook drills
4. production promotion plus eligible field Web Vitals evidence
The [frontend platform testing strategy](./frontend-platform-testing-strategy.md)
contains the broader testing design. This file is the executable taxonomy for
where a test belongs and which environment is allowed to run it.