Files
clean-architecture-frontend…/tests/mocks/scenarios/catalog.ts
T
DongHyeonka 5d064b8ace test(features): 기능을 더해도 기능 밖 테스트와 시나리오 하네스가 깨지지 않게 한다 (16-02)
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).

방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
  context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
  만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.

위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
  실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
  제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
  http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
  스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
  테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
  a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
  breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
  않았다.

검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
2026-11-03 01:49:11 +09:00

511 lines
16 KiB
TypeScript

import type { JsonBodyType } from "msw";
import type {
AttemptStatus,
BodyDisposition,
HttpScenarioAssertionGroups,
RetryReason,
} from "../../../scripts/lib/http-scenario-evidence.ts";
export type {
AttemptStatus,
BodyDisposition,
HttpScenarioAssertionGroups,
RetryReason,
} from "../../../scripts/lib/http-scenario-evidence.ts";
import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts";
import {
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
TEST_DETAIL_HTTP_CONTRACT,
TEST_LIST_HTTP_CONTRACT,
} from "../../helpers/external-contract-fixture.ts";
export const HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION = 1 as const;
export const HTTP_SCENARIO_IDS = Object.freeze([
"success",
"empty",
"slow",
"network-error",
"timeout",
"aborted",
"content-type-mismatch",
"malformed-json",
"envelope-mismatch",
"schema-mismatch",
"response-too-large",
"unauthenticated-401",
"forbidden-403",
"not-found-404",
"conflict-409",
"in-flight-409",
"validation-422",
"rate-limited-429",
"server-retry-success",
"server-terminal-503",
] as const);
export type HttpScenarioId = (typeof HTTP_SCENARIO_IDS)[number];
/**
* 0929/10-02. The catalog runs on the test contracts, not the removable sample
* feature, so removing the sample keeps the HTTP scenario evidence
* (FE-GATE-007). The facts an expectation depends on (command or query, body
* ceiling, success status) are read from the contract itself.
*/
export const HTTP_SCENARIO_CONTRACTS = Object.freeze({
TEST_LIST_ENTITIES: TEST_LIST_HTTP_CONTRACT,
TEST_GET_ENTITY: TEST_DETAIL_HTTP_CONTRACT,
TEST_CREATE_ENTITY: TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
});
/**
* 16-02. Any installed operation, not only the catalog's: a feature test
* answers its own operation with `createHttpScenarioHandler`
* (`tests/mocks/handlers/http-scenarios.ts`) without editing this file.
*/
export type HttpScenarioOperationId = string;
/**
* The part of an installed (V3) descriptor a scenario reads. Every
* `InstalledHttpContract` fits it, whatever its input and output types.
*/
export type HttpScenarioContract = Readonly<{
contract: Readonly<
Pick<
InstalledHttpContract<unknown, unknown, unknown>["contract"],
"operationId" | "method" | "pathTemplate" | "acceptedStatuses"
> & { commandEffect: unknown }
>;
frontend: Readonly<{ responseByteLimit: number }>;
}>;
/** The operations this catalog's evidence (FE-GATE-007) is recorded for. */
type CatalogOperationId = keyof typeof HTTP_SCENARIO_CONTRACTS;
export const HTTP_SCENARIO_OPERATION_IDS = Object.freeze(
Object.keys(HTTP_SCENARIO_CONTRACTS) as CatalogOperationId[],
);
for (const operationId of HTTP_SCENARIO_OPERATION_IDS) {
const declared = HTTP_SCENARIO_CONTRACTS[operationId].contract.operationId;
if (declared !== operationId) {
throw new Error(`Scenario operation ${operationId} names contract ${declared}`);
}
}
export type HttpScenarioExecutionId =
`${CatalogOperationId}::${HttpScenarioId}`;
export type HttpScenarioExpectation = Readonly<{
executionId: HttpScenarioExecutionId;
operationId: CatalogOperationId;
scenarioId: HttpScenarioId;
expected: HttpScenarioAssertionGroups;
testDeadlineOverrideMs: number | null;
}>;
const encoder = new TextEncoder();
const jsonBytes = (value: unknown) => encoder.encode(JSON.stringify(value)).byteLength;
export const HTTP_SCENARIO_ENTITY = Object.freeze({
id: "entity-1",
name: "Entity",
});
export const HTTP_SCENARIO_CREATED_ENTITY = Object.freeze({
id: "entity-created",
name: "Created",
});
/** The success body each catalog operation answers with. */
export const HTTP_SCENARIO_PAYLOADS: Readonly<
Record<CatalogOperationId, JsonBodyType>
> = Object.freeze({
TEST_LIST_ENTITIES: Object.freeze([HTTP_SCENARIO_ENTITY]),
TEST_GET_ENTITY: HTTP_SCENARIO_ENTITY,
TEST_CREATE_ENTITY: HTTP_SCENARIO_CREATED_ENTITY,
});
/** What a scenario's answer depends on, read from the installed descriptor. */
export function httpScenarioOperationFacts(installed: HttpScenarioContract) {
return Object.freeze({
command: installed.contract.commandEffect !== null,
ceiling: installed.frontend.responseByteLimit,
successStatus: installed.contract.acceptedStatuses[0]!,
});
}
function problem(status: number, code: string) {
return {
type: `https://api.test/problems/${code.toLowerCase()}`,
title: code,
status,
code,
};
}
function attemptBody(
disposition: BodyDisposition,
pulledBytes: number,
ceiling: number,
) {
return Object.freeze({ disposition, pulledBytes, ceiling });
}
function expectationFor(
operationId: CatalogOperationId,
scenarioId: HttpScenarioId,
): HttpScenarioExpectation {
const { command, ceiling, successStatus } = httpScenarioOperationFacts(
HTTP_SCENARIO_CONTRACTS[operationId],
);
const payload = HTTP_SCENARIO_PAYLOADS[operationId];
let statuses: AttemptStatus[] = [successStatus];
let kind = "SUCCESS";
let detail: string | null = null;
let outcomeEffect = command ? "APPLIED_CONFIRMED" : "NOT_APPLICABLE";
let observer = outcomeEffect;
let retryReasons: RetryReason[] = [];
let media: (string | null)[] = ["application/json"];
let bodies = [attemptBody("FULLY_READ_WITHIN_BOUND", jsonBytes(payload), ceiling)];
let scopeEnd: "CURRENT" | "STALE" = "CURRENT";
let scopeSignal: "ACTIVE" | "ABORTED" = "ACTIVE";
let cancellationOwner: "NONE" | "CALLER" | "SCOPE_FENCE" | "DEADLINE" =
"NONE";
let testDeadlineOverrideMs: number | null = null;
switch (scenarioId) {
case "success":
case "slow":
break;
case "empty":
bodies = [attemptBody("FULLY_READ_WITHIN_BOUND", jsonBytes([]), ceiling)];
break;
case "network-error": {
const attemptCount = command ? 1 : 3;
statuses = Array.from({ length: attemptCount }, () => "NETWORK_REJECTION");
kind = "TRANSPORT_FAILURE";
detail = "NETWORK_FAILURE";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_STARTED";
observer = "NETWORK_FAILURE";
retryReasons = command ? [] : ["NETWORK_FAILURE", "NETWORK_FAILURE"];
media = Array.from({ length: attemptCount }, () => null);
bodies = Array.from({ length: attemptCount }, () =>
attemptBody("NO_RESPONSE", 0, 0),
);
break;
}
case "timeout":
statuses = ["PENDING_ABORT"];
kind = "TRANSPORT_FAILURE";
detail = "TIMEOUT";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_STARTED";
observer = "TIMEOUT";
media = [null];
bodies = [attemptBody("NO_RESPONSE", 0, 0)];
cancellationOwner = "DEADLINE";
testDeadlineOverrideMs = 500;
break;
case "aborted":
statuses = ["PENDING_ABORT"];
media = [null];
bodies = [attemptBody("NO_RESPONSE", 0, 0)];
if (operationId === "TEST_LIST_ENTITIES") {
kind = "CANCELLED";
outcomeEffect = "NOT_STARTED";
observer = "CANCELLED";
cancellationOwner = "CALLER";
} else {
scopeSignal = "ABORTED";
kind = "TRANSPORT_FAILURE";
detail = "ABORTED_BY_SCOPE";
outcomeEffect = "NOT_STARTED";
observer = "SCOPE_FENCED";
scopeEnd = "STALE";
cancellationOwner = "SCOPE_FENCE";
}
break;
case "content-type-mismatch":
kind = "CONTRACT_VIOLATION";
detail = "CONTENT_TYPE_MISMATCH";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE";
observer = "CONTRACT_VIOLATION";
media = ["text/html"];
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
encoder.encode("<html>not json</html>").byteLength,
ceiling,
),
];
break;
case "malformed-json":
kind = "CONTRACT_VIOLATION";
detail = "JSON_INVALID";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE";
observer = "CONTRACT_VIOLATION";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
encoder.encode("{invalid").byteLength,
ceiling,
),
];
break;
case "envelope-mismatch":
kind = "CONTRACT_VIOLATION";
detail = "SUCCESS_SCHEMA_INVALID";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE";
observer = "CONTRACT_VIOLATION";
bodies = [
attemptBody("FULLY_READ_WITHIN_BOUND", jsonBytes({ data: payload }), ceiling),
];
break;
case "schema-mismatch":
kind = "CONTRACT_VIOLATION";
detail = "SUCCESS_SCHEMA_INVALID";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE";
observer = "CONTRACT_VIOLATION";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes({ unexpected: true }),
ceiling,
),
];
break;
case "response-too-large":
kind = "CONTRACT_VIOLATION";
detail = "RESPONSE_TOO_LARGE";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE";
observer = "RESPONSE_TOO_LARGE";
bodies = [attemptBody("REJECTED_LIMIT", 0, ceiling)];
break;
case "unauthenticated-401":
statuses = [401];
kind = "UNAUTHENTICATED";
outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE";
observer = "UNAUTHENTICATED";
bodies = [attemptBody("CANCELLED_WITHOUT_READ", 0, 0)];
break;
case "forbidden-403":
statuses = [403];
kind = "FORBIDDEN";
outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE";
observer = "FORBIDDEN";
bodies = [attemptBody("CANCELLED_WITHOUT_READ", 0, 0)];
break;
case "not-found-404":
statuses = [404];
kind = "PROBLEM";
detail = "404";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED";
observer = command ? "MAYBE_APPLIED" : "NOT_STARTED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(404, "NOT_FOUND")),
65_536,
),
];
break;
case "conflict-409":
statuses = [409];
kind = "PROBLEM";
detail = "409";
outcomeEffect = "NOT_APPLIED";
observer = command ? "NOT_APPLIED" : "NOT_STARTED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(409, "CONFLICT")),
65_536,
),
];
break;
case "in-flight-409":
// 0929/03-01. The same key is still running: the command stays unknown.
statuses = [409];
kind = "PROBLEM";
detail = "409";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED";
observer = command ? "MAYBE_APPLIED" : "NOT_STARTED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(409, "IDEMPOTENT_IN_FLIGHT")),
65_536,
),
];
break;
case "validation-422":
statuses = [422];
kind = "PROBLEM";
detail = "422";
outcomeEffect = "NOT_APPLIED";
observer = command ? "NOT_APPLIED" : "NOT_STARTED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(422, "VALIDATION_REJECTED")),
65_536,
),
];
break;
case "rate-limited-429": {
const attemptCount = command ? 1 : 3;
statuses = Array.from({ length: attemptCount }, () => 429);
kind = "RATE_LIMITED";
outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE";
observer = "RATE_LIMITED";
retryReasons = command ? [] : ["HTTP_429", "HTTP_429"];
media = Array.from({ length: attemptCount }, () => "application/json");
bodies = Array.from({ length: attemptCount }, () =>
attemptBody("CANCELLED_WITHOUT_READ", 0, 0),
);
break;
}
case "server-retry-success":
if (command) {
statuses = [503];
kind = "PROBLEM";
detail = "503";
outcomeEffect = "MAYBE_APPLIED";
observer = "MAYBE_APPLIED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(503, "SERVER_FAILURE")),
65_536,
),
];
} else {
statuses = [503, successStatus];
retryReasons = ["HTTP_503"];
media = ["application/json", "application/json"];
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(503, "SERVER_FAILURE")),
65_536,
),
attemptBody("FULLY_READ_WITHIN_BOUND", jsonBytes(payload), ceiling),
];
}
break;
case "server-terminal-503": {
const attemptCount = command ? 1 : 3;
statuses = Array.from({ length: attemptCount }, () => 503);
kind = "PROBLEM";
detail = "503";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED";
observer = command ? "MAYBE_APPLIED" : "NOT_STARTED";
retryReasons = command ? [] : ["HTTP_503", "HTTP_503"];
media = Array.from({ length: attemptCount }, () => "application/json");
bodies = Array.from({ length: attemptCount }, () =>
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(503, "SERVER_FAILURE")),
65_536,
),
);
break;
}
}
const executionId = `${operationId}::${scenarioId}` as const;
return Object.freeze({
executionId,
operationId,
scenarioId,
expected: Object.freeze({
status: Object.freeze({
attempts: Object.freeze(statuses),
final: statuses.at(-1)!,
}),
outcome: Object.freeze({ kind, detail }),
effect: Object.freeze({ outcome: outcomeEffect, observer }),
retry: Object.freeze({
count: retryReasons.length,
reasons: Object.freeze(retryReasons),
}),
fetch: Object.freeze({
count: statuses.length,
observerAttempts: statuses.length,
agrees: true,
}),
media: Object.freeze({
attempts: Object.freeze(media),
final: media.at(-1) ?? null,
}),
body: Object.freeze({ attempts: Object.freeze(bodies) }),
scope: Object.freeze({
start: "CURRENT" as const,
end: scopeEnd,
signal: scopeSignal,
cancellationOwner,
}),
}),
testDeadlineOverrideMs,
});
}
const OPERATION_SCENARIOS = Object.freeze({
TEST_LIST_ENTITIES: HTTP_SCENARIO_IDS,
TEST_GET_ENTITY: Object.freeze(
HTTP_SCENARIO_IDS.filter((scenario) => scenario !== "empty"),
),
TEST_CREATE_ENTITY: Object.freeze(
HTTP_SCENARIO_IDS.filter(
(scenario) => scenario !== "empty" && scenario !== "aborted",
),
),
} satisfies Readonly<
Record<CatalogOperationId, readonly HttpScenarioId[]>
>);
export const HTTP_SCENARIO_EXPECTATIONS = Object.freeze(
HTTP_SCENARIO_OPERATION_IDS.flatMap((operationId) =>
OPERATION_SCENARIOS[operationId].map((scenarioId) =>
expectationFor(operationId, scenarioId),
),
),
);
export const HTTP_SCENARIO_EXECUTION_IDS = Object.freeze(
HTTP_SCENARIO_EXPECTATIONS.map((expectation) => expectation.executionId),
);
export const OPERATION_SCENARIO_CATALOG = Object.freeze(
Object.fromEntries(
HTTP_SCENARIO_OPERATION_IDS.map((operationId) => [
operationId,
Object.freeze(
HTTP_SCENARIO_EXPECTATIONS.filter(
(expectation) => expectation.operationId === operationId,
).map((expectation) => expectation.scenarioId),
),
]),
) as Readonly<
Record<CatalogOperationId, readonly HttpScenarioId[]>
>,
);
export function assertOperationScenario(
operationId: HttpScenarioOperationId,
scenario: HttpScenarioId,
) {
const catalog: Readonly<Partial<Record<string, readonly HttpScenarioId[]>>> =
OPERATION_SCENARIO_CATALOG;
const declared = catalog[operationId];
if (declared === undefined) {
throw new Error(
`${operationId} is not a catalog operation; answer it with createHttpScenarioHandler`,
);
}
if (!declared.includes(scenario)) {
throw new Error(`Scenario ${scenario} is not declared for ${operationId}`);
}
return scenario;
}