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
+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();