Files
clean-architecture-frontend…/tests/unit/example-feature-rules.test.ts
T
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

335 lines
17 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import path from "node:path";
import { describe, expect, it } from "vitest";
import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts";
import { reachablePackageScripts } from "../../scripts/lib/package-script-graph.ts";
import {
REMOVABLE_TEMPLATE_FEATURES,
removableTemplateFeaturePaths,
type RemovableTemplateFeature,
} from "../../scripts/lib/removable-template-features.ts";
import { PLATFORM_ROUTE_REGISTRY } from "../../src/contracts/routes.ts";
import { ROUTE_FEATURE_OWNER, ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
import { childProcessTimeout } from "../helpers/child-process-timeout.ts";
/**
* R4 and R5 of docs/manual/03-outside-feature-folder.md. A sample feature
* that the template or a project ships is listed in
* scripts/lib/removable-template-features.ts, and the list is proven by a
* drill that builds and tests a copy without it (R4). The gates' own targets
* (visual goldens, e2e routes, the gate evidence list, scale measurements)
* are platform screens, test fixtures and generator output, never a sample a
* copy is meant to delete (R5): the template's reference sample was the
* target of nine gates when it was deleted on 2026-11-07.
*
* R5 follows each target to what owns it, so a sample is found by what it
* owns, not by its name appearing in a string: a route path resolves through
* the route table to a route and its feature, a story id to the stories file
* that defines it, a spec's imports to the files they load, a route review in
* the evidence list to its route, and a gate's commands through the package
* script graph to the scripts and paths they run.
*/
const PLATFORM = "platform";
type Sample = Readonly<{ featureId: string; paths: readonly string[]; scripts: readonly string[] }>;
type RouteRow = Readonly<{ routeId: string; path: string; owner: string }>;
/** What the gates point at, each with where it was found. */
type GateTargets = Readonly<{
routeTargets: readonly Readonly<{ where: string; target: string }>[];
reachedFiles: readonly Readonly<{ where: string; file: string }>[];
artifacts: readonly string[];
gateScripts: readonly Readonly<{ gateId: string; script: string; command: string }>[];
scaleSourceFeature: string;
}>;
function samplesOf(features: readonly RemovableTemplateFeature[]): Sample[] {
return features.map((feature) => ({
featureId: feature.featureId,
paths: removableTemplateFeaturePaths(feature),
scripts: feature.scripts,
}));
}
function owningSample(samples: readonly Sample[], file: string): Sample | undefined {
return samples.find(({ paths }) => paths.some((owned) => file === owned || file.startsWith(`${owned}/`)));
}
/** The route table the app boots with: each route and the feature that declares it. */
function repositoryRoutes(): RouteRow[] {
const routes = Object.values(ROUTE_REGISTRY) as readonly Readonly<{ routeId: string; path: string }>[];
return routes.map(({ routeId, path: routePath }) => ({
routeId,
path: routePath,
owner: ROUTE_FEATURE_OWNER[routeId] ?? (routeId in PLATFORM_ROUTE_REGISTRY ? PLATFORM : "unknown"),
}));
}
/** The route the router renders for `target`: a declared path, else the catch-all. */
function resolveRoute(target: string, routes: readonly RouteRow[]): RouteRow | undefined {
const pathname = target.split(/[?#]/u)[0] ?? "";
const segments = pathname.split("/").filter(Boolean);
const declared = routes.find((route) => {
if (route.path === "*") return false;
const pattern = route.path.split("/").filter(Boolean);
return (
pattern.length === segments.length &&
pattern.every((part, index) => (part.startsWith(":") ? segments[index] !== "" : part === segments[index]))
);
});
return declared ?? routes.find((route) => route.path === "*");
}
/**
* The app paths a spec opens literally. A target computed at run time is left
* out: the a11y spec walks the whole route table, which names every installed
* feature and none in particular, and a generated feature's path is generator
* output. A sample module such a spec imports is still found by the import walk.
*/
function literalGotoTargets(source: string): string[] {
return [...source.matchAll(/\.goto\(\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/gu)].flatMap(([, , raw = ""]) => {
// `${server.origin}/` is the served build's origin, then the app path.
const target = raw.replace(/^\$\{[^}]*\}/u, "");
if (target.includes("${")) return [];
if (target === "") return ["/"];
return target.startsWith("/") ? [target] : [];
});
}
const IMPORT_SPECIFIER =
/(?:\bimport\s+(?:type\s+)?(?:[^'"`;]*?\sfrom\s*)?|\bexport\s+(?:type\s+)?[^'"`;]*?\sfrom\s*|\bimport\(\s*)["']([^"']+)["']/gu;
/** Repository files `file` imports, resolved; package imports are not followed. */
function importedFiles(file: string, source: string, exists: (file: string) => boolean): string[] {
return [...source.matchAll(IMPORT_SPECIFIER)].flatMap(([, specifier = ""]) => {
if (!specifier.startsWith(".")) return [];
const base = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
const resolved = [base, `${base}.ts`, `${base}.tsx`, `${base}/index.ts`].find(exists);
return resolved === undefined ? [] : [resolved];
});
}
/**
* Every file the entries load. The walk stops at `src/.generated/`: the
* feature index there is generator output that imports each installed
* feature, and removing a sample writes it again without that sample.
*/
function reachableFiles(
entries: readonly string[],
read: (file: string) => string,
exists: (file: string) => boolean,
): Readonly<{ where: string; file: string }>[] {
const reached = new Map<string, string>();
const queue = entries.map((entry) => ({ where: entry, file: entry }));
for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
if (reached.has(next.file) || next.file.startsWith("src/.generated/")) continue;
reached.set(next.file, next.where);
for (const imported of importedFiles(next.file, read(next.file), exists)) {
queue.push({ where: next.where, file: imported });
}
}
return [...reached].map(([file, where]) => ({ where, file }));
}
/** Storybook's id prefix for a stories file's title: "Platform/Galleries" is "platform-galleries". */
function storyIdPrefix(title: string): string {
return title.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "");
}
/** Gate targets that a sample owns, or that point at nothing. Empty when R5 holds. */
function sampleGateTargets(samples: readonly Sample[], routes: readonly RouteRow[], targets: GateTargets): string[] {
const sampleIds = new Set(samples.map(({ featureId }) => featureId));
const findings: string[] = [];
for (const { where, target } of targets.routeTargets) {
const route = resolveRoute(target, routes);
if (route === undefined) findings.push(`${where}: goto ${target} matches no route`);
else if (sampleIds.has(route.owner)) findings.push(`${where}: goto ${target} is ${route.routeId} of sample ${route.owner}`);
}
for (const { where, file } of targets.reachedFiles) {
const sample = owningSample(samples, file);
if (sample) findings.push(`${where} loads ${file} of sample ${sample.featureId}`);
}
for (const artifact of targets.artifacts) {
const review = /^docs\/accessibility\/route-reviews\/([^/]+)\.md$/u.exec(artifact)?.[1];
const route = review === undefined ? undefined : routes.find(({ routeId }) => routeId === review);
if (review !== undefined && route === undefined) {
findings.push(`config/ci/gates.json: ${artifact} reviews no route in the route table`);
} else if (route !== undefined && sampleIds.has(route.owner)) {
findings.push(`config/ci/gates.json: ${artifact} reviews ${route.routeId} of sample ${route.owner}`);
}
const sample = owningSample(samples, artifact);
if (sample) findings.push(`config/ci/gates.json: ${artifact} is in sample ${sample.featureId}`);
}
for (const { gateId, script, command } of targets.gateScripts) {
for (const sample of samples) {
if (sample.scripts.includes(script)) findings.push(`${gateId} runs ${script}, a script of sample ${sample.featureId}`);
}
const words = command.split(/\s+/u).map((word) => word.replace(/^["']|["']$/gu, ""));
for (const [index, word] of words.entries()) {
const feature = /^--feature=(.+)$/u.exec(word)?.[1] ?? (word === "--feature" ? words[index + 1] : undefined);
if (feature !== undefined && sampleIds.has(feature)) findings.push(`${gateId} runs ${script} on sample ${feature}`);
const sample = owningSample(samples, word.replace(/^\.\//u, ""));
if (sample) findings.push(`${gateId} runs ${script} on ${word} of sample ${sample.featureId}`);
}
}
if (sampleIds.has(targets.scaleSourceFeature)) {
findings.push(`config/scale/feature-shape-growth.json: sourceFeature is sample ${targets.scaleSourceFeature}`);
}
return findings;
}
function trackedFiles(): string[] {
const listed = spawnSync("git", ["ls-files", "-z"], { encoding: "utf8" });
if (listed.error || listed.status !== 0) throw new Error(`git ls-files failed: ${listed.error?.message ?? listed.stderr}`);
return listed.stdout.split("\0").filter((file) => file !== "" && existsSync(file));
}
async function repositoryGateTargets(): Promise<GateTargets> {
const tracked = trackedFiles();
const specs = tracked.filter((file) => /^tests\/(?:visual|e2e)\/.+\.tsx?$/u.test(file));
const read = (file: string) => readFileSync(file, "utf8");
const routeTargets = specs.flatMap((file) => literalGotoTargets(read(file)).map((target) => ({ where: file, target })));
// A workshop story a visual spec opens is drawn by the stories file whose title gives its id.
const stories = tracked
.filter((file) => file.endsWith(".stories.tsx"))
.flatMap((file) => {
const title = /^\s*title:\s*["']([^"']+)["']/mu.exec(read(file))?.[1];
return title === undefined ? [] : [{ file, prefix: storyIdPrefix(title) }];
});
const storyFiles = specs
.filter((file) => file.startsWith("tests/visual/"))
.flatMap((file) =>
[...read(file).matchAll(/["'`]([a-z0-9-]+)--[a-z0-9-]+["'`]/gu)].map(([story = "", prefix = ""]) => {
const owner = stories.find((candidate) => candidate.prefix === prefix);
return { where: `${file} (story ${story.slice(1, -1)})`, file: owner?.file ?? `<no stories file for ${prefix}>` };
}),
);
const contract = await loadCiGateContract(process.cwd());
const packageScripts = (JSON.parse(read("package.json")) as { scripts: Record<string, string> }).scripts;
const gateScripts = contract.gates.flatMap(({ id, commandIds }) =>
reachablePackageScripts(
packageScripts,
contract.commands.filter((command) => commandIds.includes(command.id)).map(({ script }) => script),
).map((script) => ({ gateId: id, script, command: packageScripts[script] ?? "" })),
);
const scale = JSON.parse(read("config/scale/feature-shape-growth.json")) as { sourceFeature: string };
return {
routeTargets,
reachedFiles: [...reachableFiles(specs, read, existsSync), ...storyFiles],
artifacts: contract.artifacts.map(({ path: artifact }) => artifact),
gateScripts,
scaleSourceFeature: scale.sourceFeature,
};
}
describe("sample features (R4)", () => {
it("are all proven by the removal drill in FE-GATE-020", async () => {
const contract = await loadCiGateContract(process.cwd());
const removability = contract.gates.find(({ id }) => id === "FE-GATE-020");
const scripts = new Set(
contract.commands
.filter(({ id }) => removability?.commandIds.includes(id))
.map(({ script }) => script),
);
expect(scripts).toContain("test:sample-removal");
// Without `--feature` the drill deletes every listed sample.
const packageScripts = (JSON.parse(readFileSync("package.json", "utf8")) as { scripts: Record<string, string> })
.scripts;
expect(packageScripts["test:sample-removal"]).not.toMatch(/--feature/u);
// It builds and tests the copy; a documents-only check does not prove removal.
const drill = readFileSync("scripts/test-sample-removal.ts", "utf8");
expect(drill).toMatch(/check\(`\$\{prefix\}build`, "build"\)/u);
expect(drill).toMatch(/check\(`\$\{prefix\}unit-integration`, "test:all"\)/u);
});
});
describe("gate targets (R5)", () => {
it("are owned by no sample feature and each points at something", async () => {
const targets = await repositoryGateTargets();
// The walk reaches the real targets: an empty one would pass anything.
expect(targets.routeTargets.length).toBeGreaterThan(10);
expect(targets.reachedFiles.some(({ file }) => file.startsWith("src/"))).toBe(true);
expect(targets.artifacts.some((artifact) => artifact.startsWith("docs/accessibility/route-reviews/"))).toBe(true);
expect(targets.gateScripts.length).toBeGreaterThan(20);
expect(sampleGateTargets(samplesOf(REMOVABLE_TEMPLATE_FEATURES), repositoryRoutes(), targets)).toEqual([]);
}, childProcessTimeout(176));
it("finds this repository's targets once a sample owns what they point at", async () => {
// As if the platform overview screen, the design system and the message catalog were a sample's.
const sample: Sample = {
featureId: "overview-sample",
paths: ["src/presentation/design-system", "src/presentation/i18n"],
scripts: ["test:visual"],
};
const routes = repositoryRoutes().map((route) =>
route.routeId === "EXAMPLES_PLATFORM" ? { ...route, owner: sample.featureId } : route,
);
const findings = sampleGateTargets([sample], routes, await repositoryGateTargets());
expect(findings).toEqual(
expect.arrayContaining([
"tests/e2e/platform-overview.spec.ts: goto /examples/platform is EXAMPLES_PLATFORM of sample overview-sample",
"tests/visual/platform.visual.spec.ts (story platform-galleries--design-system) loads src/presentation/design-system/galleries.stories.tsx of sample overview-sample",
"tests/e2e/accessibility.spec.ts loads src/presentation/i18n/catalog.ts of sample overview-sample",
"FE-GATE-008 runs test:visual, a script of sample overview-sample",
]),
);
}, childProcessTimeout(85));
it("follows routes, imports, route reviews, scripts and the scale record of a synthetic sample", () => {
const sample: Sample = {
featureId: "order-feature",
paths: ["src/features/order-feature", "tests/features/order-feature"],
scripts: ["test:orders"],
};
const routes: RouteRow[] = [
{ routeId: "APP_HOME", path: "/", owner: PLATFORM },
{ routeId: "ORDER_DETAIL", path: "/orders/:orderId", owner: "order-feature" },
{ routeId: "NOT_FOUND", path: "*", owner: PLATFORM },
];
const sources: Record<string, string> = {
"tests/e2e/orders.spec.ts": [
`import { ORDER } from "../../src/features/order-feature/order-contract.ts";`,
`import { INDEX } from "../../src/.generated/product-feature-index.ts";`,
`await page.goto(\`\${server.origin}/orders/7?tab=items\`);`,
`await page.goto("/");`,
`await page.goto("/no-such-page");`,
`await page.goto(route);`,
].join("\n"),
"src/features/order-feature/order-contract.ts": `export const ORDER = 1;`,
};
const exists = (file: string) => file in sources || file === "src/.generated/product-feature-index.ts";
const targets: GateTargets = {
routeTargets: literalGotoTargets(sources["tests/e2e/orders.spec.ts"]!).map((target) => ({
where: "tests/e2e/orders.spec.ts",
target,
})),
reachedFiles: reachableFiles(["tests/e2e/orders.spec.ts"], (file) => sources[file] ?? "", exists),
artifacts: ["docs/accessibility/route-reviews/ORDER_DETAIL.md", "docs/accessibility/route-reviews/GONE.md"],
gateScripts: [
{ gateId: "FE-GATE-008", script: "test:orders", command: "playwright test" },
{ gateId: "FE-GATE-005", script: "test:unit", command: "vitest run tests/features/order-feature" },
{ gateId: "FE-GATE-020", script: "test:sample-removal", command: "node drill.ts --feature=order-feature" },
],
scaleSourceFeature: "order-feature",
};
expect(sampleGateTargets([sample], routes, targets)).toEqual([
"tests/e2e/orders.spec.ts: goto /orders/7?tab=items is ORDER_DETAIL of sample order-feature",
"tests/e2e/orders.spec.ts loads src/features/order-feature/order-contract.ts of sample order-feature",
"config/ci/gates.json: docs/accessibility/route-reviews/ORDER_DETAIL.md reviews ORDER_DETAIL of sample order-feature",
"config/ci/gates.json: docs/accessibility/route-reviews/GONE.md reviews no route in the route table",
"FE-GATE-008 runs test:orders, a script of sample order-feature",
"FE-GATE-005 runs test:unit on tests/features/order-feature of sample order-feature",
"FE-GATE-020 runs test:sample-removal on sample order-feature",
"config/scale/feature-shape-growth.json: sourceFeature is sample order-feature",
]);
// `/no-such-page` is the catch-all's, a platform screen; the generated index ends the walk.
expect(targets.reachedFiles.map(({ file }) => file)).not.toContain("src/.generated/product-feature-index.ts");
});
});