Files
clean-architecture-frontend…/scripts/test-performance.ts
T
DongHyeonka e02f252d57 fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다
문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.

고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
  첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
  스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
  --hide-scrollbars를 빼고 띄운다. lab.json context.browser에
  scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
  scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
  (test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.

위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5

Refs: 1105/15-05
2026-11-06 01:23:48 +09:00

304 lines
11 KiB
TypeScript

import { spawn } from "node:child_process";
import { mkdir, readFile } from "node:fs/promises";
import { cpus, loadavg } from "node:os";
import process from "node:process";
import { chromium, type Browser } from "@playwright/test";
import {
assertPortUnused,
assertServedRelease,
DEFAULT_LAB_PORT,
DEFAULT_LAB_RUNS,
labBrowserLaunchOptions,
previewArguments,
summarizeSamples,
} from "./lib/lab-performance.ts";
import { evaluateLabBudget } from "./lib/performance-budgets.ts";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { labPerformanceArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type ContractPerformanceEvidence = {
lcpMs: number;
cls: number;
clickAt: number | null;
headingAt: number | null;
eventDurationMs: number | null;
};
type ContractPerformanceWindow = Window & {
__contractPerformance?: ContractPerformanceEvidence;
};
type LayoutShiftEntry = PerformanceEntry & {
hadRecentInput: boolean;
value: number;
};
const argument = (name: string) =>
process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3);
const port = Number(process.env.LAB_PERFORMANCE_PORT ?? DEFAULT_LAB_PORT);
const runs = Number(argument("runs") ?? DEFAULT_LAB_RUNS);
if (!Number.isSafeInteger(port) || port <= 0 || !Number.isSafeInteger(runs) || runs < 1) {
throw new TypeError("LAB_PERFORMANCE_PORT must be a port and --runs a positive integer.");
}
const baseUrl = `http://127.0.0.1:${port}`;
const target = ROUTE_REGISTRY.EXAMPLES_PLATFORM;
const targetLabel = target.navigationLabel;
if (!targetLabel) {
throw new Error("Performance route must be present in navigation.");
}
// 11-07. A server already on the port used to be measured in place of this
// build: vite moved to another port and the gate never noticed.
await assertPortUnused(baseUrl);
// Its own process group: `corepack` starts pnpm, which starts vite, and a
// signal to `corepack` alone left vite serving the port after the gate ended.
const server = spawn("corepack", [...previewArguments(port)], {
stdio: "ignore",
detached: true,
});
let serverExit: string | null = null;
server.on("exit", (code, signal) => {
serverExit = `preview server exited (${signal ?? code})`;
});
async function waitForServer() {
for (let attempt = 0; attempt < 100; attempt += 1) {
if (serverExit) throw new Error(serverExit);
try {
const response = await fetch(baseUrl);
if (response.ok) return;
} catch {
// The bounded retry loop handles startup races.
}
await new Promise((resolve) => setTimeout(resolve, 100));
}
throw new Error("Preview server did not become ready.");
}
type RunMetrics = { lcpMs: number; cls: number; namedInteractionMs: number; eventDurationMs: number | null };
async function measureOnce(browser: Browser): Promise<RunMetrics> {
// Every run is a cold, isolated context.
const context = await browser.newContext({
viewport: { width: 1280, height: 720 },
});
try {
const page = await context.newPage();
const cdp = await context.newCDPSession(page);
await cdp.send("Network.enable");
await cdp.send("Network.emulateNetworkConditions", {
offline: false,
latency: 40,
downloadThroughput: 200_000,
uploadThroughput: 93_750,
connectionType: "cellular4g",
});
await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
await page.addInitScript((title: string) => {
const evidence: ContractPerformanceEvidence = {
lcpMs: 0,
cls: 0,
clickAt: null,
headingAt: null,
eventDurationMs: null,
};
(window as ContractPerformanceWindow).__contractPerformance = evidence;
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) evidence.lcpMs = entry.startTime;
}).observe({ type: "largest-contentful-paint", buffered: true });
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
const layoutShift = entry as LayoutShiftEntry;
if (!layoutShift.hadRecentInput) {
evidence.cls += layoutShift.value;
}
}
}).observe({ type: "layout-shift", buffered: true });
// 11-07. The interaction is timed by the page's own clock, from the
// click event to the target heading entering the DOM, so Playwright's
// round trips are not in it. The Event Timing entry of the click (the
// INP input) is recorded next to it.
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.name === "click") {
evidence.eventDurationMs = Math.max(evidence.eventDurationMs ?? 0, entry.duration);
}
}
}).observe({ type: "event", buffered: true, durationThreshold: 16 } as PerformanceObserverInit);
document.addEventListener(
"click",
(event) => {
evidence.clickAt ??= event.timeStamp;
},
{ capture: true },
);
new MutationObserver((_records, observer) => {
if (evidence.clickAt === null) return;
const found = [...document.querySelectorAll("h1, h2")].some(
(heading) => heading.textContent?.trim() === title,
);
if (found) {
evidence.headingAt = performance.now();
observer.disconnect();
}
}).observe(document, { childList: true, subtree: true, characterData: true });
}, target.title);
await page.goto(baseUrl, { waitUntil: "networkidle" });
// Playwright matches accessible names by substring, so the navigation entry
// "플랫폼 구성" also matched the home page's "플랫폼 구성 보기" call to
// action; `exact` keeps the locator on the navigation link.
await page.getByRole("link", { name: targetLabel, exact: true }).click();
await page.getByRole("heading", { name: target.title }).waitFor();
await page.waitForFunction(
() => (window as ContractPerformanceWindow).__contractPerformance?.headingAt !== null,
);
const paint = await page.evaluate(
() => (window as ContractPerformanceWindow).__contractPerformance,
);
if (!paint || paint.clickAt === null || paint.headingAt === null) {
throw new Error("Browser performance evidence was not initialized.");
}
return {
lcpMs: Math.round(paint.lcpMs),
cls: Number(paint.cls.toFixed(4)),
namedInteractionMs: Math.round(paint.headingAt - paint.clickAt),
eventDurationMs:
paint.eventDurationMs === null ? null : Math.round(paint.eventDurationMs),
};
} finally {
await context.close();
}
}
const load = () => loadavg().map((value) => Math.round(value * 100) / 100);
try {
await waitForServer();
const release = JSON.parse(
await readFile("dist/release-manifest.json", "utf8"),
);
await assertServedRelease(baseUrl, release);
const thresholds = JSON.parse(
await readFile("config/performance/budgets.json", "utf8"),
).lab;
const browser = await chromium.launch(labBrowserLaunchOptions());
try {
const loadBefore = load();
const samples: RunMetrics[] = [];
for (let run = 0; run < runs; run += 1) samples.push(await measureOnce(browser));
const loadAfter = load();
// The served build must not have changed under the runs either.
await assertServedRelease(baseUrl, release);
const lcp = summarizeSamples(samples.map((sample) => sample.lcpMs));
const cls = summarizeSamples(samples.map((sample) => sample.cls));
const interaction = summarizeSamples(
samples.map((sample) => sample.namedInteractionMs),
);
const eventDurations = samples.flatMap((sample) =>
sample.eventDurationMs === null ? [] : [sample.eventDurationMs],
);
const contextMetadata = {
runner: {
platform: process.platform,
architecture: process.arch,
nodeVersion: process.version,
cpuModel: cpus()[0]?.model.trim() ?? "unknown",
logicalCpus: cpus().length,
loadAverage: { before: loadBefore, after: loadAfter },
},
// 1105/15-05. Classic scrollbars, not Playwright's hidden ones.
browser: {
name: "chromium",
version: await browser.version(),
scrollbars: "visible",
},
viewport: { width: 1280, height: 720 },
network: {
profile: "contract-fast-4g",
latencyMs: 40,
downloadBytesPerSecond: 200_000,
uploadBytesPerSecond: 93_750,
},
cpu: { throttlingRate: 4 },
cache: { state: "cold", isolation: "new-browser-context" },
build: {
buildId: release.buildId,
releaseId: release.releaseId,
served: `${baseUrl}/release-manifest.json`,
},
// 11-07. The budget is judged on the median of cold runs; every run and
// the spread stay in the evidence.
sampling: {
runs,
statistic: "median",
interactionClock: "page: click event to target heading in DOM",
lcpMs: lcp,
cls,
namedInteractionMs: interaction,
clickEventDurationMs: eventDurations.length
? summarizeSamples(eventDurations)
: null,
},
};
const metrics = {
lcpMs: lcp.median,
cls: cls.median,
namedInteractionMs: interaction.median,
};
const result = evaluateLabBudget(
{ context: contextMetadata, metrics },
thresholds,
);
const fixtures = [
{
name: "missing-context",
passed: !evaluateLabBudget({ metrics }, thresholds).passed,
},
{
name: "lcp-over-threshold",
passed: !evaluateLabBudget(
{
context: contextMetadata,
metrics: { ...metrics, lcpMs: thresholds.lcpMs + 1 },
},
thresholds,
).passed,
},
];
const passed = result.passed && fixtures.every((fixture) => fixture.passed);
await mkdir("artifacts/performance", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/performance/lab.json",
schema: labPerformanceArtifactSchema,
value: {
schemaVersion: 1,
generatedAt: new Date().toISOString(),
context: contextMetadata,
metrics,
thresholds,
fixtures,
passed,
},
});
if (!passed) {
throw new Error(
`Lab performance failed (median of ${runs}): ${JSON.stringify(metrics)}; ` +
`interaction samples ${interaction.samples.join(",")}`,
);
}
process.stdout.write(
`Lab performance: PASS, median of ${runs} (LCP ${metrics.lcpMs}ms, CLS ${metrics.cls}, interaction ${metrics.namedInteractionMs}ms ` +
`[${interaction.min}-${interaction.max}])\n`,
);
} finally {
await browser.close();
}
} finally {
if (server.pid !== undefined && serverExit === null) {
process.kill(-server.pid, "SIGTERM");
}
}