test(evidence): HTTP 시나리오와 타입 음성 fixture를 테스트 계약으로 옮긴다 (0929/10-02)

문제: 샘플 제거 절차(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 통과.
This commit is contained in:
DongHyeonka
2026-11-03 01:18:36 +09:00
parent ca74caa2a8
commit 498ae87554
19 changed files with 492 additions and 374 deletions
+3 -3
View File
@@ -2,7 +2,7 @@
"schemaVersion": 2,
"scenarioCatalogs": [
{
"owner": "reference-feature",
"owner": "platform",
"path": "tests/mocks/scenarios/catalog.ts",
"expectationExport": "HTTP_SCENARIO_EXPECTATIONS",
"receiptPath": "artifacts/tests/http-scenario-executions.json",
@@ -11,8 +11,8 @@
],
"sourceContracts": [
{
"owner": "reference-feature",
"path": "tests/mocks/handlers/reference-resources.ts",
"owner": "platform",
"path": "tests/mocks/handlers/test-entities.ts",
"requiredTokens": [
"assertOperationScenario",
"../scenarios/catalog.ts"
@@ -704,6 +704,10 @@ open dialog, invalid form, expanded menu 같은 state story로 보완한다.
`config/testing/test-evidence.json`의 owner별 contribution으로 등록한다. 따라서
feature 제거 시 해당 contribution도 함께 제거할 수 있고 공통 evidence checker는
특정 sample 경로를 하드코딩하지 않는다.
템플릿의 catalog(`tests/mocks/scenarios/catalog.ts`)는 owner가 `platform`이다.
sample feature가 아니라 `tests/helpers/external-contract-fixture.ts`의 테스트
계약 3개(조회 목록, 조회 단건, 명령)로 돌므로 sample을 지워도 남는다(0929/10-02).
바이트 상한·명령 여부·성공 status는 계약에서 읽는다.
### 11.1 목표 구조
+23 -43
View File
@@ -46,8 +46,10 @@ type FeatureExtras = Readonly<{
const SAMPLE_EXTRAS: Readonly<Record<string, FeatureExtras>> = Object.freeze({
"reference-feature": Object.freeze({
// 0929/10-02. The HTTP scenario catalog (tests/mocks) and the negative
// type fixtures of the feature APIs run on the test contracts, so they are
// platform checks and stay (commonTestPaths below).
paths: [
"tests/integration/http-scenario-catalog.test.ts",
"tests/component/product-feature-switch.test.tsx",
"tests/e2e/reference-form.spec.ts",
"tests/e2e/reference-route.spec.ts",
@@ -57,40 +59,12 @@ const SAMPLE_EXTRAS: Readonly<Record<string, FeatureExtras>> = Object.freeze({
"scripts/scale/measure-feature-shape-growth.ts",
"config/scale/feature-shape-growth.json",
"config/scale/feature-shape-ceilings.json",
"tests/mocks",
"tests/fixtures/typecheck/invalid-feature-input.ts",
"tests/fixtures/typecheck/invalid-reference-operation.ts",
"tests/fixtures/typecheck/invalid-http-operation-input.ts",
"tests/fixtures/typecheck/invalid-http-wire-mapper.ts",
"tests/fixtures/typecheck/invalid-http-operation-id.ts",
"tests/fixtures/typecheck/invalid-http-route-id.ts",
"tests/fixtures/typecheck/invalid-feature-contribution-input.ts",
"tests/fixtures/typecheck/invalid-feature-capability-selection.ts",
"tests/fixtures/typecheck/tsconfig.feature-input.json",
"tests/fixtures/typecheck/tsconfig.reference-operation.json",
"tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"tests/fixtures/typecheck/tsconfig.http-route-id.json",
"tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
],
ciScripts: [
"check:types:fixture:feature-input",
"check:types:fixture:reference-operation",
"check:types:fixture:http-operation-input",
"check:types:fixture:http-wire-mapper",
"check:types:fixture:http-operation-id",
"check:types:fixture:http-route-id",
"check:types:fixture:feature-contribution-input",
"check:types:fixture:feature-capability-selection",
"test:http-scenario-evidence",
"test:reference-feature",
],
evidencePathFragments: [
"reference-feature.xml",
"http-scenario-executions",
"http-scenario-evidence",
],
residue: /REFERENCE_RESOURCE|reference-feature|reference-resource/i,
}),
@@ -161,6 +135,20 @@ const commonTestPaths = [
"tests/unit/http-execution-v3.test.ts",
"tests/unit/runtime-adapters.test.ts",
"tests/integration/http-execution-v3-observability.test.ts",
// 0929/10-02. HTTP scenario evidence (FE-GATE-007) and the feature API
// negative type fixtures (FE-GATE-003) run on the test contracts.
"tests/integration/http-scenario-catalog.test.ts",
"tests/mocks/scenarios/catalog.ts",
"tests/mocks/handlers/test-entities.ts",
"tests/fixtures/typecheck/fixture-feature-contract.ts",
"tests/fixtures/typecheck/invalid-feature-input.ts",
"tests/fixtures/typecheck/invalid-reference-operation.ts",
"tests/fixtures/typecheck/invalid-http-operation-input.ts",
"tests/fixtures/typecheck/invalid-http-wire-mapper.ts",
"tests/fixtures/typecheck/invalid-http-operation-id.ts",
"tests/fixtures/typecheck/invalid-http-route-id.ts",
"tests/fixtures/typecheck/invalid-feature-contribution-input.ts",
"tests/fixtures/typecheck/invalid-feature-capability-selection.ts",
];
const featureOwnedPaths = [
featureSource,
@@ -313,21 +301,17 @@ try {
const evidencePolicy = JSON.parse(
await readFile(evidencePolicyFile, "utf8"),
) as EvidencePolicy;
let removedEvidenceContributions = 0;
for (const policyKey of ["scenarioCatalogs", "sourceContracts"] as const) {
const contributions = evidencePolicy[policyKey];
if (!Array.isArray(contributions)) {
throw new Error(`Test evidence policy is missing ${policyKey}`);
}
evidencePolicy[policyKey] = contributions.filter((candidate: unknown) => {
const contribution = candidate as EvidenceContribution;
const retained = contribution.owner !== featureId;
if (!retained) removedEvidenceContributions += 1;
return retained;
});
}
if (isSample && removedEvidenceContributions === 0) {
throw new Error("Reference feature test evidence policy is not registered");
// A feature's own evidence goes with it. The sample has none since
// 0929/10-02: the HTTP scenario catalog is owned by the platform.
evidencePolicy[policyKey] = contributions.filter(
(candidate: unknown) =>
(candidate as EvidenceContribution).owner !== featureId,
);
}
await writeFile(
evidencePolicyFile,
@@ -376,10 +360,6 @@ try {
scripts: Record<string, string>;
};
pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts);
if (isSample) {
delete fixturePackage.scripts["check:http-scenario-evidence"];
delete fixturePackage.scripts["check:http-scenario-evidence:fixture"];
}
await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
@@ -16,7 +16,7 @@ import {
import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.ts";
import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.tsx";
import { createBootstrapHandlers } from "../../mocks/handlers/bootstrap.ts";
import { createReferenceScenarioHandlers } from "../../mocks/handlers/reference-resources.ts";
import { createReferenceResourceHandlers } from "./reference-resource-handlers.ts";
import { createStrictMockServer } from "../../mocks/server.ts";
const runtimeConfig = {
@@ -60,7 +60,7 @@ const createRequests = vi.fn();
const resources = [{ id: "reference-1", name: "Existing" }];
const mockApi = createStrictMockServer(
...createBootstrapHandlers(runtimeConfig, releaseManifest),
...createReferenceScenarioHandlers({
...createReferenceResourceHandlers({
resources,
onList: listRequests,
onCreate: createRequests,
@@ -0,0 +1,57 @@
import { http, HttpResponse } from "msw";
export type ReferenceResourceFixture = Readonly<{
id: string;
name: string;
createdAt?: string;
}>;
const DEFAULT_RESOURCE = Object.freeze({
id: "reference-1",
name: "Reference",
createdAt: "2026-07-26T00:00:00.000Z",
});
/**
* A working reference resource API. Failure scenarios are the platform's HTTP
* scenario catalog (`tests/mocks/scenarios/catalog.ts`), which runs on the
* test contracts; a sample test that needs a failure overrides one route.
*/
export function createReferenceResourceHandlers(
options: Readonly<{
baseUrl?: string;
resources?: ReferenceResourceFixture[];
onList?(search: string): void;
onCreate?(body: Readonly<Record<string, unknown>>): void;
}> = {},
) {
const baseUrl = options.baseUrl ?? "https://api.test";
const resources = options.resources ?? [{ ...DEFAULT_RESOURCE }];
return [
http.get(`${baseUrl}/api/reference-resources`, ({ request }) => {
options.onList?.(new URL(request.url).search);
return HttpResponse.json(resources);
}),
http.post(`${baseUrl}/api/reference-resources`, async ({ request }) => {
const rawBody = await request.json();
const body =
rawBody && typeof rawBody === "object" && !Array.isArray(rawBody)
? (rawBody as Readonly<Record<string, unknown>>)
: {};
options.onCreate?.(body);
const created = {
id: "reference-created",
name: String(body.name ?? "Created"),
createdAt: "2026-07-26T00:00:00.000Z",
};
resources.push(created);
return HttpResponse.json(created);
}),
http.get(`${baseUrl}/api/reference-resources/:resourceId`, ({ params }) =>
HttpResponse.json(
resources.find((entry) => entry.id === params.resourceId) ??
DEFAULT_RESOURCE,
),
),
] as const;
}
+106
View File
@@ -0,0 +1,106 @@
import type {} from "../../../src/application/ports/in/application-api.ts";
import {
createFeatureHttpBinding,
defineFeatureHttpOperationForRoutes,
type FeatureHttpBinding,
type InstalledHttpOperationExecutor,
} from "../../../src/adapters/http/index.ts";
import {
mappingSuccess,
type BoundaryMappingResult,
} from "../../../src/contracts/boundary-mapper.ts";
import {
TEST_CREATE_HTTP_CONTRACT,
TEST_DETAIL_HTTP_CONTRACT,
TEST_LIST_HTTP_CONTRACT,
} from "../../helpers/external-contract-fixture.ts";
/**
* 0929/10-02. A test-only feature for the negative type fixtures of the
* platform's feature APIs (FE-GATE-003), so they keep running after the
* sample feature is removed. Only the fixture tsconfigs compile this file: the
* registry augmentation below never reaches the app or test programs.
*/
export const FIXTURE_FEATURE_ID = "fixture-feature";
export type FixtureEntity = Readonly<{ entityId: string; label: string }>;
export type FixtureFeatureInput = Readonly<{
listEntities(limit: number): Promise<readonly FixtureEntity[]>;
}>;
declare module "../../../src/application/ports/in/application-api.ts" {
interface ApplicationFeatureInputs {
"fixture-feature": FixtureFeatureInput;
}
}
/** The test contract with its operation ID as a literal, as a package declares it. */
function withLiteralOperationId<
const OperationId extends string,
Installed extends Readonly<{ contract: Readonly<{ operationId: string }> }>,
>(operationId: OperationId, installed: Installed) {
return Object.freeze({
...installed,
contract: Object.freeze({ ...installed.contract, operationId }),
});
}
export const TEST_LIST_ENTITIES_CONTRACT = withLiteralOperationId(
"TEST_LIST_ENTITIES",
TEST_LIST_HTTP_CONTRACT,
);
export const TEST_GET_ENTITY_CONTRACT = withLiteralOperationId(
"TEST_GET_ENTITY",
TEST_DETAIL_HTTP_CONTRACT,
);
export const TEST_CREATE_ENTITY_CONTRACT = withLiteralOperationId(
"TEST_CREATE_ENTITY",
TEST_CREATE_HTTP_CONTRACT,
);
export type FixtureRouteId = "FIXTURE_ITEMS" | "FIXTURE_ITEM_STATUS";
type EntityDto = Readonly<{ id: string; name: string }>;
export function mapEntityPayload(dto: EntityDto): BoundaryMappingResult<FixtureEntity> {
return mappingSuccess(Object.freeze({ entityId: dto.id, label: dto.name }));
}
const defineFixtureOperation = defineFeatureHttpOperationForRoutes<FixtureRouteId>();
export const FIXTURE_HTTP_OPERATIONS = Object.freeze({
TEST_LIST_ENTITIES: defineFixtureOperation({
contract: TEST_LIST_ENTITIES_CONTRACT,
routeId: "FIXTURE_ITEMS",
mapSuccess: (payload: readonly EntityDto[]) =>
mappingSuccess(Object.freeze(payload.map((dto) => ({ entityId: dto.id, label: dto.name })))),
}),
TEST_GET_ENTITY: defineFixtureOperation({
contract: TEST_GET_ENTITY_CONTRACT,
routeId: "FIXTURE_ITEM_STATUS",
mapSuccess: mapEntityPayload,
}),
TEST_CREATE_ENTITY: defineFixtureOperation({
contract: TEST_CREATE_ENTITY_CONTRACT,
routeId: "FIXTURE_ITEMS",
mapSuccess: mapEntityPayload,
}),
} as const);
export type FixtureHttpBinding = FeatureHttpBinding<typeof FIXTURE_HTTP_OPERATIONS>;
export function createFixtureFeatureInstalledInput(context: Readonly<{
http: InstalledHttpOperationExecutor;
}>) {
const http = createFeatureHttpBinding(context.http, FIXTURE_HTTP_OPERATIONS);
return Object.freeze({
featureId: FIXTURE_FEATURE_ID,
input: Object.freeze({
async listEntities(limit: number) {
const result = await http.execute("TEST_LIST_ENTITIES", { limit });
return result.ok ? result.value : [];
},
}) satisfies FixtureFeatureInput,
});
}
@@ -1,12 +1,12 @@
import { defineFeatureAdapterContribution } from "../../../src/features/feature-adapter-contribution.ts";
import { createReferenceFeatureInstalledInput } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts";
import { createFixtureFeatureInstalledInput } from "./fixture-feature-contract.ts";
defineFeatureAdapterContribution({
featureId: "reference-feature",
featureId: "fixture-feature",
needs: ["http"] as const,
createInput(context) {
context.indexedDb;
return createReferenceFeatureInstalledInput({
return createFixtureFeatureInstalledInput({
http: context.http,
});
},
@@ -1,14 +1,14 @@
import { defineFeatureAdapterContribution } from "../../../src/features/feature-adapter-contribution.ts";
import type {} from "../../../src/features/reference-feature/application/reference-feature-api.ts";
import type {} from "./fixture-feature-contract.ts";
defineFeatureAdapterContribution({
featureId: "reference-feature",
featureId: "fixture-feature",
needs: ["http"] as const,
createInput() {
return {
featureId: "reference-feature" as const,
featureId: "fixture-feature" as const,
input: {
definitelyNotReferenceFeatureInput: true,
definitelyNotFixtureFeatureInput: true,
},
};
},
+3 -3
View File
@@ -1,8 +1,8 @@
import type { ApplicationApi } from "../../../src/application/ports/in/application-api.ts";
import type { ReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts";
import type { FixtureFeatureInput } from "./fixture-feature-contract.ts";
declare const application: ApplicationApi;
declare const referenceFeature: ReferenceFeatureInput;
declare const fixtureFeature: FixtureFeatureInput;
application.features.get("not-installed");
referenceFeature.listResources;
fixtureFeature.listEntities;
+7 -5
View File
@@ -3,16 +3,18 @@ import {
defineFeatureHttpOperation,
type InstalledHttpOperationExecutor,
} from "../../../src/adapters/http/index.ts";
import { GET_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
import { mapReferenceResourcePayload } from "../../../src/features/reference-feature/contracts/reference-mapper.ts";
import {
mapEntityPayload,
TEST_GET_ENTITY_CONTRACT,
} from "./fixture-feature-contract.ts";
declare const executor: InstalledHttpOperationExecutor;
const operations = Object.freeze({
TOTALLY_WRONG_OPERATION_ID: defineFeatureHttpOperation({
contract: GET_REFERENCE_RESOURCE_CONTRACT,
routeId: "REFERENCE_RESOURCE_DETAIL",
mapSuccess: mapReferenceResourcePayload,
contract: TEST_GET_ENTITY_CONTRACT,
routeId: "FIXTURE_ITEM_STATUS",
mapSuccess: mapEntityPayload,
}),
});
+3 -3
View File
@@ -1,7 +1,7 @@
import type { ReferenceHttpBinding } from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
import type { FixtureHttpBinding } from "./fixture-feature-contract.ts";
declare const http: ReferenceHttpBinding;
declare const http: FixtureHttpBinding;
http.execute("GET_REFERENCE_RESOURCE", {
http.execute("TEST_GET_ENTITY", {
name: "wrong-command-for-get",
});
+9 -9
View File
@@ -1,15 +1,15 @@
import { defineFeatureHttpOperationForRoutes } from "../../../src/adapters/http/index.ts";
import {
type ReferenceFeatureRouteId,
} from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
import { GET_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
import { mapReferenceResourcePayload } from "../../../src/features/reference-feature/contracts/reference-mapper.ts";
mapEntityPayload,
TEST_GET_ENTITY_CONTRACT,
type FixtureRouteId,
} from "./fixture-feature-contract.ts";
const defineReferenceOperation =
defineFeatureHttpOperationForRoutes<ReferenceFeatureRouteId>();
const defineFixtureOperation =
defineFeatureHttpOperationForRoutes<FixtureRouteId>();
defineReferenceOperation({
contract: GET_REFERENCE_RESOURCE_CONTRACT,
defineFixtureOperation({
contract: TEST_GET_ENTITY_CONTRACT,
routeId: "TOTALLY_WRONG_ROUTE",
mapSuccess: mapReferenceResourcePayload,
mapSuccess: mapEntityPayload,
});
+3 -3
View File
@@ -1,9 +1,9 @@
import { defineFeatureHttpOperation } from "../../../src/adapters/http/index.ts";
import { GET_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
import { TEST_GET_ENTITY_CONTRACT } from "./fixture-feature-contract.ts";
defineFeatureHttpOperation({
contract: GET_REFERENCE_RESOURCE_CONTRACT,
routeId: "REFERENCE_RESOURCE_DETAIL",
contract: TEST_GET_ENTITY_CONTRACT,
routeId: "FIXTURE_ITEM_STATUS",
mapSuccess(value: Readonly<{ unrelatedWireField: number }>) {
return {
ok: true as const,
+4 -4
View File
@@ -1,8 +1,8 @@
import type { ReferenceHttpBinding } from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
import type { FixtureHttpBinding } from "./fixture-feature-contract.ts";
declare const http: ReferenceHttpBinding;
declare const http: FixtureHttpBinding;
const listInput = { limit: 20 };
// GET is bound to { resourceId: string }; list input must be rejected.
http.execute("GET_REFERENCE_RESOURCE", listInput);
// GET is bound to { entityId: string }; list input must be rejected.
http.execute("TEST_GET_ENTITY", listInput);
@@ -50,6 +50,7 @@ const problemSchema = z
type: z.string().min(1),
title: z.string().min(1),
status: z.int().min(100).max(599),
code: z.string().min(1).optional(),
})
.strip();
@@ -198,6 +199,35 @@ export const TEST_CREATE_HTTP_CONTRACT: InstalledHttpContract<
}),
});
/**
* The create command as a package that classifies its effects describes it,
* the way the HTTP scenario catalog (`tests/mocks/scenarios/catalog.ts`)
* expects (testing strategy §11.2): 401, 403 and 429 are rejected before any
* state changes, 400, 422 and the declared `409 CONFLICT` are NOT_APPLIED, and
* any other problem (`409 IDEMPOTENT_IN_FLIGHT`, 404, 503) stays MAYBE_APPLIED.
* TEST_CREATE_HTTP_CONTRACT keeps the bare classifier the executor tests
* extend.
*/
export const TEST_CLASSIFIED_CREATE_HTTP_CONTRACT: typeof TEST_CREATE_HTTP_CONTRACT =
Object.freeze({
...TEST_CREATE_HTTP_CONTRACT,
contract: Object.freeze({
...TEST_CREATE_HTTP_CONTRACT.contract,
commandEffect: Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem({
status,
problem,
}: Readonly<{ status: number; problem: TestProblem }>) {
if (status === 400 || status === 422) return "NOT_APPLIED";
if (status === 409 && problem.code === "CONFLICT") return "NOT_APPLIED";
return "MAYBE_APPLIED";
},
classifyStatus: () => "NOT_APPLIED" as const,
}),
}),
});
/**
* An event contract an external package could install. The shared
* contribution below keeps `events` empty, so tests that check event
+19 -30
View File
@@ -12,7 +12,6 @@ import {
type InstalledHttpContract,
} from "../../src/contracts/external-contract-runtime.ts";
import type { CacheScopeSnapshot } from "../../src/contracts/server-state-scope.ts";
import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
import {
computeHttpScenarioCatalogDigest,
httpScenarioReceiptSchema,
@@ -22,9 +21,10 @@ import {
type RetryReason,
} from "../../scripts/lib/http-scenario-evidence.ts";
import { writeValidatedJsonArtifact } from "../../scripts/lib/validated-json-artifact.ts";
import { createReferenceScenarioHandlers } from "../mocks/handlers/reference-resources.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,
@@ -33,12 +33,8 @@ import {
type HttpScenarioOperationId,
} from "../mocks/scenarios/catalog.ts";
/** The reference gateway owns these low-cardinality route identities. */
function routeIdFor(operationId: HttpScenarioOperationId): string {
return operationId === "GET_REFERENCE_RESOURCE"
? "REFERENCE_RESOURCE_DETAIL"
: "REFERENCE_RESOURCE_LIST";
}
/** 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",
@@ -58,18 +54,16 @@ type AttemptTrace = {
};
function operationFor(operationId: HttpScenarioOperationId) {
const operation = REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http.find(
(candidate) => candidate.contract.operationId === operationId,
);
if (!operation) throw new Error(`Missing operation fixture: ${operationId}`);
return operation as InstalledHttpContract<unknown, unknown, unknown>;
return HTTP_SCENARIO_CONTRACTS[operationId] as InstalledHttpContract<
unknown,
unknown,
unknown
>;
}
function inputFor(operationId: HttpScenarioOperationId): unknown {
if (operationId === "LIST_REFERENCE_RESOURCES") return { limit: 20 };
if (operationId === "GET_REFERENCE_RESOURCE") {
return { resourceId: "reference-1" };
}
if (operationId === "TEST_LIST_ENTITIES") return { limit: 20 };
if (operationId === "TEST_GET_ENTITY") return { entityId: "entity-1" };
return { name: "Created" };
}
@@ -231,12 +225,7 @@ async function executeScenario(
const executor = createContractHttpExecutor({
baseUrl: "https://api.test",
maxRetryAttempts: 2,
// The reference contribution declares EXTERNAL_BEARER, so the
// credential owner must supply the required proof header before dispatch.
attachCredentials: () => ({
kind: "READY",
headers: { authorization: "Bearer scenario-token" },
}),
attachCredentials: () => ({ kind: "READY", headers: {} }),
fetcher,
random: () => 0,
readBoundedResponseBytes: async (response, maximumBytes) => {
@@ -257,7 +246,7 @@ async function executeScenario(
});
mockApi.server.use(
...createReferenceScenarioHandlers({
...createTestEntityScenarioHandlers({
scenarios: { [entry.operationId]: entry.scenarioId },
onAttempt(attempt) {
if (
@@ -272,10 +261,10 @@ async function executeScenario(
try {
const execution = executor.execute(operation, inputFor(entry.operationId), {
routeId: routeIdFor(entry.operationId),
routeId: ROUTE_ID,
scope,
signal: caller.signal,
...(entry.operationId === "CREATE_REFERENCE_RESOURCE"
...(entry.operationId === "TEST_CREATE_ENTITY"
? {
intent: Object.freeze({
intentId: `intent-${entry.scenarioId}`,
@@ -291,7 +280,7 @@ async function executeScenario(
if (entry.scenarioId === "timeout" || entry.scenarioId === "aborted") {
await waitForHandler(ready, entry.executionId);
if (entry.scenarioId === "aborted") {
if (entry.operationId === "LIST_REFERENCE_RESOURCES") {
if (entry.operationId === "TEST_LIST_ENTITIES") {
caller.abort();
} else {
scopeCurrent = false;
@@ -367,9 +356,9 @@ describe("HTTP scenario catalog execution evidence", () => {
scenarioIds.map((scenarioId) => `${operationId}::${scenarioId}`),
);
expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(20);
expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(19);
expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(18);
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);
-231
View File
@@ -1,231 +0,0 @@
import { delay, http, HttpResponse, type JsonBodyType } from "msw";
import type {
HttpScenarioId,
HttpScenarioOperationId,
} from "../scenarios/catalog.ts";
import { assertOperationScenario } from "../scenarios/catalog.ts";
export type ReferenceResourceFixture = Readonly<{
id: string;
name: string;
createdAt?: string;
}>;
type ScenarioOptions = Readonly<{
baseUrl?: string;
scenarios?: Partial<
Record<
| "LIST_REFERENCE_RESOURCES"
| "CREATE_REFERENCE_RESOURCE"
| "GET_REFERENCE_RESOURCE",
HttpScenarioId
>
>;
resources?: ReferenceResourceFixture[];
onAttempt?(attempt: Readonly<{
operationId: HttpScenarioOperationId;
scenarioId: HttpScenarioId;
attempt: number;
}>): void;
onList?(search: string): void;
onCreate?(body: Readonly<Record<string, unknown>>): void;
}>;
const DEFAULT_RESOURCE = Object.freeze({
id: "reference-1",
name: "Reference",
createdAt: "2026-07-26T00:00:00.000Z",
});
async function scenarioResponse(
operationId: HttpScenarioOperationId,
scenario: HttpScenarioId,
payload: JsonBodyType,
attempt: number,
) {
if (scenario === "slow") await delay(50);
if (scenario === "timeout" || scenario === "aborted") {
await delay("infinite");
}
if (scenario === "network-error") return HttpResponse.error();
if (scenario === "content-type-mismatch") {
return new HttpResponse("<html>not json</html>", {
headers: { "Content-Type": "text/html" },
});
}
if (scenario === "malformed-json") {
return new HttpResponse("{invalid", {
headers: { "Content-Type": "application/json" },
});
}
if (scenario === "envelope-mismatch") {
return HttpResponse.json({ data: payload });
}
if (scenario === "schema-mismatch") {
return HttpResponse.json({ unexpected: true });
}
if (
scenario === "unauthenticated-401"
) {
return HttpResponse.json(problem(401, "AUTH_REQUIRED"), {
status: 401,
});
}
if (scenario === "forbidden-403") {
return HttpResponse.json(problem(403, "FORBIDDEN"), { status: 403 });
}
if (scenario === "not-found-404") {
return HttpResponse.json(problem(404, "NOT_FOUND"), { status: 404 });
}
if (scenario === "conflict-409") {
return HttpResponse.json(problem(409, "CONFLICT"), { status: 409 });
}
if (scenario === "in-flight-409") {
return HttpResponse.json(problem(409, "IDEMPOTENT_IN_FLIGHT"), {
status: 409,
});
}
if (scenario === "validation-422") {
return HttpResponse.json(
problem(422, "VALIDATION_REJECTED"),
{ status: 422 },
);
}
if (scenario === "rate-limited-429") {
return HttpResponse.json(problem(429, "RATE_LIMITED"), {
status: 429,
headers: { "Retry-After": "1" },
});
}
if (
scenario === "server-terminal-503" ||
(scenario === "server-retry-success" && attempt === 1)
) {
return HttpResponse.json(problem(503, "SERVER_FAILURE"), {
status: 503,
});
}
if (scenario === "response-too-large") {
const ceiling =
operationId === "LIST_REFERENCE_RESOURCES" ? 262_144 : 32_768;
const bytes = new Uint8Array(ceiling + 1).fill(0x20);
bytes[0] = 0x5b;
bytes[bytes.length - 1] = 0x5d;
return new HttpResponse(
new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(bytes);
controller.close();
},
}),
{
headers: {
"Content-Type": "application/json",
"Content-Length": String(bytes.byteLength),
},
},
);
}
return HttpResponse.json(payload);
}
function problem(status: number, code: string) {
return Object.freeze({
type: `https://api.test/problems/${code.toLowerCase()}`,
title: code,
status,
code,
});
}
export function createReferenceScenarioHandlers(options: ScenarioOptions = {}) {
const baseUrl = options.baseUrl ?? "https://api.test";
const resources = options.resources ?? [{ ...DEFAULT_RESOURCE }];
const attempts = new Map<string, number>();
const scenarioFor = (
operationId: keyof NonNullable<ScenarioOptions["scenarios"]>,
) =>
assertOperationScenario(
operationId,
options.scenarios?.[operationId] ?? "success",
);
const nextAttempt = (operationId: string) => {
const next = (attempts.get(operationId) ?? 0) + 1;
attempts.set(operationId, next);
return next;
};
return [
http.get(`${baseUrl}/api/reference-resources`, ({ request }) => {
options.onList?.(new URL(request.url).search);
const scenario = scenarioFor("LIST_REFERENCE_RESOURCES");
const payload = scenario === "empty" ? [] : resources;
const attempt = nextAttempt("LIST_REFERENCE_RESOURCES");
options.onAttempt?.({
operationId: "LIST_REFERENCE_RESOURCES",
scenarioId: scenario,
attempt,
});
return scenarioResponse(
"LIST_REFERENCE_RESOURCES",
scenario,
payload,
attempt,
);
}),
http.post(
`${baseUrl}/api/reference-resources`,
async ({ request }) => {
const rawBody = await request.json();
const body =
rawBody &&
typeof rawBody === "object" &&
!Array.isArray(rawBody)
? (rawBody as Readonly<Record<string, unknown>>)
: {};
options.onCreate?.(body);
const scenario = scenarioFor("CREATE_REFERENCE_RESOURCE");
const created = {
id: "reference-created",
name: String(body.name ?? "Created"),
createdAt: "2026-07-26T00:00:00.000Z",
};
if (scenario === "success") resources.push(created);
const attempt = nextAttempt("CREATE_REFERENCE_RESOURCE");
options.onAttempt?.({
operationId: "CREATE_REFERENCE_RESOURCE",
scenarioId: scenario,
attempt,
});
return scenarioResponse(
"CREATE_REFERENCE_RESOURCE",
scenario,
created,
attempt,
);
},
),
http.get(
`${baseUrl}/api/reference-resources/:resourceId`,
({ params }) => {
const scenario = scenarioFor("GET_REFERENCE_RESOURCE");
const resource =
resources.find((entry) => entry.id === params.resourceId) ??
DEFAULT_RESOURCE;
const attempt = nextAttempt("GET_REFERENCE_RESOURCE");
options.onAttempt?.({
operationId: "GET_REFERENCE_RESOURCE",
scenarioId: scenario,
attempt,
});
return scenarioResponse(
"GET_REFERENCE_RESOURCE",
scenario,
resource,
attempt,
);
},
),
] as const;
}
+159
View File
@@ -0,0 +1,159 @@
import { delay, http, HttpResponse, type JsonBodyType } from "msw";
import {
assertOperationScenario,
httpScenarioOperationFacts,
HTTP_SCENARIO_ENTITY,
type HttpScenarioId,
type HttpScenarioOperationId,
} from "../scenarios/catalog.ts";
/**
* MSW handlers for the test contracts in `tests/helpers/external-contract-fixture.ts`
* (`/api/test-entities`). Each operation answers the catalog scenario the test
* selects; a scenario the catalog does not declare for that operation throws.
*/
type ScenarioOptions = Readonly<{
baseUrl?: string;
scenarios?: Partial<Record<HttpScenarioOperationId, HttpScenarioId>>;
onAttempt?(attempt: Readonly<{
operationId: HttpScenarioOperationId;
scenarioId: HttpScenarioId;
attempt: number;
}>): void;
}>;
async function scenarioResponse(
operationId: HttpScenarioOperationId,
scenario: HttpScenarioId,
payload: JsonBodyType,
attempt: number,
) {
const { ceiling, successStatus } = httpScenarioOperationFacts(operationId);
if (scenario === "slow") await delay(50);
if (scenario === "timeout" || scenario === "aborted") {
await delay("infinite");
}
if (scenario === "network-error") return HttpResponse.error();
if (scenario === "content-type-mismatch") {
return new HttpResponse("<html>not json</html>", {
status: successStatus,
headers: { "Content-Type": "text/html" },
});
}
if (scenario === "malformed-json") {
return new HttpResponse("{invalid", {
status: successStatus,
headers: { "Content-Type": "application/json" },
});
}
if (scenario === "envelope-mismatch") {
return HttpResponse.json({ data: payload }, { status: successStatus });
}
if (scenario === "schema-mismatch") {
return HttpResponse.json({ unexpected: true }, { status: successStatus });
}
if (scenario === "unauthenticated-401") {
return HttpResponse.json(problem(401, "AUTH_REQUIRED"), { status: 401 });
}
if (scenario === "forbidden-403") {
return HttpResponse.json(problem(403, "FORBIDDEN"), { status: 403 });
}
if (scenario === "not-found-404") {
return HttpResponse.json(problem(404, "NOT_FOUND"), { status: 404 });
}
if (scenario === "conflict-409") {
return HttpResponse.json(problem(409, "CONFLICT"), { status: 409 });
}
if (scenario === "in-flight-409") {
return HttpResponse.json(problem(409, "IDEMPOTENT_IN_FLIGHT"), {
status: 409,
});
}
if (scenario === "validation-422") {
return HttpResponse.json(problem(422, "VALIDATION_REJECTED"), {
status: 422,
});
}
if (scenario === "rate-limited-429") {
return HttpResponse.json(problem(429, "RATE_LIMITED"), {
status: 429,
headers: { "Retry-After": "1" },
});
}
if (
scenario === "server-terminal-503" ||
(scenario === "server-retry-success" && attempt === 1)
) {
return HttpResponse.json(problem(503, "SERVER_FAILURE"), { status: 503 });
}
if (scenario === "response-too-large") {
const bytes = new Uint8Array(ceiling + 1).fill(0x20);
bytes[0] = 0x5b;
bytes[bytes.length - 1] = 0x5d;
return new HttpResponse(
new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(bytes);
controller.close();
},
}),
{
status: successStatus,
headers: {
"Content-Type": "application/json",
"Content-Length": String(bytes.byteLength),
},
},
);
}
return HttpResponse.json(payload, { status: successStatus });
}
function problem(status: number, code: string) {
return Object.freeze({
type: `https://api.test/problems/${code.toLowerCase()}`,
title: code,
status,
code,
});
}
export function createTestEntityScenarioHandlers(options: ScenarioOptions = {}) {
const baseUrl = options.baseUrl ?? "https://api.test";
const attempts = new Map<HttpScenarioOperationId, number>();
const answer = (operationId: HttpScenarioOperationId, payload: JsonBodyType) => {
const scenarioId = assertOperationScenario(
operationId,
options.scenarios?.[operationId] ?? "success",
);
const attempt = (attempts.get(operationId) ?? 0) + 1;
attempts.set(operationId, attempt);
options.onAttempt?.({ operationId, scenarioId, attempt });
return scenarioResponse(
operationId,
scenarioId,
scenarioId === "empty" ? [] : payload,
attempt,
);
};
return [
http.get(`${baseUrl}/api/test-entities`, () =>
answer("TEST_LIST_ENTITIES", [{ ...HTTP_SCENARIO_ENTITY }]),
),
http.post(`${baseUrl}/api/test-entities`, async ({ request }) => {
const body = (await request.json()) as Readonly<Record<string, unknown>>;
return answer("TEST_CREATE_ENTITY", {
id: "entity-created",
name: String(body.name ?? "Created"),
});
}),
http.get(`${baseUrl}/api/test-entities/:entityId`, ({ params }) =>
answer("TEST_GET_ENTITY", {
...HTTP_SCENARIO_ENTITY,
id: String(params.entityId),
}),
),
] as const;
}
+53 -31
View File
@@ -11,6 +11,11 @@ export type {
HttpScenarioAssertionGroups,
RetryReason,
} from "../../../scripts/lib/http-scenario-evidence.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;
@@ -39,14 +44,31 @@ export const HTTP_SCENARIO_IDS = Object.freeze([
export type HttpScenarioId = (typeof HTTP_SCENARIO_IDS)[number];
export const HTTP_SCENARIO_OPERATION_IDS = Object.freeze([
"LIST_REFERENCE_RESOURCES",
"GET_REFERENCE_RESOURCE",
"CREATE_REFERENCE_RESOURCE",
] as const);
/**
* 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,
});
export type HttpScenarioOperationId = keyof typeof HTTP_SCENARIO_CONTRACTS;
export const HTTP_SCENARIO_OPERATION_IDS = Object.freeze(
Object.keys(HTTP_SCENARIO_CONTRACTS) as HttpScenarioOperationId[],
);
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 HttpScenarioOperationId =
(typeof HTTP_SCENARIO_OPERATION_IDS)[number];
export type HttpScenarioExecutionId =
`${HttpScenarioOperationId}::${HttpScenarioId}`;
@@ -61,29 +83,28 @@ export type HttpScenarioExpectation = Readonly<{
const encoder = new TextEncoder();
const jsonBytes = (value: unknown) => encoder.encode(JSON.stringify(value)).byteLength;
const RESOURCE = Object.freeze({
id: "reference-1",
name: "Reference",
createdAt: "2026-07-26T00:00:00.000Z",
export const HTTP_SCENARIO_ENTITY = Object.freeze({
id: "entity-1",
name: "Entity",
});
const CREATED = Object.freeze({
id: "reference-created",
export const HTTP_SCENARIO_CREATED_ENTITY = Object.freeze({
id: "entity-created",
name: "Created",
createdAt: "2026-07-26T00:00:00.000Z",
});
function operationFacts(operationId: HttpScenarioOperationId) {
const command = operationId === "CREATE_REFERENCE_RESOURCE";
/** What a scenario's answer depends on, from the operation's contract. */
export function httpScenarioOperationFacts(operationId: HttpScenarioOperationId) {
const installed = HTTP_SCENARIO_CONTRACTS[operationId];
return Object.freeze({
command,
ceiling:
operationId === "LIST_REFERENCE_RESOURCES" ? 262_144 : 32_768,
command: installed.contract.commandEffect !== null,
ceiling: installed.frontend.responseByteLimit,
successStatus: installed.contract.acceptedStatuses[0]!,
payload:
operationId === "LIST_REFERENCE_RESOURCES"
? [RESOURCE]
: operationId === "GET_REFERENCE_RESOURCE"
? RESOURCE
: CREATED,
operationId === "TEST_LIST_ENTITIES"
? [HTTP_SCENARIO_ENTITY]
: operationId === "TEST_GET_ENTITY"
? HTTP_SCENARIO_ENTITY
: HTTP_SCENARIO_CREATED_ENTITY,
});
}
@@ -108,8 +129,9 @@ function expectationFor(
operationId: HttpScenarioOperationId,
scenarioId: HttpScenarioId,
): HttpScenarioExpectation {
const { command, ceiling, payload } = operationFacts(operationId);
let statuses: AttemptStatus[] = [200];
const { command, ceiling, successStatus, payload } =
httpScenarioOperationFacts(operationId);
let statuses: AttemptStatus[] = [successStatus];
let kind = "SUCCESS";
let detail: string | null = null;
let outcomeEffect = command ? "APPLIED_CONFIRMED" : "NOT_APPLICABLE";
@@ -159,7 +181,7 @@ function expectationFor(
statuses = ["PENDING_ABORT"];
media = [null];
bodies = [attemptBody("NO_RESPONSE", 0, 0)];
if (operationId === "LIST_REFERENCE_RESOURCES") {
if (operationId === "TEST_LIST_ENTITIES") {
kind = "CANCELLED";
outcomeEffect = "NOT_STARTED";
observer = "CANCELLED";
@@ -329,7 +351,7 @@ function expectationFor(
),
];
} else {
statuses = [503, 200];
statuses = [503, successStatus];
retryReasons = ["HTTP_503"];
media = ["application/json", "application/json"];
bodies = [
@@ -400,11 +422,11 @@ function expectationFor(
}
const OPERATION_SCENARIOS = Object.freeze({
LIST_REFERENCE_RESOURCES: HTTP_SCENARIO_IDS,
GET_REFERENCE_RESOURCE: Object.freeze(
TEST_LIST_ENTITIES: HTTP_SCENARIO_IDS,
TEST_GET_ENTITY: Object.freeze(
HTTP_SCENARIO_IDS.filter((scenario) => scenario !== "empty"),
),
CREATE_REFERENCE_RESOURCE: Object.freeze(
TEST_CREATE_ENTITY: Object.freeze(
HTTP_SCENARIO_IDS.filter(
(scenario) => scenario !== "empty" && scenario !== "aborted",
),