diff --git a/config/schemas/lab-performance.schema.json b/config/schemas/lab-performance.schema.json index 878b9f33..0943c608 100644 --- a/config/schemas/lab-performance.schema.json +++ b/config/schemas/lab-performance.schema.json @@ -20,7 +20,7 @@ }, "metrics": { "type": "object", - "required": ["lcpMs", "cls", "namedInteractionMs"] + "required": ["lcpMs", "cls", "namedInteractionMs", "targetDeepLinkCls"] }, "thresholds": { "type": "object" }, "fixtures": { "type": "array", "minItems": 2 }, diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index f2a861a7..7c907136 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -90,6 +90,11 @@ lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build 대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고, lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry 길이(INP의 입력값)는 `context.sampling.clickEventDurationMs`에 따로 남는다. +- 클릭으로 들어간 화면의 CLS는 대상 화면이 채워지며 내는 shift를 보지 못한다. + 클릭 뒤 500 ms 안의 shift는 정의상 입력이 낸 것(`hadRecentInput`)이라 빠진다. + 그래서 run마다 대상 라우트를 새 context에서 직접 열고, heading 뒤 network + idle까지의 CLS를 `metrics.targetDeepLinkCls`(중앙값)와 + `context.sampling.targetDeepLink`에 남긴다. 예산은 `cls`와 같다(1105/15-01). - CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 `context.runner`에 남긴다. - Chromium은 스크롤바를 보이게 띄운다(`--hide-scrollbars` 제외, 1105/15-05). Playwright 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며 diff --git a/scripts/lib/performance-budgets.ts b/scripts/lib/performance-budgets.ts index b2bf26b1..577012b2 100644 --- a/scripts/lib/performance-budgets.ts +++ b/scripts/lib/performance-budgets.ts @@ -62,10 +62,23 @@ export function describeBundleBudgetFailures( return lines; } +/** + * 1105/15-01. `targetDeepLinkCls` is the CLS of a direct visit to the lab's + * target route, judged against the same `cls` threshold. The click run + * cannot see a shift the target makes while it fills in: one within 500 ms + * of the click is input-driven by definition. + */ export type LabMetrics = Readonly<{ lcpMs: number; cls: number; namedInteractionMs: number; + targetDeepLinkCls: number; +}>; + +export type LabThresholds = Readonly<{ + lcpMs: number; + cls: number; + namedInteractionMs: number; }>; export function evaluateLabBudget( @@ -73,7 +86,7 @@ export function evaluateLabBudget( context?: Readonly>; metrics: LabMetrics; }>, - thresholds: LabMetrics, + thresholds: LabThresholds, ) { const requiredContext = [ "runner", @@ -92,6 +105,7 @@ export function evaluateLabBudget( cls: report.metrics.cls <= thresholds.cls, namedInteraction: report.metrics.namedInteractionMs <= thresholds.namedInteractionMs, + targetDeepLinkCls: report.metrics.targetDeepLinkCls <= thresholds.cls, }; return Object.freeze({ missingContext: Object.freeze(missingContext), diff --git a/scripts/test-performance.ts b/scripts/test-performance.ts index 5a96be2d..f7877a40 100644 --- a/scripts/test-performance.ts +++ b/scripts/test-performance.ts @@ -3,7 +3,7 @@ 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 { chromium, type Browser, type Page } from "@playwright/test"; import { assertPortUnused, @@ -78,10 +78,21 @@ async function waitForServer() { throw new Error("Preview server did not become ready."); } -type RunMetrics = { lcpMs: number; cls: number; namedInteractionMs: number; eventDurationMs: number | null }; +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; +}; -async function measureOnce(browser: Browser): Promise { - // Every run is a cold, isolated context. +/** + * 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 }, }); @@ -97,7 +108,7 @@ async function measureOnce(browser: Browser): Promise { connectionType: "cellular4g", }); await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 }); - await page.addInitScript((title: string) => { + await page.addInitScript((headingTitle: string) => { const evidence: ContractPerformanceEvidence = { lcpMs: 0, cls: 0, @@ -138,14 +149,37 @@ async function measureOnce(browser: Browser): Promise { new MutationObserver((_records, observer) => { if (evidence.clickAt === null) return; const found = [...document.querySelectorAll("h1, h2")].some( - (heading) => heading.textContent?.trim() === title, + (heading) => heading.textContent?.trim() === headingTitle, ); if (found) { evidence.headingAt = performance.now(); observer.disconnect(); } }).observe(document, { childList: true, subtree: true, characterData: true }); - }, target.title); + }, 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 @@ -173,6 +207,28 @@ async function measureOnce(browser: Browser): Promise { } } +/** + * 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 { @@ -188,7 +244,10 @@ try { try { const loadBefore = load(); const samples: RunMetrics[] = []; - for (let run = 0; run < runs; run += 1) samples.push(await measureOnce(browser)); + 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); @@ -197,6 +256,9 @@ try { 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], ); @@ -241,12 +303,19 @@ try { 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 }, @@ -291,7 +360,8 @@ try { } 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`, + `[${interaction.min}-${interaction.max}], ${target.path} direct CLS ${metrics.targetDeepLinkCls} ` + + `[${deepLinkCls.min}-${deepLinkCls.max}])\n`, ); } finally { await browser.close(); diff --git a/src/presentation/examples/platform-overview-page.tsx b/src/presentation/examples/platform-overview-page.tsx index 1cf80f90..329d6a54 100644 --- a/src/presentation/examples/platform-overview-page.tsx +++ b/src/presentation/examples/platform-overview-page.tsx @@ -60,6 +60,23 @@ function Metric({ ); } +/** + * 1105/15-01. The release metrics before the summary resolves, or after it + * failed: the resolved metrics' labels and hint lines, so the grid keeps its + * height. The status takes the first card's value and stays short enough for + * one line in the narrowest card (13rem), as a build id does. + */ +function ReleaseMetricsPlaceholder({ status }: Readonly<{ status: string }>) { + return ( + <> + + + + + + ); +} + type RouteRow = (typeof ROUTE_REGISTRY)[keyof typeof ROUTE_REGISTRY]; const ROUTE_COLUMNS: readonly DataTableColumn[] = Object.freeze([ @@ -419,10 +436,18 @@ export function PlatformOverviewPage({ 부팅 시 경계 검사를 통과한 런타임 설정과 릴리스 매니페스트에서 옵니다.

-
- {release === "failed" ? ( - - ) : release ? ( + {/* 1105/15-01. The same four metrics, with the same hint lines, in + every state: the grid used to grow from one card to four with + hints once the summary resolved, about 30-100 ms after the title, + and pushed everything below it 21 px (CLS 0.0046 on a direct + visit). Only the values change; `aria-busy` says when they are + not there yet (the visual test waits on it). */} +
+ {release !== null && release !== "failed" ? ( <> @@ -450,7 +475,11 @@ export function PlatformOverviewPage({ /> ) : ( - + )}
diff --git a/tests/component/starter-platform-overview-page.test.tsx b/tests/component/starter-platform-overview-page.test.tsx index 3484238c..60aecfe7 100644 --- a/tests/component/starter-platform-overview-page.test.tsx +++ b/tests/component/starter-platform-overview-page.test.tsx @@ -233,13 +233,66 @@ describe("platform overview page", () => { }, }), }); + const region = screen.getByRole("region", { name: "릴리스 신원" }); await waitFor(() => expect( - screen.getByText("런타임 정보를 확인하지 못했습니다."), + within(metricByLabel(region, "빌드")).getByText("확인하지 못했습니다."), ).toBeVisible(), ); - expect( - screen.queryByText("런타임 정보를 확인하고 있습니다."), - ).not.toBeInTheDocument(); + expect(within(region).queryByText("확인하고 있습니다.")).not.toBeInTheDocument(); + }); + + /** + * 1105/15-01. The release metrics drew one "상태" card until the summary + * resolved, then four cards with hint lines: the grid grew by a hint line + * about 30-100 ms after the title and pushed the rest of the page 21 px + * (CLS 0.0046 on a direct visit). The cards and their hint lines are the + * same in every state; only the values change. + */ + it("keeps the release metrics' cards and hint lines while the summary loads", async () => { + const summary = { + buildId: "test-build", + releaseId: "test-release", + configSchemaVersion: "1", + apiContractVersion: "1", + assetManifestHash: "test-hash", + routeChunks: { "route-home": "assets/home.js" }, + }; + let resolve: (value: typeof summary) => void = () => {}; + const pending = new Promise((settle) => { + resolve = settle; + }); + await renderPage({ + application: createTestApplication({ + releaseInfo: { getCurrent: () => pending, refresh: () => pending }, + }), + }); + const region = screen.getByRole("region", { name: "릴리스 신원" }); + const shape = () => + [...region.querySelectorAll(".platform-metric")].map((card) => [ + card.querySelector("dt")?.textContent, + card.querySelector(".platform-metric__hint") !== null, + ]); + + const loading = shape(); + expect(within(metricByLabel(region, "빌드")).getByText("확인하고 있습니다.")).toBeVisible(); + expect(region.querySelector("dl")).toHaveAttribute("aria-busy", "true"); + + await act(async () => { + resolve(summary); + await pending; + }); + await waitFor(() => + expect(within(metricByLabel(region, "빌드")).getByText("test-build")).toBeVisible(), + ); + + expect(loading).toEqual([ + ["빌드", false], + ["릴리스", false], + ["설정 스키마", true], + ["계약 집합 다이제스트", true], + ]); + expect(shape()).toEqual(loading); + expect(region.querySelector("dl")).toHaveAttribute("aria-busy", "false"); }); }); diff --git a/tests/unit/performance-budgets.test.ts b/tests/unit/performance-budgets.test.ts index 7cff0612..1868f54b 100644 --- a/tests/unit/performance-budgets.test.ts +++ b/tests/unit/performance-budgets.test.ts @@ -42,7 +42,7 @@ describe("performance budgets", () => { const thresholds = { lcpMs: 2500, cls: 0.1, namedInteractionMs: 200 }; expect( evaluateLabBudget( - { metrics: { lcpMs: 1000, cls: 0, namedInteractionMs: 50 } }, + { metrics: { lcpMs: 1000, cls: 0, namedInteractionMs: 50, targetDeepLinkCls: 0 } }, thresholds, ), ).toMatchObject({ passed: false }); @@ -58,13 +58,41 @@ describe("performance budgets", () => { cache: {}, build: {}, }, - metrics: { lcpMs: 2501, cls: 0, namedInteractionMs: 50 }, + metrics: { lcpMs: 2501, cls: 0, namedInteractionMs: 50, targetDeepLinkCls: 0 }, }, thresholds, ).passed, ).toBe(false); }); + /** + * 1105/15-01. The lab entered its target route only by a click, and a + * shift within 500 ms of a click is left out of CLS. The target screen + * pushed its content 21 px after its title and the lab reported 0. The + * direct visit's CLS is judged against the same threshold. + */ + it("fails lab evidence when a direct visit to the target route shifts over the CLS budget", () => { + const thresholds = { lcpMs: 2500, cls: 0.1, namedInteractionMs: 200 }; + const context = { + runner: {}, + browser: {}, + viewport: {}, + network: {}, + cpu: {}, + cache: {}, + build: {}, + }; + const metrics = { lcpMs: 1000, cls: 0, namedInteractionMs: 50, targetDeepLinkCls: 0.0046 }; + + expect(evaluateLabBudget({ context, metrics }, thresholds).passed).toBe(true); + const shifted = evaluateLabBudget( + { context, metrics: { ...metrics, targetDeepLinkCls: 0.11 } }, + thresholds, + ); + expect(shifted.passed).toBe(false); + expect(shifted.results).toMatchObject({ cls: true, targetDeepLinkCls: false }); + }); + it("uses the nearest-rank p75 and fails closed while sample minimum is deferred", () => { expect(percentile75([4, 1, 3, 2])).toBe(3); expect(