Files
clean-architecture-frontend…/tests/unit/a11y-api-answers.test.ts
T
DongHyeonka 7f633106bb test(a11y): 접근성 e2e가 기능 API를 descriptor 모양의 빈 목록으로 답한다
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.

고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
  descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
  목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
  같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
  단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
  spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
  501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
  문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
  접근성 spec 생성(파일·실행 시간 증가).

위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
  그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
  annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
  "passed"로 적힌다.

검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
  변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
  변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
  axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
2026-11-04 22:59:03 +09:00

104 lines
4.0 KiB
TypeScript

import { describe, expect, it } from "vitest";
import { readSuccessEnvelope } from "../../src/adapters/http/backend-envelope.ts";
import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts";
import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../../src/features/loaded-feature-runtimes.ts";
import { answerInstalledApiRequest } from "../e2e/support/installed-api-answers.ts";
import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts";
/**
* 1103/11-01, 16-03. The accessibility e2e answers a protected page's API
* requests from the installed descriptors: an empty list in the frame the
* operation declares. A global bare `[]` put every Envelope feature on the
* mismatch error screen and still passed.
*/
const [LIST, GET, CREATE] = TEST_CONTRACT_CONTRIBUTION.http;
function composed(responseEnvelope?: "ENVELOPE_V1") {
return composeContractContributions([
Object.freeze({
...TEST_CONTRACT_CONTRIBUTION,
http: Object.freeze(
[LIST!, GET!, CREATE!].map((installed) =>
responseEnvelope === undefined
? installed
: Object.freeze({
...installed,
contract: Object.freeze({ ...installed.contract, responseEnvelope }),
}),
),
),
}),
]);
}
describe("accessibility e2e API answers", () => {
it("answers a DTO list read with a bare empty list", () => {
expect(answerInstalledApiRequest(composed(), "GET", "/api/test-entities")).toEqual({
kind: "empty-list",
operationId: "TEST_LIST_ENTITIES",
body: [],
});
});
it("answers an Envelope list read with an empty list inside the Envelope", () => {
const answer = answerInstalledApiRequest(
composed("ENVELOPE_V1"),
"GET",
"/api/test-entities",
);
expect(answer.kind).toBe("empty-list");
if (answer.kind !== "empty-list") return;
// What the executor reads out of the frame is what the operation accepts.
expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] });
expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true);
});
it("names a single-resource read, which no empty list can answer", () => {
expect(
answerInstalledApiRequest(composed("ENVELOPE_V1"), "GET", "/api/test-entities/a11y-1"),
).toMatchObject({ kind: "single-resource", operationId: "TEST_GET_ENTITY" });
});
it("refuses a request no installed read declares", () => {
expect(
answerInstalledApiRequest(composed(), "POST", "/api/test-entities"),
).toEqual({ kind: "unanswerable", request: "POST /api/test-entities" });
expect(
answerInstalledApiRequest(composed(), "GET", "/api/elsewhere"),
).toEqual({ kind: "unanswerable", request: "GET /api/elsewhere" });
});
it("refuses a parameterless read whose payload is not a list", () => {
const pagedOnly = composeContractContributions([
Object.freeze({
...TEST_CONTRACT_CONTRIBUTION,
http: Object.freeze([
Object.freeze({
...GET!,
contract: Object.freeze({
...GET!.contract,
operationId: "TEST_PAGED_ENTITIES",
pathTemplate: "/api/paged-entities",
}),
}),
]),
}),
]);
expect(answerInstalledApiRequest(pagedOnly, "GET", "/api/paged-entities")).toEqual({
kind: "unanswerable",
request: "GET /api/paged-entities",
reason: "TEST_PAGED_ENTITIES reads no single resource and rejects an empty list",
});
});
it("can answer every parameterless read the installed features declare", () => {
for (const { contract } of COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.values()) {
if (contract.method !== "GET" || contract.pathTemplate.includes("{")) continue;
expect(
answerInstalledApiRequest(COMPOSED_CONTRACT_CONTRIBUTIONS, "GET", contract.pathTemplate),
).toMatchObject({ kind: "empty-list", operationId: contract.operationId });
}
});
});