Files
clean-architecture-frontend…/tests/support/browser/preload-use.ts
T
DongHyeonka aad005cbce fix(test): 브라우저 테스트가 WebKit의 3초 preload 추정 대신 실제 사용을 검사한다
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).

고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
  console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
  "preload한 script가 실제로 실행됐는가"를 본다.
  - 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
    MutationObserver로 적고, 끝에 남은 link도 더한다.
  - page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
    문장 하나를 앞에 붙인다.
  - test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
    실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
  받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
  문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
  "참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
  - script가 아닌 preload는 `preloadunverifiable:<as>:`.
  - Service Worker가 문서를 제어할 때 만든 preload는
    `preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
    page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
    release manifest의 sha256 대조가 깨진다.
  - route.fetch가 세 번 실패해 표시 없이 넘어간 script는
    `preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
    route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
    reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
  - boot-module-failure: 깨진 build의 boot 정적 closure.
  - old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
    허용이 WebKit 경고 문구로만 있었다.
  - service-worker-update: worker 제어 중 preload만.
  - production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
    fulfillBuildScript를 쓴다.

버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
  test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
  늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.

위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
  service-worker-update만 허용).

검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
  - 변이 test는 세 엔진 모두 Expected
    ["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
  - 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
    …/reference-schemas-DICBcHlO.js was preloaded using link preload but not
    used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
  - 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
  - 새 fixture: 3/3 실패,
    "preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
  - 이전 fixture: webkit 실패.
  - 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
    (probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
2026-11-05 08:13:56 +09:00

234 lines
8.9 KiB
TypeScript

import type { APIResponse, Frame, Page, Route } from "@playwright/test";
/**
* 1103/11-09. Which link-preloaded scripts a page actually ran.
*
* WebKit warns about a preload no request has used three seconds after the
* load event, once. That is a timing guess: a route entered just before the
* check preloads chunks the page runs a moment later, and a preload the page
* never runs goes unreported when the test ends first. This check does not
* depend on when it runs, and it is the same in every engine:
*
* - Every `<link rel=modulepreload>` and `<link rel=preload>` a document gets
* is recorded (a MutationObserver from before the document's first byte,
* plus the links still in the document at the end).
* - Every build script the page receives (`/assets/*.js`) starts with one
* statement that records its own URL when it is evaluated. A preload only
* fetches (WebKit, Firefox) or fetches and parses (Chromium); none of them
* evaluates, so a preloaded chunk counts as used only once the module graph
* ran it.
* - At the end, a preloaded script that was not run is `preloadunused:`. The
* check waits for a dynamic import still in flight (up to `timeoutMs`).
*
* What it cannot see fails closed, under its own name:
* - `preloadunverifiable:<as>:` a preload of anything but a script.
* - `preloadunverifiable:service-worker:` a script preloaded while a Service
* Worker controlled the document. The worker answers the page's requests,
* so this route never sees them; marking what the worker fetches would
* change bytes it checks against the release manifest.
* - `preloadunverifiable:unmarked:` a script this route could not fetch to
* mark (the browser got it unmarked).
* A script outside `/assets/`, or one a test's own handler fulfilled without
* `fulfillBuildScript`, never records itself and is `preloadunused:`.
*
* Only the documents open at the end are checked: a document the test
* navigated away from takes its records with it.
*/
const BUILD_SCRIPT = /\/assets\/[^/?#]+\.js$/u;
const STATE = "__e2ePreloadUse";
const FETCH_ATTEMPTS = 3;
type Preload = Readonly<{ href: string; kind: string }>;
type FrameRecord = Readonly<{
preloaded: readonly Preload[];
evaluated: readonly string[];
}>;
export type PreloadUseCheck = Readonly<{
/** Every preloaded URL path the open documents recorded. */
preloaded: readonly string[];
/** `preloadunused:<path>` and `preloadunverifiable:<reason>:<path>` lines. */
failures: readonly string[];
}>;
export type PreloadUseTracker = Readonly<{
check(options?: Readonly<{ timeoutMs?: number }>): Promise<PreloadUseCheck>;
}>;
/** Runs in every document before its first byte. */
function recordPreloads(state: string): void {
const record = {
preloaded: new Map<string, string>(),
evaluated: new Set<string>(),
};
Object.defineProperty(globalThis, state, { value: record });
const remember = (node: Node) => {
if (!(node instanceof HTMLLinkElement) || node.href === "") return;
const script =
node.relList.contains("modulepreload") ||
(node.relList.contains("preload") && node.as === "script");
if (script) {
const controlled = navigator.serviceWorker?.controller != null;
record.preloaded.set(node.href, controlled ? "service-worker" : "script");
} else if (node.relList.contains("preload")) {
record.preloaded.set(node.href, node.as || "unknown");
}
};
new MutationObserver((mutations) => {
for (const mutation of mutations) {
for (const node of mutation.addedNodes) {
remember(node);
if (node instanceof Element) node.querySelectorAll("link").forEach(remember);
}
}
}).observe(document, { childList: true, subtree: true });
}
function readRecord(state: string): FrameRecord {
const record = (globalThis as Record<string, unknown>)[state] as
| { preloaded: Map<string, string>; evaluated: Set<string> }
| undefined;
const preloaded = new Map(record?.preloaded);
const controlled = navigator.serviceWorker?.controller != null;
for (const link of document.querySelectorAll("link")) {
if (link.href === "" || preloaded.has(link.href)) continue;
if (
link.relList.contains("modulepreload") ||
(link.relList.contains("preload") && link.as === "script")
) {
preloaded.set(link.href, controlled ? "service-worker" : "script");
} else if (link.relList.contains("preload")) {
preloaded.set(link.href, link.as || "unknown");
}
}
return {
preloaded: [...preloaded].map(([href, kind]) => ({ href, kind })),
evaluated: [...(record?.evaluated ?? [])],
};
}
/**
* Fulfills a request with `response`, the evaluation mark added when it is a
* build script. A test that fulfills build scripts itself (for example to add
* headers) uses this, or every preload of those scripts reads as unused.
*/
export async function fulfillBuildScript(
route: Route,
response: APIResponse,
headers: Readonly<Record<string, string>> = response.headers(),
): Promise<void> {
const url = route.request().url();
const type = response.headers()["content-type"] ?? "";
if (
!BUILD_SCRIPT.test(new URL(url).pathname) ||
response.status() !== 200 ||
!/javascript/u.test(type)
) {
return route.fulfill({ response, headers: { ...headers } });
}
const marked = { ...headers };
delete marked["content-length"];
delete marked["content-encoding"];
await route.fulfill({
status: response.status(),
headers: marked,
// Valid in a module and in a classic script; a no-op where the page's
// record does not exist (a worker).
body: `globalThis.${STATE}?.evaluated.add(${JSON.stringify(url)});\n${await response.text()}`,
});
}
function pathOf(href: string, origin: string): string {
const url = new URL(href);
return url.origin === origin ? `${url.pathname}${url.search}` : href;
}
export async function trackPreloadUse(page: Page): Promise<PreloadUseTracker> {
/** URL → why it reached the browser without the mark. */
const unmarked = new Map<string, string>();
async function markEvaluation(route: Route): Promise<void> {
if (route.request().method() !== "GET") return route.fallback();
let lastError: unknown;
for (let attempt = 0; attempt < FETCH_ATTEMPTS; attempt += 1) {
let response: APIResponse;
try {
response = await route.fetch();
} catch (error) {
lastError = error;
continue;
}
return fulfillBuildScript(route, response);
}
// The browser gets the request as the server answers it, unmarked.
unmarked.set(
route.request().url(),
String(lastError).split("\n")[0] ?? "fetch failed",
);
return route.continue();
}
async function frameResult(frame: Frame): Promise<
Readonly<{ preloaded: string[]; failures: string[] }> | undefined
> {
if (frame.isDetached()) return { preloaded: [], failures: [] };
let record: FrameRecord;
let origin: string;
try {
[record, origin] = await Promise.all([
frame.evaluate(readRecord, STATE),
frame.evaluate(() => location.origin),
]);
} catch {
// The document is being replaced; read the next one.
return undefined;
}
const evaluated = new Set(record.evaluated);
const failures: string[] = [];
for (const { href, kind } of record.preloaded) {
const where = pathOf(href, origin);
if (kind !== "script" && kind !== "service-worker") {
failures.push(`preloadunverifiable:${kind}:${where}`);
} else if (evaluated.has(href)) {
continue;
} else if (unmarked.has(href)) {
failures.push(`preloadunverifiable:unmarked:${where}: ${unmarked.get(href)}`);
} else if (kind === "service-worker") {
failures.push(`preloadunverifiable:service-worker:${where}`);
} else {
failures.push(`preloadunused:${where}`);
}
}
return {
preloaded: record.preloaded.map(({ href }) => pathOf(href, origin)),
failures,
};
}
await page.addInitScript(recordPreloads, STATE);
await page.route((url) => BUILD_SCRIPT.test(url.pathname), markEvaluation);
return Object.freeze({
async check({ timeoutMs = 5_000 } = {}) {
const deadline = Date.now() + timeoutMs;
for (;;) {
if (page.isClosed()) return { preloaded: [], failures: [] };
const frames = await Promise.all(page.frames().map(frameResult));
const settled = frames.every((frame) => frame !== undefined);
const preloaded = frames.flatMap((frame) => frame?.preloaded ?? []).sort();
const failures = frames.flatMap((frame) => frame?.failures ?? []).sort();
if ((settled && failures.length === 0) || Date.now() >= deadline) {
return {
preloaded,
failures: settled
? failures
: [...failures, "preloadcheck:unreadable-document"],
};
}
await new Promise((resolve) => setTimeout(resolve, 100));
}
},
});
}