Files
clean-architecture-frontend…/tests/unit/api-operation-v2.test.ts
T
DongHyeonka 32da8a40e9 test(contracts): 조립기·선언 검증의 쓰기 API 규칙 5개를 고정한다 (07-06)
문제
조립기와 선언 검증의 쓰기 API 규칙 5개는 지워도 관련 테스트가 모두
통과한다(리뷰 변이 MX1·MX2·MX5·MX6·MX9).
- MX1 읽기 operation의 command descriptor 금지
  (external-contract-runtime.ts). 실행기는 쓰기 여부를 메서드가 아니라
  commandEffect !== null로 정하므로 GET이 쓰기로 처리되는 것을 막는
  유일한 경계다.
- MX9 KEYED 쓰기의 복구 descriptor 필수
- MX6 NEVER 재시도와 재시도 예산 1 이상의 모순 거부
- MX5 V2 KEYED_COMMAND의 idempotencyKeyPolicy REQUIRED 정합
  (api-operations.ts)
- MX2 mapper 레지스트리 키 = mapperId (boundary-mapper.ts)
조립기는 여러 번 다시 쓰인 파일이라 규칙 줄이 빠져도 CI가 모른다.

고른 방법
규칙마다 그 규칙만 어긴 행 하나로 실패 사례를 둔다. 오류 메시지는 기능
작성자가 쓰기 API 규칙을 배우는 통로라 reason 문자열을 그대로 단언한다.
정상 대조군은 기존 사례(TEST_CONTRACT_CONTRIBUTION 조립, command()
정의, 키가 맞는 mapper 등록)를 쓰거나 같은 테스트 안에 둔다. 코드 변경은
없다.

버린 대안
- 메시지 대신 ContractContributionError 종류만 단언: 다른 규칙이 먼저
  실패해도 통과해서 변이를 놓칠 수 있다.

위험·한계
- 메시지 문구를 바꾸면 테스트도 바꿔야 한다. 의도한 결합이다.
- MX6은 실행기(http-retry-lifecycle)가 한 번 더 막는다. 이 테스트는
  조립 단계의 안내 메시지를 지킨다.

검증
- RED: 변이 5개를 하나씩 넣고 바꾼 3파일을 돌렸다. 이 커밋 전 테스트로는
  5개 모두 살아남음(26/26 통과). 새 테스트로는 5개 모두 죽음, 각 변이마다
  해당 사례 1건만 실패(30/31).
- GREEN: 변이 없이 31/31 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00

123 lines
3.9 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
composeApiOperations,
defineRestOperation,
type RestOperationV2,
} from "../../src/contracts/api-operations.ts";
import { API_OPERATIONS } from "../../src/features/loaded-feature-runtimes.ts";
function operation(operationId = "GET_RESOURCE") {
return defineRestOperation({
contractVersion: 2,
protocol: "REST",
semantics: "QUERY",
method: "GET",
path: "/resources/{resourceId}",
operationId,
auth: "external-session",
timeoutMs: 5_000,
idempotency: "safe",
retry: "runtime",
replayPolicy: "SAFE",
idempotencyKeyPolicy: "NONE",
requestSource: "none",
requestSchema: "NoRequest",
responseSchema: "ResourcePayload",
mapperId: "ResourceMapper",
successStatuses: [200],
responseMediaTypes: ["application/json"],
maxResponseBytes: 32_768,
providerId: "PRIMARY_API",
authProfileId: "REFERENCE_EXTERNAL_BEARER",
csrfProfileId: "NO_CSRF_BEARER",
pathSchema: "ResourceParams",
pathParameterNames: ["resourceId"],
maxEncodedSearchBytes: 0,
owner: "test",
});
}
describe("REST operation v2 registry", () => {
it("rejects duplicate contributions before an object spread can overwrite them", () => {
const selected = operation();
expect(() =>
composeApiOperations([
{ GET_RESOURCE: selected },
{ GET_RESOURCE: selected },
]),
).toThrow("Duplicate API operation");
});
it("rejects an unsafe query/replay policy combination", () => {
expect(() =>
defineRestOperation({
...operation(),
method: "POST",
}),
).toThrow("Incoherent REST replay contract");
});
// 07-06 (MX5). A KEYED command without a required idempotency key would be
// resent with no key to bind the retry to.
it("rejects a KEYED_COMMAND whose idempotency key is not required", () => {
expect(() =>
defineRestOperation({ ...command(), idempotencyKeyPolicy: "NONE" }),
).toThrow("Incoherent REST replay contract: CREATE_RESOURCE");
expect(defineRestOperation(command()).idempotencyKeyPolicy).toBe("REQUIRED");
});
});
function command(): RestOperationV2 {
return {
...operation(),
semantics: "COMMAND",
method: "POST",
path: "/resources",
operationId: "CREATE_RESOURCE",
idempotency: "keyed",
replayPolicy: "KEYED_COMMAND",
idempotencyKeyPolicy: "REQUIRED",
requestSource: "body",
pathSchema: "NoRequest",
pathParameterNames: [],
};
}
/**
* R-7.4. CSRF protection is chosen from the HTTP method, so a COMMAND sent
* as GET/HEAD would skip it. browser-rpc and the V3 composition already bind
* commands to unsafe methods; REST V2 must too.
*/
describe("REST operation v2 command method and enum rules", () => {
it.each(["POST", "PUT", "PATCH", "DELETE"])("accepts a COMMAND sent as %s", (method) => {
expect(defineRestOperation({ ...command(), method }).method).toBe(method);
});
it.each(["GET", "HEAD", "OPTIONS", "post"])("rejects a COMMAND sent as %s", (method) => {
expect(() => defineRestOperation({ ...command(), method })).toThrow(TypeError);
expect(() =>
composeApiOperations([{ CREATE_RESOURCE: { ...command(), method } }]),
).toThrow(TypeError);
});
it.each<[string, Record<string, unknown>]>([
["semantics", { semantics: "SUBSCRIBE" }],
["replayPolicy", { replayPolicy: "ALWAYS" }],
])("rejects an unknown %s value", (_field, patch) => {
void _field;
const candidate = { ...command(), ...patch } as unknown as RestOperationV2;
expect(() => defineRestOperation(candidate)).toThrow(TypeError);
});
it("keeps every installed REST v2 operation valid", () => {
for (const installed of Object.values(API_OPERATIONS)) {
if (installed.contractVersion !== 2) continue;
expect(
() => defineRestOperation(installed as RestOperationV2),
installed.operationId,
).not.toThrow();
}
});
});