Files
clean-architecture-frontend…/tests/unit/http-scenario-evidence.test.ts
DongHyeonka 91962e24e3 test(setup): 자식 프로세스를 띄우는 시험이 잰 시간으로 timeout을 정한다
자식 프로세스를 띄우는 Vitest 시험 91개(24파일)가 기본 timeout 10초에
기대고 있었다. 셋은 FE-GATE-013에서만 도는 tests/system 시험이다.
기본값은 프로세스 안에서 도는 시험에 맞춘 값이다. 부하가 높은
desktop에서는 자식 프로세스 시험이 평소보다 크게 느려진다.
FE-GATE-020 drill 사본에서 평소 0.4~1.2초인 문서 시험이 10.6초 걸려
실패했다(2026-11-12). 가장 위험한 것은 tests/architecture/app-build-input
.test.ts로, desktop에서 이미 5.7초까지 걸렸다.

무엇을 고칠지는 desktop 계측으로 정했다.
- test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. 시험마다
  띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은
  JSON reporter로 받았다.
- 시험마다 실제 timeout은 task.timeout으로 기록했다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. tests/system은
  그 묶음에 없어서, 아래 검사가 잡은 셋을 따로 세 번 쟀다.

고친 것:
- tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대
  ms>)는 그 15배를 30초 단위로 올린 값이다. 15배는 위 0.7초 → 10.6초에서
  왔다. 시험마다 자기가 잰 최대값을 인자로 적어 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에,
  일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게
  잡지 않으려는 것이다.
- tests/setup.ts가 child_process 함수를 감싼다. 기본 timeout인 시험이
  자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
  helper나 시험이 import한 스크립트가 띄워도 잡는다. util.promisify가
  읽는 속성은 원래 함수에서 옮긴다.
- docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.

버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않고, 이미 있는 값도
  60_000·120_000처럼 근거가 없었다.
- 자식 프로세스를 띄우지 않게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는
  것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와
  같은 파일의 다른 시험을 놓친다.

위험:
- hook(beforeAll 등)에서 띄우는 프로세스는 검사하지 않는다. 계측에서
  hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의
  timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- 다운스트림 시험이 기본값으로 자식 프로세스를 띄우면 test:unit 등이
  실패한다. 메시지가 helper를 알린다.

검증(desktop):
- 다섯 검사(test:unit·check:types·check:ci·lint·verify:documentation)
  rc=0.
- 자식 프로세스를 띄우는 시험 파일 40개와 tests/scale: rc=0, 검사 위반 0.
- tests/system: 115개 중 18개 실패. 모두 bwrap 호스트 제약이고 검사
  위반은 0이다.
- 변이: 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
  tracked-artifacts describe의 timeout을 지우면 그 시험이 검사 메시지로
  실패한다.
- 재현: CPU 10% 제한에서 app-build-input·registry-governance·hosting-probe
  ·design-system-rules를 돌렸다. main 650d22fa는 11개가 10초 timeout으로
  실패했다. 이 커밋은 71개 모두 통과했고, 가장 긴 시험은 17.7초였다.
2026-11-12 11:22:59 +09:00

362 lines
11 KiB
TypeScript

import { spawnSync } from "node:child_process";
import {
mkdir,
mkdtemp,
readFile,
rm,
writeFile,
} from "node:fs/promises";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
createBoundedChildInvocation,
createBoundedPnpmScriptInvocation,
formatPnpmScriptFailure,
} from "../../scripts/lib/bounded-pnpm-script.ts";
import {
computeHttpScenarioCatalogDigest,
httpScenarioExpectationSchema,
httpScenarioReceiptSchema,
type HttpScenarioAssertionGroups,
type HttpScenarioExpectation,
} from "../../scripts/lib/http-scenario-evidence.ts";
import { childProcessTimeout } from "../helpers/child-process-timeout.ts";
type MutableReceipt = {
schemaVersion: number;
catalogDigest: string;
catalogTotal: number;
executedIds: string[];
rows: Array<{
executionId: string;
expected: HttpScenarioAssertionGroups;
observed: HttpScenarioAssertionGroups;
testDeadlineOverrideMs: number | null;
}>;
};
const temporaryDirectories: string[] = [];
afterEach(async () => {
await Promise.all(
temporaryDirectories.splice(0).map((directory) =>
rm(directory, { recursive: true, force: true }),
),
);
});
async function validFixture() {
const source = JSON.parse(
await readFile(
"tests/fixtures/test-evidence/scenarios/catalog.json",
"utf8",
),
) as Readonly<Record<string, unknown>>;
const expectations = httpScenarioExpectationSchema
.array()
.parse(source.HTTP_SCENARIO_EXPECTATIONS) as HttpScenarioExpectation[];
const rows = expectations
.map((entry) => ({
executionId: entry.executionId,
expected: structuredClone(entry.expected),
observed: structuredClone(entry.expected),
testDeadlineOverrideMs: entry.testDeadlineOverrideMs,
}))
.sort((left, right) => left.executionId.localeCompare(right.executionId));
const receipt: MutableReceipt = {
schemaVersion: 1,
catalogDigest: computeHttpScenarioCatalogDigest(1, expectations),
catalogTotal: expectations.length,
executedIds: rows.map((row) => row.executionId),
rows,
};
return { expectations, receipt };
}
async function runFixture(
expectations: readonly HttpScenarioExpectation[],
receipt: MutableReceipt,
) {
await mkdir(".tmp", { recursive: true });
const directory = await mkdtemp(path.resolve(".tmp/http-scenario-evidence-"));
temporaryDirectories.push(directory);
const sourceRoot = path.join(directory, "source");
const catalogPath = path.join(directory, "catalog.json");
const receiptPath = path.join(directory, "receipt.json");
const policyPath = path.join(directory, "policy.json");
const artifactPath = path.join(directory, "report.json");
await mkdir(sourceRoot);
await writeFile(
catalogPath,
`${JSON.stringify({ HTTP_SCENARIO_EXPECTATIONS: expectations }, null, 2)}\n`,
);
await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
await writeFile(
policyPath,
`${JSON.stringify(
{
schemaVersion: 2,
scenarioCatalogs: [
{
owner: "mutation-fixture",
path: catalogPath,
expectationExport: "HTTP_SCENARIO_EXPECTATIONS",
receiptPath,
receiptSchemaVersion: 1,
},
],
sourceContracts: [],
},
null,
2,
)}\n`,
);
const invocation = createBoundedChildInvocation({
command: process.execPath,
arguments: [
"scripts/check-test-evidence.ts",
"--scenario-only",
"--source-root",
sourceRoot,
"--policy",
policyPath,
"--catalog",
catalogPath,
"--receipt",
receiptPath,
"--artifact",
artifactPath,
],
environment: process.env,
cwd: process.cwd(),
});
return spawnSync(
invocation.command,
[...invocation.arguments],
invocation.options,
);
}
describe("HTTP scenario evidence receipt schema", () => {
it("bounds checker fixture children with the shared process policy", () => {
const environment = { CI: "true" };
expect(
createBoundedChildInvocation({
command: "/runtime/node",
arguments: ["scripts/check-test-evidence.ts", "--scenario-only"],
environment,
cwd: "/workspace",
}),
).toEqual({
command: "/runtime/node",
arguments: ["scripts/check-test-evidence.ts", "--scenario-only"],
options: {
cwd: "/workspace",
encoding: "utf8",
env: environment,
killSignal: "SIGTERM",
maxBuffer: 16 * 1024 * 1024,
timeout: 60_000,
},
});
});
it("bounds every orchestration child by time and captured output", () => {
const environment = { CI: "true" };
expect(
createBoundedPnpmScriptInvocation({
nodePath: "/runtime/node",
pnpmCli: "/runtime/pnpm.cjs",
script: "test:http-scenario-catalog",
environment,
}),
).toEqual({
command: "/runtime/node",
arguments: [
"/runtime/pnpm.cjs",
"run",
"test:http-scenario-catalog",
],
options: {
encoding: "utf8",
env: environment,
killSignal: "SIGTERM",
maxBuffer: 16 * 1024 * 1024,
timeout: 60_000,
},
});
});
it("preserves timeout code and termination signal in child diagnostics", () => {
const error = Object.assign(new Error("spawn timed out"), {
code: "ETIMEDOUT",
});
expect(
formatPnpmScriptFailure("test:http-scenario-catalog", {
status: null,
signal: "SIGTERM",
error,
}),
).toBe(
"test:http-scenario-catalog failed: exit=null, signal=SIGTERM, error=ETIMEDOUT: spawn timed out",
);
});
it("preserves output overflow codes in child diagnostics", () => {
const error = Object.assign(new Error("stdout maxBuffer exceeded"), {
code: "ENOBUFS",
});
expect(
formatPnpmScriptFailure("check:http-scenario-evidence", {
status: null,
signal: null,
error,
}),
).toBe(
"check:http-scenario-evidence failed: exit=null, signal=none, error=ENOBUFS: stdout maxBuffer exceeded",
);
});
it("rejects internally inconsistent assertion groups as schema drift", async () => {
const receipt = JSON.parse(
await readFile(
"tests/fixtures/test-evidence/scenarios/receipt-semantic-invalid.json",
"utf8",
),
);
const result = httpScenarioReceiptSchema.safeParse(receipt);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.issues).toEqual(
expect.arrayContaining([
expect.objectContaining({
path: ["rows", 0, "expected", "fetch", "agrees"],
}),
expect.objectContaining({
path: ["rows", 0, "observed", "fetch", "agrees"],
}),
expect.objectContaining({
path: ["rows", 0, "expected", "retry", "count"],
}),
expect.objectContaining({
path: ["rows", 0, "expected", "retry", "reasons", 0],
}),
expect.objectContaining({
path: ["rows", 0, "observed", "retry", "count"],
}),
expect.objectContaining({
path: ["rows", 0, "observed", "retry", "reasons", 0],
}),
]),
);
}
});
it.each([
{
label: "zero declarations and executions",
diagnostic: "[TEST-EVIDENCE-CATALOG-ZERO]",
mutate(expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
expectations.splice(0);
receipt.catalogTotal = 0;
receipt.executedIds.splice(0);
receipt.rows.splice(0);
},
},
{
label: "a missing execution",
diagnostic: "[TEST-EVIDENCE-EXECUTION-ID-MISSING]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.executedIds.pop();
receipt.rows.pop();
},
},
{
label: "an extra execution",
diagnostic: "[TEST-EVIDENCE-EXECUTION-ID-EXTRA]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
const extra = structuredClone(receipt.rows.at(-1)!);
extra.executionId = "FIXTURE_OPERATION::zz-extra";
receipt.executedIds.push(extra.executionId);
receipt.rows.push(extra);
},
},
{
label: "a duplicate execution",
diagnostic: "[TEST-EVIDENCE-EXECUTION-ID-DUPLICATE]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.executedIds.splice(1, 0, receipt.executedIds[0]!);
receipt.rows.splice(1, 0, structuredClone(receipt.rows[0]!));
},
},
{
label: "digest drift",
diagnostic: "[TEST-EVIDENCE-CATALOG-DIGEST]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.catalogDigest = `sha256:${"0".repeat(64)}`;
},
preserveDigest: true,
},
{
label: "unsorted execution rows",
diagnostic: "[TEST-EVIDENCE-EXECUTION-ID-UNSORTED]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.executedIds.reverse();
receipt.rows.reverse();
},
},
{
label: "expected value drift",
diagnostic: "[TEST-EVIDENCE-EXPECTED-DRIFT]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
const changed = {
...receipt.rows[0]!.expected,
outcome: { kind: "FORBIDDEN", detail: null },
};
receipt.rows[0]!.expected = changed;
receipt.rows[0]!.observed = structuredClone(changed);
},
},
{
label: "observed value mismatch",
diagnostic: "[TEST-EVIDENCE-OBSERVATION-MISMATCH]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.rows[0]!.observed = {
...receipt.rows[0]!.observed,
outcome: { kind: "FORBIDDEN", detail: null },
};
},
},
{
label: "a deadline override drift",
diagnostic: "[TEST-EVIDENCE-DEADLINE-DRIFT]",
mutate(_expectations: HttpScenarioExpectation[], receipt: MutableReceipt) {
receipt.rows[0]!.testDeadlineOverrideMs = 500;
},
},
])("rejects $label with its stable diagnostic", async (fixture) => {
const { expectations, receipt } = await validFixture();
fixture.mutate(expectations, receipt);
if (!fixture.preserveDigest) {
receipt.catalogDigest = computeHttpScenarioCatalogDigest(
receipt.schemaVersion,
expectations,
);
}
const result = await runFixture(expectations, receipt);
expect(result.error).toBeUndefined();
expect(result.status).toBe(1);
expect(`${result.stdout}\n${result.stderr}`).toContain(fixture.diagnostic);
}, childProcessTimeout(962));
});