Files
clean-architecture-frontend…/tests/unit/a11y-report.test.ts
T
DongHyeonka 9c4cddc201 fix(a11y): 한 자원을 읽는 라우트가 기록 없이 통과로 세지면 report가 실패한다
문제: 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
2026-11-06 05:29:21 +09:00

198 lines
6.6 KiB
TypeScript

import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { automatedA11yArtifactSchema } from "../../scripts/contracts/release-artifacts.ts";
import {
automatedA11yReport,
oneResourceReadRoutes,
oneResourceRoutesCountedAsChecked,
readA11yNotCheckedRoutes,
recordA11yDataState,
} from "../../scripts/lib/a11y-data-state.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "../../scripts/lib/manual-a11y-evidence.ts";
/**
* 1103/11-01. The accessibility spec scans a detail page on its failure state
* (no generic answer exists for a read of one resource). `a11y.json` must not
* count that route as passed: it goes to `notChecked` with its reason.
*/
const ROUTES: readonly string[] = MANUAL_A11Y_ROUTE_IDS;
const [CHECKED_ROUTE = "", FAILURE_STATE_ROUTE = ""] = ROUTES;
const REASON = "scanned on its failure state only: TEST_GET_ENTITY reads one resource";
const GENERATED_AT = "2026-11-05T00:00:00.000Z";
const directories: string[] = [];
async function recordDirectory(): Promise<string> {
const directory = await mkdtemp(path.join(tmpdir(), "a11y-data-state-"));
directories.push(directory);
return directory;
}
afterEach(async () => {
await Promise.all(
directories.splice(0).map((directory) =>
rm(directory, { recursive: true, force: true }),
),
);
});
describe("automated accessibility report", () => {
it("needs two installed routes to tell a checked route from a failure-state one", () => {
expect(ROUTES.length).toBeGreaterThanOrEqual(2);
});
it("reports a route scanned only on its failure state as not checked", async () => {
const directory = await recordDirectory();
await recordA11yDataState(CHECKED_ROUTE, null, directory);
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
const report = automatedA11yReport({
routeIds: ROUTES,
notChecked: await readA11yNotCheckedRoutes(ROUTES, directory),
generatedAt: GENERATED_AT,
});
expect(report.scope).toContain(CHECKED_ROUTE);
expect(report.scope).not.toContain(FAILURE_STATE_ROUTE);
expect(report.notChecked).toEqual([
{ routeId: FAILURE_STATE_ROUTE, reason: REASON },
]);
expect(automatedA11yArtifactSchema.safeParse(report).success).toBe(true);
});
it("lets a route's latest run decide", async () => {
const directory = await recordDirectory();
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
await recordA11yDataState(FAILURE_STATE_ROUTE, null, directory);
await expect(readA11yNotCheckedRoutes(ROUTES, directory)).resolves.toEqual([]);
});
it("refuses a report that counts a failure-state route as passed", () => {
const report = automatedA11yReport({
routeIds: ROUTES,
notChecked: [{ routeId: FAILURE_STATE_ROUTE, reason: REASON }],
generatedAt: GENERATED_AT,
});
expect(
automatedA11yArtifactSchema.safeParse({ ...report, scope: [...ROUTES] })
.success,
).toBe(false);
});
it("refuses a report that drops an installed route from both lists", () => {
const report = automatedA11yReport({
routeIds: ROUTES,
notChecked: [],
generatedAt: GENERATED_AT,
});
expect(automatedA11yArtifactSchema.safeParse(report).success).toBe(true);
expect(
automatedA11yArtifactSchema.safeParse({
...report,
scope: ROUTES.filter((routeId) => routeId !== FAILURE_STATE_ROUTE),
}).success,
).toBe(false);
});
});
/**
* 1106/11-01. Which routes need a failure-state record comes from the
* descriptors, not from the spec that writes the records. Review 11-R2 passed
* `null` for the detail page's record and every check passed.
*/
describe("routes the accessibility spec can scan only on their failure state", () => {
const read = (
operationId: string,
method: string,
pathTemplate: string,
inputSchemaId: string,
acceptsEmptyList: boolean,
) => ({
contract: {
operationId,
method,
pathTemplate,
inputValidator: { schemaId: inputSchemaId },
outputValidator: {
safeParse: (value: unknown) => ({
success: acceptsEmptyList && Array.isArray(value),
}),
},
},
});
const route = (
routeId: string,
access: string,
paramsSchema: string | null,
) => ({ routeId, access, paramsSchema });
it("finds a protected route whose params are the input of a read of one resource", () => {
expect(
oneResourceReadRoutes(
[
route("THING_LIST", "session-required", null),
route("THING_DETAIL", "session-required", "ThingParams"),
route("THING_PARTS", "session-required", "ThingPartsParams"),
route("THING_EDIT", "session-required", "ThingEditParams"),
route("PUBLIC_THING", "public", "ThingParams"),
],
[
read("LIST_THINGS", "GET", "/api/things", "ThingListQuery", true),
read("GET_THING", "GET", "/api/things/{thingId}", "ThingParams", false),
// A list under a path parameter gets the empty list.
read("LIST_THING_PARTS", "GET", "/api/things/{thingId}/parts", "ThingPartsParams", true),
// Not a read.
read("DELETE_THING", "DELETE", "/api/things/{thingId}", "ThingEditParams", false),
],
),
).toEqual([{ routeId: "THING_DETAIL", operationIds: ["GET_THING"] }]);
});
it("refuses records that count such a route as checked", async () => {
const directory = await recordDirectory();
const expected = [
{ routeId: FAILURE_STATE_ROUTE, operationIds: ["TEST_GET_ENTITY"] },
];
// 11-R2: the spec recorded the route as scanned in its own state.
await recordA11yDataState(FAILURE_STATE_ROUTE, null, directory);
expect(
oneResourceRoutesCountedAsChecked(
expected,
await readA11yNotCheckedRoutes(ROUTES, directory),
),
).toEqual([
expect.stringContaining(
`${FAILURE_STATE_ROUTE} reads one resource (TEST_GET_ENTITY) but has no failure-state record`,
),
]);
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
expect(
oneResourceRoutesCountedAsChecked(
expected,
await readA11yNotCheckedRoutes(ROUTES, directory),
),
).toEqual([]);
});
it("does not refuse a record for a route the descriptors do not name", async () => {
const directory = await recordDirectory();
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
expect(
oneResourceRoutesCountedAsChecked(
[],
await readA11yNotCheckedRoutes(ROUTES, directory),
),
).toEqual([]);
});
});