Files
clean-architecture-frontend…/tests/runtime-schema/release-manifest.test.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

250 lines
6.8 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
loadReleaseManifest,
ReleaseManifestError,
} from "../../src/bootstrap/load-release-manifest.ts";
import { computeContractSetDigest } from "../../src/contracts/contract-set-canonical.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../../src/features/installed-contract-contributions.ts";
const EMPTY_SET_DIGEST = await computeContractSetDigest([]);
// 16-02. The build compiles the installed features' packages, so a coherent
// manifest carries exactly that set, whatever is installed.
const INSTALLED_SET_DIGEST = await computeContractSetDigest(
EXPECTED_CONTRACT_SET_PACKAGES,
);
const runtime: Parameters<typeof loadReleaseManifest>[0] = {
build: {
buildId: "build-a",
commitSha: "abc123",
routerBasePath: "/",
runtimeConfigUrl: "/config.json",
},
config: {
APP_ENV: "local",
API_BASE_URL: "https://api.test",
REQUEST_TIMEOUT_MS: 10_000,
MAX_RETRY_ATTEMPTS: 2,
TELEMETRY_ENABLED: false,
AUTH_MODE: "external",
RELEASE_MANIFEST_URL: "/release-manifest.json",
BUILD_ID: "build-a",
RELEASE_ID: "release-a",
CONFIG_SCHEMA_VERSION: "2.0",
CAPABILITY_OVERRIDES: {
REALTIME: "DEFAULT",
WEB_WORKER: "DEFAULT",
SERVICE_WORKER: "DEFAULT",
OFFLINE_COMMANDS: "DEFAULT",
},
FEATURE_OVERRIDES: {},
},
configSchema: "V2",
validationDurationMs: 0,
};
const manifest = {
schemaVersion: 2,
appVersion: "0.1.0",
buildId: "build-a",
commitSha: "abc123",
configSchemaVersion: "2.0",
assetManifestHash: "hash-a",
releaseId: "release-a",
builtAt: "2026-07-25T00:00:00Z",
routeChunks: { "route-home": "assets/home.js" },
contractSet: {
setAlgorithm: "CA_CONTRACT_SET_V1",
setDigest: INSTALLED_SET_DIGEST,
packages: EXPECTED_CONTRACT_SET_PACKAGES,
},
};
const runtimeV1: Parameters<typeof loadReleaseManifest>[0] = {
...runtime,
config: {
...runtime.config,
CONFIG_SCHEMA_VERSION: "1",
LEGACY_API_CONTRACT_VERSION: "1",
},
configSchema: "V1",
};
const manifestV1 = {
schemaVersion: 1,
appVersion: "0.1.0",
buildId: "build-a",
commitSha: "abc123",
configSchemaVersion: "1",
apiContractVersion: "1",
assetManifestHash: "hash-a",
releaseId: "release-a",
builtAt: "2026-07-25T00:00:00Z",
routeChunks: { "route-home": "assets/home.js" },
};
function jsonResponse(body: unknown): Response {
return new Response(JSON.stringify(body), {
headers: { "content-type": "application/json" },
});
}
describe("release manifest boot boundary", () => {
it("loads a coherent release tuple", async () => {
await expect(
loadReleaseManifest(
runtime,
{ fetcher: async () => jsonResponse(manifest) },
),
).resolves.toMatchObject({ releaseId: "release-a" });
});
it("fails before mount when release and runtime differ", async () => {
await expect(
loadReleaseManifest(
runtime,
{
fetcher: async () =>
jsonResponse({ ...manifest, buildId: "build-b" }),
},
),
).rejects.toMatchObject({
kind: "BUILD_MISMATCH",
code: "MANIFEST_BUILD_MISMATCH",
});
});
it.each([
[
{ releaseId: "release-b" },
{},
"RELEASE_MISMATCH",
"MANIFEST_RELEASE_MISMATCH",
],
[
{},
{ expectedAssetManifestHash: "different" },
"ASSET_MISMATCH",
"MANIFEST_ASSET_MISMATCH",
],
])(
"classifies tuple mismatch %# without a generic deploy error",
async (manifestOverride, options, kind, code) => {
await expect(
loadReleaseManifest(
runtime,
{
fetcher: async () =>
jsonResponse({ ...manifest, ...manifestOverride }),
...options,
},
),
).rejects.toMatchObject({ kind, code });
},
);
it.each(["3.0", "9.0"])(
"rejects unsupported V2 manifest config version %s at the schema boundary",
async (configSchemaVersion) => {
await expect(
loadReleaseManifest(runtime, {
fetcher: async () =>
jsonResponse({ ...manifest, configSchemaVersion }),
}),
).rejects.toMatchObject({
kind: "RELEASE_MANIFEST_FAILURE",
code: "MANIFEST_SCHEMA_INVALID",
});
},
);
it("rejects a contract set the build did not compile", async () => {
await expect(
loadReleaseManifest(runtime, {
fetcher: async () =>
jsonResponse({
...manifest,
contractSet: {
setAlgorithm: "CA_CONTRACT_SET_V1",
setDigest: EMPTY_SET_DIGEST,
packages: [
{
packageId: "@org-contracts/worklog",
version: "1.2.3",
digest: `sha256:${"a".repeat(64)}`,
runtimeProtocolVersion: 1,
sourceRevision: "abc1234",
},
],
},
}),
}),
).rejects.toMatchObject({
kind: "CONTRACT_SET_MISMATCH",
code: "CONTRACT_SET_PACKAGE_UNEXPECTED",
});
});
it("still reads a V1 manifest during the compatibility window", async () => {
await expect(
loadReleaseManifest(
runtimeV1,
{
fetcher: async () => jsonResponse(manifestV1),
},
),
).resolves.toMatchObject({ schemaVersion: 1, contractSet: null });
});
it("rejects a V2 runtime paired with a V1 manifest", async () => {
await expect(
loadReleaseManifest(runtime, {
fetcher: async () => jsonResponse({
...manifestV1,
configSchemaVersion: "2.0",
}),
}),
).rejects.toMatchObject({
kind: "PROTOCOL_PAIR_MISMATCH",
code: "MANIFEST_PROTOCOL_PAIR_MISMATCH",
});
});
it("rejects a V1 runtime paired with a V2 manifest", async () => {
await expect(
loadReleaseManifest(runtimeV1, {
fetcher: async () => jsonResponse(manifest),
}),
).rejects.toMatchObject({
kind: "PROTOCOL_PAIR_MISMATCH",
code: "MANIFEST_PROTOCOL_PAIR_MISMATCH",
});
});
it("requires matching legacy scalar versions for a V1 pair", async () => {
await expect(
loadReleaseManifest(runtimeV1, {
fetcher: async () => jsonResponse({
...manifestV1,
apiContractVersion: "2",
}),
}),
).rejects.toMatchObject({
kind: "API_CONTRACT_MISMATCH",
code: "MANIFEST_API_CONTRACT_MISMATCH",
});
});
it("rejects a manifest without a complete route chunk map", async () => {
const malformed = Object.fromEntries(
Object.entries(manifest).filter(([key]) => key !== "routeChunks"),
);
await expect(
loadReleaseManifest(
runtime,
{ fetcher: async () => jsonResponse(malformed) },
),
).rejects.toBeInstanceOf(ReleaseManifestError);
});
});