From 138c195fcd67437ae747e52e853b2f403ca3f7a2 Mon Sep 17 00:00:00 2001
From: DongHyeonka
Date: Thu, 5 Nov 2026 22:15:46 +0900
Subject: [PATCH] =?UTF-8?q?fix(examples):=20=EB=A6=B4=EB=A6=AC=EC=8A=A4=20?=
=?UTF-8?q?=EC=8B=A0=EC=9B=90=20=EC=B9=B8=EC=9D=98=20=EC=9E=90=EB=A6=AC?=
=?UTF-8?q?=EB=A5=BC=20=EB=AF=B8=EB=A6=AC=20=EC=9E=A1=EA=B3=A0=20lab?=
=?UTF-8?q?=EC=9D=B4=20=EB=8C=80=EC=83=81=20=ED=99=94=EB=A9=B4=20=EC=A7=81?=
=?UTF-8?q?=EC=A0=91=20=EC=A7=84=EC=9E=85=20CLS=EB=A5=BC=20=EC=9E=B0?=
=?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지
릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로
바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래
section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift
16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는
hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느
게이트도 보지 않는다.
고른 방법:
- 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합
다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다."
/ "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도
한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미
`main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던
대기가 값이 채워진 뒤로 유지된다.
- lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network
idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값,
context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls
임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다.
- 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는
빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면
lab 판정이 실패한다.
버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기
포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 —
CLS 정의와 달라져 field 값과 비교할 수 없다.
위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초)
늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은
shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은
lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어
"런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면
문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에
새 칸을 필수로 더했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(lab.json metrics.targetDeepLinkCls가 0인지)
Refs: 1105/15-01
---
config/schemas/lab-performance.schema.json | 2 +-
docs/operations/performance-evidence.md | 5 ++
scripts/lib/performance-budgets.ts | 16 +++-
scripts/test-performance.ts | 88 +++++++++++++++++--
.../examples/platform-overview-page.tsx | 39 ++++++--
.../starter-platform-overview-page.test.tsx | 61 ++++++++++++-
tests/unit/performance-budgets.test.ts | 32 ++++++-
7 files changed, 221 insertions(+), 22 deletions(-)
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(