test(docs): verify:documentation을 띄우는 시험에 넉넉한 시간을 준다

문제: tests/unit/documentation-readiness.test.ts의 사례마다
verify:documentation을 새 프로세스로 띄운다. 이 브랜치에서 그 검사가 살아
있는 문서 전부를 읽게 돼 한 번 도는 시간이 늘었고, 부하가 큰 desktop(load
25)에서 FE-GATE-020의 기능 생성 드릴이 사본 안에서 이 파일을 돌릴 때 세
사례가 기본 시간 10초를 넘겨 실패했다. 같은 사례는 부하가 낮을 때 1~8초다.

고른 방법: 이 파일의 사례에 저장소 관례대로 시간 한도 60초를 준다
(`VERIFY_TIMEOUT`). 그리고 livingDocuments가 문서 내용을 읽지 않고 경로만
고르게 해 한 번 도는 일을 줄인다. 버린 안: vitest 전역 testTimeout을
올리는 것(다른 시험의 멈춤을 늦게 알게 된다).

위험: 진짜로 멈춘 검사를 60초 뒤에야 알게 된다.

검증: desktop에서 이 파일과 FE-GATE-005·FE-GATE-020을 다시 돌린다.
This commit is contained in:
DongHyeonka
2026-11-11 23:25:51 +09:00
parent 5f10f9285a
commit 7b09c215f0
2 changed files with 28 additions and 23 deletions
+1 -3
View File
@@ -726,8 +726,6 @@ export function checkDocsSystem(documentsRoot: string, repositoryRoot: string):
/** Living documents under `root` whose references verify:documentation checks. */
export function livingDocuments(root: string): string[] {
return readDocuments(root)
.map(({ path }) => path)
.filter(checkedForDrift);
return treeFiles(root).filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path) && checkedForDrift(path));
}
+27 -20
View File
@@ -50,6 +50,13 @@ async function verify(
}
}
/**
* Each case spawns verify:documentation, which reads every document. On a
* loaded host (the FE-GATE-020 drills run this file inside their copies) one
* run took more than the 10 s default.
*/
const VERIFY_TIMEOUT = 60_000;
function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
return verify({ [document]: mutate });
}
@@ -66,7 +73,7 @@ describe("verify:documentation on this repository", () => {
encoding: "utf8",
});
expect(result.status, `${result.stderr}${result.stdout}`).toBe(0);
}, 60_000);
}, VERIFY_TIMEOUT);
});
const gitEnvironment = {
@@ -133,7 +140,7 @@ describe("verify:documentation failure output (1101/14-06)", () => {
it("passes the documents as they are", async () => {
const result = await verifyWithReadme((readme) => readme);
expect(result.status, result.stderr).toBe(0);
});
}, VERIFY_TIMEOUT);
it("names the route ID that has no manual review record", async () => {
const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]);
@@ -141,7 +148,7 @@ describe("verify:documentation failure output (1101/14-06)", () => {
expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM");
expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u);
expect(result.stderr).not.toContain("scoped-review evidence");
});
}, VERIFY_TIMEOUT);
it("names every failed check", async () => {
const result = await verify(
@@ -150,7 +157,7 @@ describe("verify:documentation failure output (1101/14-06)", () => {
);
expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET");
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
});
}, VERIFY_TIMEOUT);
});
// 1101/14-05. README and the manual checklist listed every route ID, so each
@@ -168,7 +175,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
"docs/accessibility/manual-checklist.md": (checklist) => checklist.replaceAll(ROUTE_IDS, ""),
});
expect(result.status, result.stderr).toBe(0);
});
}, VERIFY_TIMEOUT);
it.each([
["README.md", "scripts/verify-documentation-readiness.ts", "scripts/verify-documentation-readyness.ts"],
@@ -180,7 +187,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${document} names paths that do not exist: ${after}`);
expect(result.stderr).toMatch(/\(failed: document references\)/u);
});
}, VERIFY_TIMEOUT);
it("fails when docs/README.md links a document that does not exist", async () => {
const result = await verifyWithReadme(
@@ -189,7 +196,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
);
expect(result.status).toBe(1);
expect(result.stderr).toContain("docs/README.md names paths that do not exist: docs/architecture/layer.md");
});
}, VERIFY_TIMEOUT);
it("fails when a document names a package script or a gate ID that does not exist", async () => {
const result = await verify({
@@ -199,12 +206,12 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
expect(result.status).toBe(1);
expect(result.stderr).toContain("README.md names package scripts that do not exist: verify:documentaton");
expect(result.stderr).toContain("docs/README.md names gate IDs that config/ci/gates.json does not define: FE-GATE-099");
});
}, VERIFY_TIMEOUT);
it("does not ask generated output to exist", async () => {
const result = await verifyWithReadme((readme) => `${readme}\nSee \`artifacts/quality/not-generated-yet.json\`.\n`);
expect(result.status, result.stderr).toBe(0);
});
}, VERIFY_TIMEOUT);
it("accepts a path under history a copy deleted, and only that", async () => {
const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`;
@@ -216,7 +223,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
const missing = await verifyWithReadme(naming);
expect(missing.status).toBe(1);
expect(missing.stderr).toContain("README.md names paths that do not exist: docs/retired-notes/plan.md");
});
}, VERIFY_TIMEOUT);
});
// 1103/12-05. Paths inside a command and links into the paired repositories
@@ -233,7 +240,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => {
const result = await verify({ [CI_DOC]: (text) => `${text}\n${line}\n` });
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: tests/integration/no-such-client.test.ts`);
});
}, VERIFY_TIMEOUT);
it("looks up a command's existing arguments and leaves placeholders alone", async () => {
const result = await verify({
@@ -242,7 +249,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => {
"Any script is run as `node scripts/…`.\n",
});
expect(result.status, result.stderr).toBe(0);
});
}, VERIFY_TIMEOUT);
it("checks a link or a path into a paired repository checked out beside this one", async () => {
const naming = (target: string) => (text: string) =>
@@ -267,7 +274,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => {
expect(broken.stderr).toContain(
`${CI_DOC} names paths that do not exist: ../clean-architecture-backend-template/docs/web/no-such.md`,
);
});
}, VERIFY_TIMEOUT);
it("reports a link into a paired repository that is not checked out as unverified", async () => {
const result = await verify({
@@ -277,7 +284,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => {
expect(result.stdout).toContain("not verified");
expect(result.report?.documentReferences.find((entry) => entry.path === CI_DOC)?.unverifiedLinks)
.toEqual(["../clean-architecture-backend-template/docs/web/no-such.md"]);
});
}, VERIFY_TIMEOUT);
});
// 1105/12-02. Paired references were looked up in the working tree of the
@@ -322,7 +329,7 @@ describe("verify:documentation paired references at the pinned commit (1105/12-0
]);
expect(entryOf(result)?.unverifiedLinks).toEqual([]);
expect(result.stderr).toContain("at the pinned commit (looked up in clean-architecture-backend-template ");
});
}, VERIFY_TIMEOUT);
it("reports the references as not verified when the checkout does not have the pinned commit", async () => {
// The desktop case: a sibling whose history stops before the pin, with
@@ -336,14 +343,14 @@ describe("verify:documentation paired references at the pinned commit (1105/12-0
expect(entryOf(result)?.unverifiedLinks).toEqual([`../${PAIRED_BACKEND}/docs/web/no-such.md`]);
expect(result.stdout).toContain("not verified");
expect(result.stdout).toContain("does not have the pinned commit");
});
}, VERIFY_TIMEOUT);
it("fails a link out of the repository into a repository that is not paired", async () => {
const misspelled = "clean-architecture-backend-templat/docs/web/http-contract.md";
const result = await verify({ [CI_DOC]: (text) => `${text}\n[contract](../../../${misspelled})\n` });
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: ../${misspelled}`);
});
}, VERIFY_TIMEOUT);
});
// 1101/14-03. The entry documents drew a top-level domain layer that does not
@@ -360,7 +367,7 @@ describe("verify:documentation source structure (1101/14-03)", () => {
"docs/architecture/layers.md does not name .dependency-cruiser.json rules: platform-kernel-is-product-neutral",
);
expect(result.stderr).toMatch(/\(failed: source structure\)/u);
});
}, VERIFY_TIMEOUT);
it("fails when a document names a top-level src folder that does not exist", async () => {
const result = await verifyWithReadme((readme) =>
@@ -368,7 +375,7 @@ describe("verify:documentation source structure (1101/14-03)", () => {
);
expect(result.status).toBe(1);
expect(result.stderr).toContain("README.md names src folders that do not exist: domain");
});
}, VERIFY_TIMEOUT);
it("fails when a document describes a folder differently from layers.md", async () => {
const result = await verifyWithReadme(
@@ -379,5 +386,5 @@ describe("verify:documentation source structure (1101/14-03)", () => {
expect(result.stderr).toContain(
"docs/architecture/overview.md does not describe src folders as the layers.md table does: platform",
);
});
}, VERIFY_TIMEOUT);
});