문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 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건.
131 lines
6.2 KiB
Markdown
131 lines
6.2 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, 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:
|
|
|
|
```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.
|
|
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](../design/2026-07-26-frontend-platform-testing-strategy-design.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.
|