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 { 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([]); }); });