문제: 샘플 제거 절차(scripts/test-sample-removal.ts)의 SAMPLE_EXTRAS가 플랫폼 검사도 함께 지운다. HTTP 실패 시나리오 카탈로그(57개)와 tests/mocks, test:http-scenario-evidence(FE-GATE-007), 기능 API 타입 음성 fixture 8개와 check:types:fixture:* 8개(FE-GATE-003)가 참조 기능 계약을 import해서 샘플 소유로 묶여 있었다. 드릴은 플랫폼 경로 4개만 확인하므로 통과하고, 제품은 가드레일이 줄었다는 것을 모른다. 방법: 카탈로그와 handler를 tests/helpers/external-contract-fixture.ts의 테스트 계약(TEST_LIST/DETAIL, 명령)으로 옮겼다. 바이트 상한·명령 여부·성공 status는 계약에서 읽는다. 명령은 효과를 분류하는 패키지처럼 TEST_CLASSIFIED_CREATE_HTTP_CONTRACT를 더해 기존 기대값(401/403/429·422· 409 CONFLICT는 NOT_APPLIED, 409 IN_FLIGHT·404·503은 MAYBE_APPLIED)을 그대로 지킨다. TEST_CREATE_HTTP_CONTRACT의 분류기는 실행기 테스트가 "분류기 없음"을 확인하는 데 쓰므로 바꾸지 않았다. 문제 스키마에 선택 code만 더했다. 타입 fixture는 fixture tsconfig만 컴파일하는 fixture-feature-contract.ts의 테스트 기능(operation ID를 literal로 좁힌 테스트 계약, "fixture-feature" 입력 등록)을 쓴다. 등록 augmentation이 app·test 프로그램에 들어가지 않는다. 참조 기능 전용 handler(성공 응답만 쓰였다)는 tests/features/reference-feature 로 옮겼다. test-evidence.json의 owner는 platform이다. SAMPLE_EXTRAS에서 이 경로·스크립트를 빼고, 드릴의 플랫폼 보존 확인 목록에 16개 경로를 더했다. 샘플이 증거 정책을 갖지 않으므로 "등록 안 됨" 오류 검사는 지웠다. 버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만 검사는 계속 사라진다. 위험: fixture 스크립트 이름(check:types:fixture:reference-operation)과 파일 이름은 그대로라 이름이 내용(TEST_GET_ENTITY)과 다르다. CI 스크립트· gates·워크플로 스냅샷을 함께 바꿔야 해서 미뤘다. 드릴의 제외 목록에 있는 tests/unit/http-scenario-evidence.test.ts는 그대로 뒀다. test:sample-removal 자체는 pnpm이 필요해 돌리지 않았다. 검증: RED는 기준 복사본에 드릴의 삭제 목록을 적용했다. 카탈로그 테스트· tests/mocks·타입 fixture 16파일이 지워지고 CI 스크립트 9개가 빠지는데 보존 확인은 4/4로 통과한다. GREEN은 같은 적용 뒤 보존 확인 16/16, 잔여 이름은 드릴이 빼는 removal-fixture.test.ts 하나, 타입 fixture 8개가 기존과 같은 진단(TS2345·2741·2353·2322·2345·2322·2322·2339) 1건씩으로 실패, 카탈로그 57/57 실행·check-test-evidence --scenario-only PASS, tests/component와 카탈로그 36파일 226개 통과, tsc -p tsconfig.test.json 통과. worktree에서는 테스트 계약 사용 파일·참조 기능·카탈로그 59파일 535개, scale session 2파일 통과, 음성 fixture의 양성 대조 컴파일 통과, tsc test·node 통과, check-ci-contract PASS, 바꾼 파일 eslint 통과.
409 lines
13 KiB
TypeScript
409 lines
13 KiB
TypeScript
import { mkdir, rm } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
|
|
|
import { readBoundedBytes } from "../../src/adapters/http/bounded-body-reader.ts";
|
|
import {
|
|
createContractHttpExecutor,
|
|
type HttpExecutionObservation,
|
|
} from "../../src/adapters/http/http-execution-v3.ts";
|
|
import {
|
|
type InstalledHttpContract,
|
|
} from "../../src/contracts/external-contract-runtime.ts";
|
|
import type { CacheScopeSnapshot } from "../../src/contracts/server-state-scope.ts";
|
|
import {
|
|
computeHttpScenarioCatalogDigest,
|
|
httpScenarioReceiptSchema,
|
|
type AttemptStatus,
|
|
type BodyDisposition,
|
|
type HttpScenarioAssertionGroups,
|
|
type RetryReason,
|
|
} from "../../scripts/lib/http-scenario-evidence.ts";
|
|
import { writeValidatedJsonArtifact } from "../../scripts/lib/validated-json-artifact.ts";
|
|
import { createTestEntityScenarioHandlers } from "../mocks/handlers/test-entities.ts";
|
|
import { createStrictMockServer } from "../mocks/server.ts";
|
|
import {
|
|
HTTP_SCENARIO_CONTRACTS,
|
|
HTTP_SCENARIO_EXECUTION_IDS,
|
|
HTTP_SCENARIO_EXPECTATIONS,
|
|
HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION,
|
|
OPERATION_SCENARIO_CATALOG,
|
|
type HttpScenarioExpectation,
|
|
type HttpScenarioOperationId,
|
|
} from "../mocks/scenarios/catalog.ts";
|
|
|
|
/** A low-cardinality route identity, as a feature binding passes it. */
|
|
const ROUTE_ID = "TEST_ENTITY_ROUTE";
|
|
|
|
const RECEIPT_PATH = path.resolve(
|
|
"artifacts/tests/http-scenario-executions.json",
|
|
);
|
|
const mockApi = createStrictMockServer();
|
|
|
|
beforeAll(mockApi.listen);
|
|
afterAll(mockApi.close);
|
|
|
|
type AttemptTrace = {
|
|
status: AttemptStatus;
|
|
media: string | null;
|
|
pulledBytes: number;
|
|
appliedCeiling: number | null;
|
|
completed: boolean;
|
|
cancelled: boolean;
|
|
};
|
|
|
|
function operationFor(operationId: HttpScenarioOperationId) {
|
|
return HTTP_SCENARIO_CONTRACTS[operationId] as InstalledHttpContract<
|
|
unknown,
|
|
unknown,
|
|
unknown
|
|
>;
|
|
}
|
|
|
|
function inputFor(operationId: HttpScenarioOperationId): unknown {
|
|
if (operationId === "TEST_LIST_ENTITIES") return { limit: 20 };
|
|
if (operationId === "TEST_GET_ENTITY") return { entityId: "entity-1" };
|
|
return { name: "Created" };
|
|
}
|
|
|
|
function normalizeMedia(response: Response): string | null {
|
|
const value = response.headers.get("content-type");
|
|
return value?.split(";", 1)[0]?.trim().toLowerCase() || null;
|
|
}
|
|
|
|
function tracingFetcher(attempts: AttemptTrace[]): typeof fetch {
|
|
return async (input, init) => {
|
|
const trace: AttemptTrace = {
|
|
status: "PENDING_ABORT",
|
|
media: null,
|
|
pulledBytes: 0,
|
|
appliedCeiling: null,
|
|
completed: false,
|
|
cancelled: false,
|
|
};
|
|
attempts.push(trace);
|
|
let response: Response;
|
|
try {
|
|
response = await fetch(input, init);
|
|
} catch (error) {
|
|
trace.status = init?.signal?.aborted
|
|
? "PENDING_ABORT"
|
|
: "NETWORK_REJECTION";
|
|
throw error;
|
|
}
|
|
trace.status = response.status;
|
|
trace.media = normalizeMedia(response);
|
|
if (!response.body) return response;
|
|
|
|
const reader = response.body.getReader();
|
|
const proxy = new ReadableStream<Uint8Array>(
|
|
{
|
|
async pull(controller) {
|
|
try {
|
|
const chunk = await reader.read();
|
|
if (chunk.done) {
|
|
trace.completed = true;
|
|
controller.close();
|
|
return;
|
|
}
|
|
trace.pulledBytes += chunk.value.byteLength;
|
|
controller.enqueue(chunk.value);
|
|
} catch (error) {
|
|
controller.error(error);
|
|
}
|
|
},
|
|
cancel(reason) {
|
|
trace.cancelled = true;
|
|
// MSW-transferred oversized bodies leave the original cancel promise
|
|
// permanently pending. Record and request cancellation without making
|
|
// the proxy response less responsive than the real executor contract.
|
|
void reader.cancel(reason).catch(() => {});
|
|
},
|
|
},
|
|
{ highWaterMark: 0 },
|
|
);
|
|
return new Response(proxy, {
|
|
status: response.status,
|
|
statusText: response.statusText,
|
|
headers: response.headers,
|
|
});
|
|
};
|
|
}
|
|
|
|
function outcomeDetail(outcome: Readonly<Record<string, unknown>>): string | null {
|
|
if (outcome.kind === "CONTRACT_VIOLATION") {
|
|
return String((outcome.violation as Readonly<{ kind: string }>).kind);
|
|
}
|
|
if (outcome.kind === "TRANSPORT_FAILURE") {
|
|
return String((outcome.failure as Readonly<{ kind: string }>).kind);
|
|
}
|
|
if (outcome.kind === "PROBLEM") {
|
|
return String((outcome.metadata as Readonly<{ status: number }>).status);
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function retryReason(status: AttemptStatus): RetryReason {
|
|
if (status === "NETWORK_REJECTION") return "NETWORK_FAILURE";
|
|
if (status === 429) return "HTTP_429";
|
|
if (status === 503) return "HTTP_503";
|
|
throw new Error(`Sleep followed a non-retryable attempt: ${String(status)}`);
|
|
}
|
|
|
|
function bodyDisposition(
|
|
trace: AttemptTrace,
|
|
outcome: Readonly<Record<string, unknown>>,
|
|
): BodyDisposition {
|
|
if (trace.status === "NETWORK_REJECTION" || trace.status === "PENDING_ABORT") {
|
|
return "NO_RESPONSE";
|
|
}
|
|
if (
|
|
outcome.kind === "CONTRACT_VIOLATION" &&
|
|
outcomeDetail(outcome) === "RESPONSE_TOO_LARGE" &&
|
|
trace.cancelled
|
|
) {
|
|
return "REJECTED_LIMIT";
|
|
}
|
|
if (trace.completed) return "FULLY_READ_WITHIN_BOUND";
|
|
if (trace.cancelled) return "CANCELLED_WITHOUT_READ";
|
|
throw new Error(`Response body was neither consumed nor cancelled: ${trace.status}`);
|
|
}
|
|
|
|
async function waitForHandler(
|
|
ready: Promise<void>,
|
|
executionId: string,
|
|
): Promise<void> {
|
|
let watchdog: ReturnType<typeof setTimeout> | undefined;
|
|
try {
|
|
await Promise.race([
|
|
ready,
|
|
new Promise<never>((_resolve, reject) => {
|
|
watchdog = setTimeout(
|
|
() => reject(new Error(`Handler readiness timed out: ${executionId}`)),
|
|
2_000,
|
|
);
|
|
}),
|
|
]);
|
|
} finally {
|
|
if (watchdog !== undefined) clearTimeout(watchdog);
|
|
}
|
|
}
|
|
|
|
async function executeScenario(
|
|
entry: HttpScenarioExpectation,
|
|
): Promise<HttpScenarioAssertionGroups> {
|
|
const physicalAttempts: AttemptTrace[] = [];
|
|
const sleeps: RetryReason[] = [];
|
|
const observations: HttpExecutionObservation[] = [];
|
|
const caller = new AbortController();
|
|
const scopeLifetime = new AbortController();
|
|
let scopeCurrent = true;
|
|
let handlerReady!: () => void;
|
|
const ready = new Promise<void>((resolve) => {
|
|
handlerReady = resolve;
|
|
});
|
|
const scope: CacheScopeSnapshot = Object.freeze({
|
|
generation: 1,
|
|
fingerprint: "scenario-scope-1",
|
|
identities: Object.freeze({}) as CacheScopeSnapshot["identities"],
|
|
signal: scopeLifetime.signal,
|
|
isCurrent: () => scopeCurrent,
|
|
});
|
|
const baseOperation = operationFor(entry.operationId);
|
|
const operation =
|
|
entry.testDeadlineOverrideMs === null
|
|
? baseOperation
|
|
: Object.freeze({
|
|
...baseOperation,
|
|
frontend: Object.freeze({
|
|
...baseOperation.frontend,
|
|
totalDeadlineMs: entry.testDeadlineOverrideMs,
|
|
}),
|
|
});
|
|
const fetcher = tracingFetcher(physicalAttempts);
|
|
const executor = createContractHttpExecutor({
|
|
baseUrl: "https://api.test",
|
|
maxRetryAttempts: 2,
|
|
attachCredentials: () => ({ kind: "READY", headers: {} }),
|
|
fetcher,
|
|
random: () => 0,
|
|
readBoundedResponseBytes: async (response, maximumBytes) => {
|
|
const trace = physicalAttempts.at(-1);
|
|
if (!trace) throw new Error("Body reader ran before a physical attempt");
|
|
if (trace.appliedCeiling !== null) {
|
|
throw new Error("Body reader ran more than once for one attempt");
|
|
}
|
|
trace.appliedCeiling = maximumBytes;
|
|
return readBoundedBytes(response, maximumBytes);
|
|
},
|
|
sleep: async () => {
|
|
const prior = physicalAttempts.at(-1);
|
|
if (!prior) throw new Error("Retry sleep occurred before an attempt");
|
|
sleeps.push(retryReason(prior.status));
|
|
},
|
|
observe: (observation) => observations.push(observation),
|
|
});
|
|
|
|
mockApi.server.use(
|
|
...createTestEntityScenarioHandlers({
|
|
scenarios: { [entry.operationId]: entry.scenarioId },
|
|
onAttempt(attempt) {
|
|
if (
|
|
attempt.operationId === entry.operationId &&
|
|
attempt.scenarioId === entry.scenarioId
|
|
) {
|
|
handlerReady();
|
|
}
|
|
},
|
|
}),
|
|
);
|
|
|
|
try {
|
|
const execution = executor.execute(operation, inputFor(entry.operationId), {
|
|
routeId: ROUTE_ID,
|
|
scope,
|
|
signal: caller.signal,
|
|
...(entry.operationId === "TEST_CREATE_ENTITY"
|
|
? {
|
|
intent: Object.freeze({
|
|
intentId: `intent-${entry.scenarioId}`,
|
|
operationId: entry.operationId,
|
|
canonicalInputIdentity: "scenario-input",
|
|
idempotencyKey: `scenario-${entry.scenarioId}`,
|
|
createdAtMonotonicMs: 1,
|
|
}),
|
|
}
|
|
: {}),
|
|
});
|
|
|
|
if (entry.scenarioId === "timeout" || entry.scenarioId === "aborted") {
|
|
await waitForHandler(ready, entry.executionId);
|
|
if (entry.scenarioId === "aborted") {
|
|
if (entry.operationId === "TEST_LIST_ENTITIES") {
|
|
caller.abort();
|
|
} else {
|
|
scopeCurrent = false;
|
|
scopeLifetime.abort();
|
|
}
|
|
}
|
|
}
|
|
const outcome = (await execution) as unknown as Readonly<Record<string, unknown>>;
|
|
expect(observations, `${entry.executionId} observer count`).toHaveLength(1);
|
|
const observation = observations[0]!;
|
|
const observedSignal = scopeLifetime.signal.aborted ? "ABORTED" : "ACTIVE";
|
|
const cancellationOwner =
|
|
observation.terminalReason === "TIMEOUT"
|
|
? "DEADLINE"
|
|
: caller.signal.aborted
|
|
? "CALLER"
|
|
: scopeLifetime.signal.aborted
|
|
? "SCOPE_FENCE"
|
|
: "NONE";
|
|
const observed: HttpScenarioAssertionGroups = Object.freeze({
|
|
status: Object.freeze({
|
|
attempts: Object.freeze(physicalAttempts.map((attempt) => attempt.status)),
|
|
final: physicalAttempts.at(-1)!.status,
|
|
}),
|
|
outcome: Object.freeze({
|
|
kind: String(outcome.kind),
|
|
detail: outcomeDetail(outcome),
|
|
}),
|
|
effect: Object.freeze({
|
|
outcome: String(outcome.effect),
|
|
observer: observation.terminalReason,
|
|
}),
|
|
retry: Object.freeze({ count: sleeps.length, reasons: Object.freeze(sleeps) }),
|
|
fetch: Object.freeze({
|
|
count: physicalAttempts.length,
|
|
observerAttempts: observation.attemptCount,
|
|
agrees: physicalAttempts.length === observation.attemptCount,
|
|
}),
|
|
media: Object.freeze({
|
|
attempts: Object.freeze(physicalAttempts.map((attempt) => attempt.media)),
|
|
final: physicalAttempts.at(-1)?.media ?? null,
|
|
}),
|
|
body: Object.freeze({
|
|
attempts: Object.freeze(
|
|
physicalAttempts.map((attempt) =>
|
|
Object.freeze({
|
|
disposition: bodyDisposition(attempt, outcome),
|
|
pulledBytes: attempt.pulledBytes,
|
|
ceiling: attempt.appliedCeiling ?? 0,
|
|
}),
|
|
),
|
|
),
|
|
}),
|
|
scope: Object.freeze({
|
|
start: "CURRENT",
|
|
end: scopeCurrent ? "CURRENT" : "STALE",
|
|
signal: observedSignal,
|
|
cancellationOwner,
|
|
}),
|
|
});
|
|
return observed;
|
|
} finally {
|
|
caller.abort();
|
|
scopeLifetime.abort();
|
|
mockApi.reset();
|
|
}
|
|
}
|
|
|
|
describe("HTTP scenario catalog execution evidence", () => {
|
|
it("declares exactly the 57 behaviorally distinct operation scenarios", () => {
|
|
const executionIds = Object.entries(OPERATION_SCENARIO_CATALOG).flatMap(
|
|
([operationId, scenarioIds]) =>
|
|
scenarioIds.map((scenarioId) => `${operationId}::${scenarioId}`),
|
|
);
|
|
|
|
expect(OPERATION_SCENARIO_CATALOG.TEST_LIST_ENTITIES).toHaveLength(20);
|
|
expect(OPERATION_SCENARIO_CATALOG.TEST_GET_ENTITY).toHaveLength(19);
|
|
expect(OPERATION_SCENARIO_CATALOG.TEST_CREATE_ENTITY).toHaveLength(18);
|
|
expect(executionIds).toHaveLength(57);
|
|
expect(new Set(executionIds)).toHaveLength(57);
|
|
expect(executionIds).toEqual(HTTP_SCENARIO_EXECUTION_IDS);
|
|
});
|
|
|
|
it("executes every declared scenario and publishes one complete receipt", async () => {
|
|
await rm(RECEIPT_PATH, { force: true });
|
|
const rows: Array<Readonly<{
|
|
executionId: string;
|
|
expected: HttpScenarioAssertionGroups;
|
|
observed: HttpScenarioAssertionGroups;
|
|
testDeadlineOverrideMs: number | null;
|
|
}>> = [];
|
|
|
|
for (const entry of HTTP_SCENARIO_EXPECTATIONS) {
|
|
const observed = await executeScenario(entry);
|
|
expect(observed, entry.executionId).toEqual(entry.expected);
|
|
rows.push(
|
|
Object.freeze({
|
|
executionId: entry.executionId,
|
|
expected: entry.expected,
|
|
observed,
|
|
testDeadlineOverrideMs: entry.testDeadlineOverrideMs,
|
|
}),
|
|
);
|
|
}
|
|
|
|
const sortedRows = [...rows].sort((left, right) =>
|
|
left.executionId.localeCompare(right.executionId),
|
|
);
|
|
await mkdir(path.dirname(RECEIPT_PATH), { recursive: true });
|
|
await writeValidatedJsonArtifact({
|
|
path: RECEIPT_PATH,
|
|
schema: httpScenarioReceiptSchema,
|
|
value: {
|
|
schemaVersion: HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION,
|
|
catalogDigest: computeHttpScenarioCatalogDigest(
|
|
HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION,
|
|
HTTP_SCENARIO_EXPECTATIONS,
|
|
),
|
|
catalogTotal: 57,
|
|
executedIds: sortedRows.map((row) => row.executionId),
|
|
rows: sortedRows,
|
|
},
|
|
});
|
|
}, 30_000);
|
|
});
|