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:
@@ -20,7 +20,7 @@
|
||||
},
|
||||
"metrics": {
|
||||
"type": "object",
|
||||
"required": ["lcpMs", "cls", "namedInteractionMs"]
|
||||
"required": ["lcpMs", "cls", "namedInteractionMs", "targetDeepLinkCls"]
|
||||
},
|
||||
"thresholds": { "type": "object" },
|
||||
"fixtures": { "type": "array", "minItems": 2 },
|
||||
|
||||
@@ -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 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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(
|
||||
|
||||
Reference in New Issue
Block a user