문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다. 기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec 말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을 null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두 통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를 적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난 실행의 기록 파일도 디렉터리에 남아 있었다. 고른 방법: 리뷰의 (다)와 기록 초기화. - scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된 descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이 필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마일 때다. GET 쪽 규칙은 tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다. 참조 기능 상세와 create:feature --with-create 상세는 GET과 같은 <Pascal>Params를 쓰므로 이 규칙에 든다. - write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면 `a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다. a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다. - accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다. 기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다. 엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에 기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다. - 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개 라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은 허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL 하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도 모른다. 참조 기능과 함께 지워진다. - 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset). 버린 대안: - (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만 reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도 정해야 한다. - 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능 런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가 많다. - spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할 뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다. - 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정: 11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다. 위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고, 규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라 받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는 규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이 API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임 전체를 불러온다(check:registries와 같은 경로). check:types:node가 그 그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts tests/features/reference-feature/reference-contract.test.ts 11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤 node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm test:a11y Refs: 1106/11-01
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# Manual accessibility review checklist
|
|
|
|
Automated axe checks do not establish WCAG conformance. A human reviewer must
|
|
review every route record in `artifacts/tests/a11y-manual/` against one
|
|
release candidate and sign them. The required scope is the route registry
|
|
(`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one
|
|
record per route, named `<ROUTE_ID>.md`. Copy the template fields exactly; the
|
|
gate rejects blank identity/timestamp/signature fields, pending verdicts,
|
|
mismatched release IDs, or missing routes.
|
|
|
|
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
|
|
it is required once per release candidate, not on every merge. The merge gate
|
|
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
|
|
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
|
|
and a record marked `reviewed` must be complete.
|
|
|
|
This document keeps no route list. A list here once said six routes while ten
|
|
were registered, and keeping it current made every new feature edit this file.
|
|
Instead `verify:documentation` fails, naming the route ID, when a registered
|
|
route has no record file. A new route starts from a copy of a pending record
|
|
with its title and `Route ID` changed.
|
|
|
|
Allowed item verdicts:
|
|
|
|
- `pass`
|
|
- `not-applicable (<specific reason>)`
|
|
|
|
Required record:
|
|
|
|
```text
|
|
Status: reviewed
|
|
Route ID: APP_HOME
|
|
Release ID: <immutable release ID>
|
|
Reviewer: <human reviewer identity>
|
|
Reviewed at: <RFC 3339 timestamp>
|
|
Signature: <reviewer identity or approved signature reference>
|
|
Attestation: accepted
|
|
M1 Keyboard: pass
|
|
M2 Visible focus: pass
|
|
M3 Route focus: pass
|
|
M4 Modal focus: not-applicable (no modal on this route)
|
|
M5 Error association: not-applicable (no form error on this route)
|
|
M6 Color signal: pass
|
|
M7 Reduced motion: pass
|
|
Screen reader: pass
|
|
Notes: <observations and linked defect IDs>
|
|
```
|
|
|
|
The reviewer must verify:
|
|
|
|
- M1: every action works without a pointing device
|
|
- M2: every focused element has a visible indicator
|
|
- M3: route transitions move focus to a deterministic target
|
|
- M4: modal focus is trapped and restored, when a modal exists
|
|
- M5: errors are programmatically associated with their controls, when present
|
|
- M6: state never relies on color alone
|
|
- M7: non-essential motion is suppressed with reduced-motion preference
|
|
- Screen reader: headings, live regions, errors, and actions are announced once
|
|
|
|
`EXAMPLES_UI` requires real M4 modal and M5 field-error review; those items must
|
|
not be marked not-applicable on that route. Passing automated evidence means
|
|
only that tested pages had no critical or serious axe findings under the
|
|
recorded Chromium, Firefox, and WebKit runs.
|
|
|
|
What the automated run scans:
|
|
|
|
- Every registered route, after the route's own `h1` is on screen, so the scan
|
|
never lands on the app shell's loading surface
|
|
(`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
|
|
catalog title.
|
|
- Protected routes after the demo sign-in, never the sign-in prompt. A list
|
|
read answers an empty list in the frame its descriptor declares (inside the
|
|
Envelope for `responseEnvelope: "ENVELOPE_V1"`), and the scan runs only once
|
|
no alert box is on screen, so a list page is scanned in its empty state. A
|
|
read of one resource (a detail page) has no generic answer: that route is
|
|
scanned in its failure state and the run records an `a11y-data-state`
|
|
annotation. `a11y.json` lists it under `notChecked`. When a protected
|
|
route's `paramsSchema` is the input of such a read, the report expects that
|
|
record from the descriptors alone and fails without it
|
|
(`scripts/write-a11y-report.ts`).
|
|
- The reference sample's list in its success, empty and error states, its
|
|
detail, its form with submit errors and its status page, each after that
|
|
state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the
|
|
sample).
|