fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다

문제: 플랫폼 구성 화면(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
This commit is contained in:
DongHyeonka
2026-11-06 01:23:48 +09:00
parent e02f252d57
commit 138c195fcd
7 changed files with 221 additions and 22 deletions
+1 -1
View File
@@ -20,7 +20,7 @@
},
"metrics": {
"type": "object",
"required": ["lcpMs", "cls", "namedInteractionMs"]
"required": ["lcpMs", "cls", "namedInteractionMs", "targetDeepLinkCls"]
},
"thresholds": { "type": "object" },
"fixtures": { "type": "array", "minItems": 2 },
+5
View File
@@ -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 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며
+15 -1
View File
@@ -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<Record<string, unknown>>;
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),
+79 -9
View File
@@ -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<RunMetrics> {
// 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<RunMetrics> {
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<RunMetrics> {
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<Omit<RunMetrics, "targetDeepLinkCls">> {
// 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<RunMetrics> {
}
}
/**
* 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<number> {
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();
@@ -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 (
<>
<Metric label="빌드" value={status} />
<Metric label="릴리스" value="—" />
<Metric label="설정 스키마" value="—" hint="—" />
<Metric label="계약 집합 다이제스트" value="—" hint="—" />
</>
);
}
type RouteRow = (typeof ROUTE_REGISTRY)[keyof typeof ROUTE_REGISTRY];
const ROUTE_COLUMNS: readonly DataTableColumn<RouteRow>[] = Object.freeze([
@@ -419,10 +436,18 @@ export function PlatformOverviewPage({
부팅 시 경계 검사를 통과한 런타임 설정과 릴리스 매니페스트에서 옵니다.
</p>
</header>
<dl className="platform-metric-grid" aria-live="polite">
{release === "failed" ? (
<Metric label="상태" value="런타임 정보를 확인하지 못했습니다." />
) : 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). */}
<dl
className="platform-metric-grid"
aria-live="polite"
aria-busy={release === null}
>
{release !== null && release !== "failed" ? (
<>
<Metric label="빌드" value={release.buildId} />
<Metric label="릴리스" value={release.releaseId} />
@@ -450,7 +475,11 @@ export function PlatformOverviewPage({
/>
</>
) : (
<Metric label="상태" value="런타임 정보를 확인하고 있습니다." />
<ReleaseMetricsPlaceholder
status={
release === "failed" ? "확인하지 못했습니다." : "확인하고 있습니다."
}
/>
)}
</dl>
</section>
@@ -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<typeof summary>((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");
});
});
+30 -2
View File
@@ -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(