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이 비었다.
This commit is contained in:
DongHyeonka
2026-11-08 21:57:47 +09:00
parent 45e8cb774c
commit 11530b1adf
15 changed files with 687 additions and 761 deletions
+93 -95
View File
@@ -1,130 +1,128 @@
# Test and evidence taxonomy
# 테스트와 증거 분류
Each gate is blocking in its declared scope. Failures are not downgraded with
`continue-on-error` or warning-only scripts.
각 gate는 선언된 범위 안에서 차단한다. 실패를 `continue-on-error`나 경고만 내는
script로 낮추지 않는다.
## 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` |
| 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` is the normal product-development loop. It runs, in order,
`test:all`은 평소 제품 개발 루프다. 다음을 순서대로 돌린다:
`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.
`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 전제 조건이
달라서, 보증 경로에서 따로 명시적으로 부른다.
## Deterministic test process
## 결정적인 테스트 프로세스
All Vitest package scripts launch through `scripts/run-vitest.ts`.
Vitest package script는 모두 `scripts/run-vitest.ts`를 거쳐 실행한다.
That runner:
이 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.
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` also fixes `NODE_ENV=test` so a direct Vitest invocation
cannot accidentally select React's production behavior.
`vitest.config.ts`도 `NODE_ENV=test`를 고정한다. 그래서 Vitest를 직접 불러도
React의 production 동작이 실수로 선택되지 않는다.
To run one test file, use the same runner:
테스트 파일 하나만 돌릴 때도 같은 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.
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` 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.
`vitest.config.ts`는 `tests/**/*.test.{ts,tsx}`만 모은다. Playwright의
`*.spec.ts` 파일은 Vitest 테스트가 아니다. `tests/system/`은 명령이 그 경로를
직접 지정할 때만 모은다(`test:system`이 그렇게 한다). 그래서 맨 `vitest` 실행은
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`).
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`).
## Development paths
## 개발 경로
Product feature:
제품 feature:
- focused feature/unit/component test
- capability contract test when a reusable boundary changes
- type/lint/architecture
- 대상을 좁힌 feature·unit·component 테스트
- 재사용 경계가 바뀌면 capability contract 테스트
- type·lint·architecture
- `test:all`
Reusable capability:
재사용 capability:
- focused unit tests
- capability contract tests
- integration tests
- type/lint/architecture
- 대상을 좁힌 unit 테스트
- capability contract 테스트
- integration 테스트
- type·lint·architecture
CI / release assurance:
CI·release 보증:
- `test:system`
- supply-chain / promotion / release gates
- 공급망·승격(promotion)·release gate
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:
host 수준 프로세스·sandbox 테스트를 Vitest를 쓴다는 이유만으로 `tests/unit`에
두면 안 된다. 분류는 테스트 framework가 아니라 system 경계와 전제 조건을 따른다.
- 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`.
- 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 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.
end-to-end 시나리오와 자동 접근성 시나리오는 버전을 고정한 Chromium, Firefox,
WebKit 엔진에서 돈다. responsive 계약은 320px reflow, 모바일 navigation drawer,
넓은 화면의 2열 gallery를 명시적으로 확인한다. 테마 시나리오는 선택값 저장,
운영체제 설정 변경, 어두운 surface의 axe 결과를 검증한다. native modal focus와
검증 오류 연결은 component 테스트와 브라우저 테스트 양쪽에서 확인한다.
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.
통제는 양성(positive) fixture가 통과하고, 일부러 실패하게 만든 음성(negative)
fixture가 거부될 때만 검증된 것으로 본다. 생성된 증거는 CI가 보관한다.
repository는 증거 디렉터리 구조만 추적한다.
Promotion is an AND graph:
승격은 AND 그래프다.
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
1. merge gate
2. merge gate와 release gate
3. release gate와 rollback·runbook drill
4. production 승격과, 조건을 만족하는 현장(field) Web Vitals 증거
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.
더 넓은 테스트 설계는
[frontend platform 테스트 전략](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다.
이 파일은 테스트가 어디에 속하고 어떤 환경이 그 테스트를 돌려도 되는지를 정하는,
실행 가능한 분류다.