Files
clean-architecture-frontend…/docs/testing/taxonomy.md
T
DongHyeonka e632b230e3 docs: 옮긴 문서를 가리키는 링크와 경로를 새 위치로 고친다
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을
가리킨다.

고른 방법: 기계적으로 바꾼다.
- 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고,
  대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다.
  옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은
  링크 대상뿐이다(백엔드 1단계와 같은 예외).
- 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`,
  `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과
  CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와
  review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토
  작업 공간의 출처 표시라 그대로 둔다.

위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는
없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다.

검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록,
CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시
쓴다) 밖에서 0건.
2026-11-08 17:25:41 +09:00

6.2 KiB

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, where bubblewrap may create unprivileged user and network namespaces 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, the rest of what test:coverage runs (tests/features, each installed feature's tests, tests/scripts and tests/scale/browser-soak.contract.test.ts), test:platform (tests/platform and tests/architecture), check:release-coherence and test:recipes (package.json test:all). So every Vitest path the merge gate's coverage run covers also runs here (tests/unit/test-all-paths.test.ts, 0929/10-05). 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:

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. Besides the executables, cgroup v2 and the systemd bus, it runs bubblewrap once with the provider sandbox's namespace options on /bin/true, so a host that refuses unprivileged user namespaces (Ubuntu 23.10 and later with kernel.apparmor_restrict_unprivileged_userns=1) fails there by name instead of in the provider tests (1105/12-01, docs/operations/ci-quality-gates.md).

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 contains the broader testing design. This file is the executable taxonomy for where a test belongs and which environment is allowed to run it.