Files
clean-architecture-frontend…/tests/e2e/support/installed-api-answers.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

64 lines
2.6 KiB
TypeScript

import type { ComposedContractContributions } from "../../../src/contracts/external-contract-runtime.ts";
import { successEnvelope } from "../../mocks/handlers/http-scenarios.ts";
/**
* 1103/11-01, 16-03. What `tests/e2e/accessibility.spec.ts` answers a
* protected page's API request with. Feature data is not that spec's subject,
* so a list read gets an empty list, framed the way the operation's own
* descriptor declares: inside the paired backend's Envelope for
* `responseEnvelope: "ENVELOPE_V1"`, bare otherwise. A global bare `[]` put
* every Envelope feature on the mismatch error screen and still passed.
*
* The request is matched to an installed GET by method and `pathTemplate`, so
* a new feature needs no edit here. A read with a path parameter whose payload
* is not a list (a detail page) cannot be answered with an empty list: the
* spec renders it in its failure state and says so. Any other request fails
* the spec instead of drawing an error screen that passes.
*/
export type InstalledApiAnswer =
| Readonly<{ kind: "empty-list"; operationId: string; body: unknown }>
| Readonly<{ kind: "single-resource"; operationId: string; body: unknown }>
| Readonly<{ kind: "unanswerable"; request: string; reason?: string }>;
const EMPTY_LIST: readonly never[] = Object.freeze([]);
function templatePattern(pathTemplate: string): RegExp {
const pattern = pathTemplate
.split(/\{[^}]+\}/u)
.map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
.join("[^/]+");
return new RegExp(`^${pattern}$`, "u");
}
export function answerInstalledApiRequest(
contracts: ComposedContractContributions,
method: string,
pathname: string,
): InstalledApiAnswer {
const request = `${method} ${pathname}`;
for (const { contract } of contracts.httpByOperationId.values()) {
if (contract.method !== method || contract.method !== "GET") continue;
if (!templatePattern(contract.pathTemplate).test(pathname)) continue;
const body =
contract.responseEnvelope === "ENVELOPE_V1"
? successEnvelope([])
: EMPTY_LIST;
if (contract.outputValidator.safeParse(EMPTY_LIST).success) {
return Object.freeze({ kind: "empty-list", operationId: contract.operationId, body });
}
if (contract.pathTemplate.includes("{")) {
return Object.freeze({
kind: "single-resource",
operationId: contract.operationId,
body,
});
}
return Object.freeze({
kind: "unanswerable",
request,
reason: `${contract.operationId} reads no single resource and rejects an empty list`,
});
}
return Object.freeze({ kind: "unanswerable", request });
}