Files
clean-architecture-frontend…/tests/features/reference-feature/reference-contract.test.ts
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

211 lines
6.9 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import {
buildRouteUrl,
parseRouteInput,
} from "../../../src/presentation/routes/route-codecs.ts";
import {
mapReferenceResourcePayload,
toReferenceView,
} from "../../../src/features/reference-feature/contracts/reference-mapper.ts";
import {
CREATE_REFERENCE_RESOURCE_CONTRACT,
GET_REFERENCE_RESOURCE_CONTRACT,
LIST_REFERENCE_RESOURCES_CONTRACT,
REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION,
} from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
import {
REFERENCE_FEATURE_CONTRACT,
REFERENCE_FEATURE_ID,
REFERENCE_RESOURCE_INVALIDATION_TOPIC,
} from "../../../src/features/reference-feature/contracts/reference-feature-contract.ts";
import { REFERENCE_FEATURE_ROUTE_CODECS } from "../../../src/features/reference-feature/presentation/reference-route-codecs.ts";
import type { ReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts";
import { createTestApplication } from "../../helpers/create-test-application.ts";
import { createReferenceFeatureInstalledInput } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts";
import { oneResourceReadRoutes } from "../../../scripts/lib/a11y-data-state.ts";
describe("reference feature boundary contracts", () => {
it("propagates uncertain command effect certainty into the application failure", async () => {
const execute = vi.fn(async () => ({
kind: "CONTRACT_VIOLATION" as const,
violation: {
kind: "SUCCESS_SCHEMA_INVALID" as const,
operation: "VALIDATION" as const,
},
effect: "MAYBE_APPLIED" as const,
}));
const installed = createReferenceFeatureInstalledInput({
http: { execute },
});
await expect(
installed.input.createResource({ name: "uncertain" }),
).resolves.toMatchObject({
ok: false,
error: {
effect: "MAYBE_APPLIED",
retryable: false,
action: "contact-support",
},
});
});
it("round-trips one canonical filter through the URL codec", () => {
const filters = {
tags: ["open", "new"],
cursor: "a/b",
limit: 5,
};
const url = buildRouteUrl(
"REFERENCE_RESOURCE_LIST",
{ search: filters },
REFERENCE_FEATURE_ROUTE_CODECS,
);
expect(url).toBe(
"/examples/reference-resources?cursor=a%2Fb&limit=5&tags=open&tags=new",
);
const parsed = parseRouteInput(
"REFERENCE_RESOURCE_LIST",
{},
new URL(url, "https://app.test").searchParams,
REFERENCE_FEATURE_ROUTE_CODECS,
);
expect(parsed).toMatchObject({
success: true,
data: { search: filters },
});
});
it("rejects unknown search and malformed DTO before mapping", () => {
expect(
parseRouteInput(
"REFERENCE_RESOURCE_LIST",
{},
new URLSearchParams("unknown=value"),
REFERENCE_FEATURE_ROUTE_CODECS,
),
).toEqual({ success: false, code: "ROUTE_SEARCH_INVALID" });
expect(
LIST_REFERENCE_RESOURCES_CONTRACT.contract.outputValidator.safeParse([
{ id: "unsafe", name: 42 },
]),
).toMatchObject({ success: false });
});
it("normalizes request input and maps only owned domain fields", () => {
expect(
CREATE_REFERENCE_RESOURCE_CONTRACT.contract.inputValidator.safeParse({
name: " Example ",
}),
).toMatchObject({ success: true, data: { name: "Example" } });
const model = mapReferenceResourcePayload({
id: "reference-1",
name: "Example",
createdAt: "2026-07-26T00:00:00.000Z",
});
if (!model.ok) throw new Error("expected one model");
expect(toReferenceView(model.value)).toEqual({
resourceId: "reference-1",
title: "Example",
createdAt: "2026-07-26T00:00:00.000Z",
});
});
it("owns route and operation contributions in one removable contract", () => {
expect(Object.keys(REFERENCE_FEATURE_CONTRACT.routes)).toEqual([
"REFERENCE_RESOURCE_LIST",
"REFERENCE_RESOURCE_DETAIL",
"REFERENCE_RESOURCE_FORM",
"REFERENCE_RESOURCE_STATUS",
]);
expect(
REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http.map(
({ contract }) => contract.operationId,
),
).toEqual([
"LIST_REFERENCE_RESOURCES",
"GET_REFERENCE_RESOURCE",
"CREATE_REFERENCE_RESOURCE",
]);
expect(GET_REFERENCE_RESOURCE_CONTRACT.contract).toMatchObject({
pathTemplate: "/api/reference-resources/{resourceId}",
});
expect(GET_REFERENCE_RESOURCE_CONTRACT.contract.inputValidator.schemaId).toBe(
"ReferenceResourceParams",
);
expect(GET_REFERENCE_RESOURCE_CONTRACT.frontend.authProfileId).toBe(
"EXTERNAL_BEARER",
);
});
// 1106/11-01. scripts/write-a11y-report.ts fails when a11y.json would count
// these routes as passed: the accessibility spec has no generic answer for a
// read of one resource and scans the page on its failure state only.
it("has one detail page the a11y report expects under notChecked", () => {
expect(
oneResourceReadRoutes(
Object.values(REFERENCE_FEATURE_CONTRACT.routes),
REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http,
),
).toEqual([
{
routeId: "REFERENCE_RESOURCE_DETAIL",
operationIds: ["GET_REFERENCE_RESOURCE"],
},
]);
});
it("contributes an identity-based invalidation graph and an explicit wire version", () => {
expect(REFERENCE_FEATURE_CONTRACT.invalidation).toEqual({
topics: [REFERENCE_RESOURCE_INVALIDATION_TOPIC],
namespaces: [
{ namespaceId: "reference-resource", namespaceVersion: 1 },
],
edges: [
{
topicId: REFERENCE_RESOURCE_INVALIDATION_TOPIC,
namespace: {
namespaceId: "reference-resource",
namespaceVersion: 1,
},
},
],
});
expect(REFERENCE_FEATURE_CONTRACT.topicVersions).toEqual([
{
topicId: REFERENCE_RESOURCE_INVALIDATION_TOPIC,
topicVersion: 1,
},
]);
});
it("returns the installed input through the typed application registry", () => {
const featureInput = {
listResources: async () => ({ ok: true as const, value: [] }),
createResource: async ({ name }) => ({
ok: true as const,
value: {
resourceId: "created",
title: name,
createdAt: null,
},
}),
getResource: async (resourceId) => ({
ok: true as const,
value: {
resourceId,
title: "Reference",
createdAt: null,
},
}),
} satisfies ReferenceFeatureInput;
const application = createTestApplication({
featureInputs: { [REFERENCE_FEATURE_ID]: featureInput },
});
expect(application.features.has(REFERENCE_FEATURE_ID)).toBe(true);
expect(application.features.get(REFERENCE_FEATURE_ID)).toBe(featureInput);
});
});