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, type Page } 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; /** 1105/15-01. CLS of a direct visit to the target route. */ targetDeepLinkCls: number; }; /** * A cold, isolated context with the lab's network and CPU throttling and the * page-side evidence recorder. `title` is the heading whose arrival after a * click ends the named interaction. */ async function openMeasuredPage(browser: Browser, title: string) { 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((headingTitle: 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() === headingTitle, ); if (found) { evidence.headingAt = performance.now(); observer.disconnect(); } }).observe(document, { childList: true, subtree: true, characterData: true }); }, title); return { context, page }; } catch (error) { await context.close(); throw error; } } /** The evidence once the layout-shift observer has delivered its entries. */ async function settledEvidence(page: Page) { return page.evaluate(async () => { // Observer callbacks run as tasks after the frame that recorded them. await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))); await new Promise((resolve) => setTimeout(resolve, 0)); return (window as ContractPerformanceWindow).__contractPerformance; }); } async function measureOnce( browser: Browser, ): Promise> { // Every run is a cold, isolated context. const { context, page } = await openMeasuredPage(browser, target.title); try { 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(); } } /** * 1105/15-01. The click run cannot see a shift the target screen makes while * it fills in: a shift within 500 ms of the click has `hadRecentInput` and * is left out of CLS by definition, and the lab only opened `/`. The target * screen used to push its content 21 px after its title (CLS 0.0046) and the * lab reported 0. A direct visit has no input, so every shift until the * network is idle after the heading counts. */ async function measureTargetDeepLink(browser: Browser): Promise { const { context, page } = await openMeasuredPage(browser, target.title); try { await page.goto(new URL(target.path, baseUrl).href, { waitUntil: "networkidle" }); await page.getByRole("heading", { name: target.title, exact: true }).waitFor(); await page.waitForLoadState("networkidle"); const evidence = await settledEvidence(page); if (!evidence) throw new Error("Browser performance evidence was not initialized."); return Number(evidence.cls.toFixed(4)); } 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) { const click = await measureOnce(browser); samples.push({ ...click, targetDeepLinkCls: await measureTargetDeepLink(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 deepLinkCls = summarizeSamples( samples.map((sample) => sample.targetDeepLinkCls), ); 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, // 1105/15-01. A cold direct visit to the target route in each run. targetDeepLink: { path: target.path, clock: "navigation start to network idle after the target heading", cls: deepLinkCls, }, }, }; const metrics = { lcpMs: lcp.median, cls: cls.median, namedInteractionMs: interaction.median, targetDeepLinkCls: deepLinkCls.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}], ${target.path} direct CLS ${metrics.targetDeepLinkCls} ` + `[${deepLinkCls.min}-${deepLinkCls.max}])\n`, ); } finally { await browser.close(); } } finally { if (server.pid !== undefined && serverExit === null) { process.kill(-server.pid, "SIGTERM"); } }