From 01a347d21938163c81c9b9742f2c237c3d2c0cc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 11:41:30 +0100 Subject: [PATCH 1/5] Explain incomplete Chrome trace recordings --- README.md | 11 +++++++++++ src/engine/extractors/overview.ts | 13 +++++++++++-- src/engine/extractors/shifts.ts | 3 ++- src/engine/helpers.ts | 17 ++++++++++++++++- src/engine/loader.ts | 8 ++++++++ src/engine/types.ts | 1 + src/formatters/markdown.ts | 3 +++ test/extractors/overview.test.ts | 3 +++ test/extractors/shifts.test.ts | 3 ++- test/loader.test.ts | 19 +++++++++++++++++++ 10 files changed, 76 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8e548d4..43098ab 100644 --- a/README.md +++ b/README.md @@ -552,3 +552,14 @@ npm run format Apache-2.0 Eligibility for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security) is determined by the [Google Open Source Software Vulnerability Reward Program Rules](https://bughunters.google.com/about/rules/open-source/google-open-source-software-vulnerability-reward-program-rules). + +### Recording a compatible trace + +Save the recording from the DevTools Performance panel. For CDP recordings, send +`Tracing.start` on a session attached to the page target. Browser-session recordings +can omit the frame tree required for page analysis. Use `scan` to search their raw +events. + +Include the `loading` category for layout shifts and +`disabled-by-default-v8.cpu_profiler` for sampled JavaScript stacks. In the DevTools +Performance panel, leave JavaScript samples enabled for function attribution. diff --git a/src/engine/extractors/overview.ts b/src/engine/extractors/overview.ts index 8d15292..7bb5a6f 100644 --- a/src/engine/extractors/overview.ts +++ b/src/engine/extractors/overview.ts @@ -14,7 +14,13 @@ import type { TimeRange } from '../../utils/filter.js'; import { microToMilli, round } from '../../utils/units.js'; -import { getMainRendererThread, getPrimaryInsightSet } from '../helpers.js'; +import { + getMainRendererThread, + getPrimaryInsightSet, + hasLayoutShiftData, + MISSING_CPU_SAMPLES, + MISSING_LAYOUT_SHIFT_DATA, +} from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { CwvRating, OverviewResult } from '../types.js'; @@ -126,7 +132,8 @@ export function extractOverview( // CLS let cls: OverviewResult['coreWebVitals']['cls'] = null; const layoutShifts = data.LayoutShifts; - if (layoutShifts) { + const hasShiftData = hasLayoutShiftData(loadedTrace); + if (layoutShifts && hasShiftData) { const score = layoutShifts.sessionMaxScore ?? 0; const worstCluster = layoutShifts.clusters?.[0]?.clusterCumulativeScore; cls = { @@ -234,6 +241,8 @@ export function extractOverview( // 5. Warnings const warnings: string[] = []; + if (!hasShiftData) warnings.push(MISSING_LAYOUT_SHIFT_DATA); + if (mainThread && !mainThread.profileCalls.length) warnings.push(MISSING_CPU_SAMPLES); if (fcp && fcp.rating === 'poor') { warnings.push(`Poor First Contentful Paint: ${fcp.valueMs}ms (threshold: 1800ms)`); } diff --git a/src/engine/extractors/shifts.ts b/src/engine/extractors/shifts.ts index 73635a1..58d1f73 100644 --- a/src/engine/extractors/shifts.ts +++ b/src/engine/extractors/shifts.ts @@ -14,7 +14,7 @@ import { isEventInBounds, type TimeRange } from '../../utils/filter.js'; import { microToMilli, round } from '../../utils/units.js'; -import { getPrimaryInsightSet } from '../helpers.js'; +import { getPrimaryInsightSet, hasLayoutShiftData, MISSING_LAYOUT_SHIFT_DATA } from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { ShiftClusterItem, @@ -158,5 +158,6 @@ export function extractShifts( return { clusters, + ...(!hasLayoutShiftData(loadedTrace) ? { warnings: [MISSING_LAYOUT_SHIFT_DATA] } : {}), }; } diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts index 0d093b6..85e9065 100644 --- a/src/engine/helpers.ts +++ b/src/engine/helpers.ts @@ -12,7 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -import type { ParsedTrace } from './loader.js'; +import type { LoadedTrace, ParsedTrace } from './loader.js'; type MapValue = T extends Map ? V : never; type RendererProcess = MapValue['processes']>; @@ -101,6 +101,21 @@ export function getPrimaryInsightSet( return findInsightEntry(parsedTrace, navigationId)?.model ?? null; } +export const MISSING_LAYOUT_SHIFT_DATA = + 'No layout shift or loading-category events were recorded. Include the loading category to measure layout shifts.'; + +export const MISSING_CPU_SAMPLES = + 'No CPU samples were recorded for this thread. Enable JavaScript samples in DevTools or include disabled-by-default-v8.cpu_profiler.'; + +export function hasLayoutShiftData({ rawEvents, parsedTrace }: LoadedTrace): boolean { + return Boolean(parsedTrace.data.LayoutShifts?.clusters.length) || rawEvents.some( + (event) => + typeof event === 'object' && event !== null && + (('name' in event && event.name === 'LayoutShift') || + ('cat' in event && typeof event.cat === 'string' && event.cat.split(',').includes('loading'))), + ); +} + /** * Traverses an object along a dot-separated property path. */ diff --git a/src/engine/loader.ts b/src/engine/loader.ts index f4a71e9..8faea0b 100644 --- a/src/engine/loader.ts +++ b/src/engine/loader.ts @@ -149,6 +149,14 @@ export async function loadTraceFromFile( }; await model.parse(rawEvents as Parameters[0]); + } catch (error) { + if (error instanceof Error && error.message === 'No frames found in trace data') { + throw new Error( + 'No frames found in trace data. Record with the DevTools Performance panel or send CDP Tracing.start on a page target session. Use scan to search raw events in this file.', + { cause: error }, + ); + } + throw error; } finally { console.warn = origWarn; console.error = origError; diff --git a/src/engine/types.ts b/src/engine/types.ts index 5cd1007..7525266 100644 --- a/src/engine/types.ts +++ b/src/engine/types.ts @@ -255,6 +255,7 @@ export interface ShiftClusterItem { * Layout shifts analysis result. */ export interface ShiftsResult { + warnings?: string[]; clusters: ShiftClusterItem[]; } diff --git a/src/formatters/markdown.ts b/src/formatters/markdown.ts index a1c482f..b9af784 100644 --- a/src/formatters/markdown.ts +++ b/src/formatters/markdown.ts @@ -261,6 +261,9 @@ function formatCulpritLabel(item: { export function formatShiftsMarkdown(shifts: ShiftsResult): string { const lines: string[] = ['# Layout Shifts', '']; + if (shifts.warnings?.length) { + lines.push(...shifts.warnings.map((warning) => `- ${warning}`), ''); + } if (shifts.clusters.length === 0) { lines.push('No layout shifts or clusters detected in trace.'); return lines.join('\n'); diff --git a/test/extractors/overview.test.ts b/test/extractors/overview.test.ts index a2a5dc1..0c7a13c 100644 --- a/test/extractors/overview.test.ts +++ b/test/extractors/overview.test.ts @@ -24,6 +24,9 @@ describe('Overview Extractor', () => { const loaded = await loadTraceFromFile(fixturePath); const overview = extractOverview(loaded); + assert.equal(overview.coreWebVitals.cls, null); + assert.ok(overview.warnings.some((warning) => warning.includes('loading category'))); + assert.ok(overview.warnings.some((warning) => warning.includes('cpu_profiler'))); assert.equal(overview.bounds.minMs, 1000); assert.equal(overview.bounds.maxMs, 1160); assert.equal(overview.bounds.durationMs, 160); diff --git a/test/extractors/shifts.test.ts b/test/extractors/shifts.test.ts index 0054914..19ed696 100644 --- a/test/extractors/shifts.test.ts +++ b/test/extractors/shifts.test.ts @@ -19,12 +19,13 @@ import { extractShifts } from '../../src/engine/extractors/shifts.js'; import { loadTraceFromFile } from '../../src/engine/loader.js'; describe('Layout Shifts Extractor', () => { - test('extractShifts handles empty layout shift traces gracefully', async () => { + test('extractShifts warns when the recording has no layout shift data', async () => { const fixturePath = path.resolve(import.meta.dirname, '../fixtures/basic-trace.json'); const loaded = await loadTraceFromFile(fixturePath); const result = extractShifts(loaded); assert.deepEqual(result.clusters, []); + assert.match(result.warnings?.[0] ?? '', /loading category/); }); test('extractShifts parses cluster score and culprit elements', async () => { diff --git a/test/loader.test.ts b/test/loader.test.ts index 95116bc..ef2cdb4 100644 --- a/test/loader.test.ts +++ b/test/loader.test.ts @@ -13,6 +13,8 @@ // limitations under the License. import assert from 'node:assert/strict'; +import { mkdtemp, rm, writeFile } from 'node:fs/promises'; +import os from 'node:os'; import path from 'node:path'; import test, { describe } from 'node:test'; import { isGzipBuffer, loadTraceFromFile, parseTraceJson } from '../src/engine/loader.js'; @@ -75,6 +77,23 @@ describe('Trace Loader', () => { assert.equal(loaded.parsedTrace.data.Meta.mainFrameURL, 'https://example.com/wrapped'); }); + test('loadTraceFromFile tells users how to record a trace when frame metadata is missing', async (t) => { + const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-')); + t.after(() => rm(dir, { recursive: true, force: true })); + const file = path.join(dir, 'browser.json'); + await writeFile(file, JSON.stringify([{ + name: 'TracingStartedInBrowser', + cat: 'disabled-by-default-devtools.timeline', + ph: 'I', + pid: 1, + tid: 1, + ts: 1000, + args: {}, + }])); + + await assert.rejects(() => loadTraceFromFile(file), { message: /page target session.*scan/ }); + }); + test('loadTraceFromFile throws when file is missing', async () => { await assert.rejects(() => loadTraceFromFile('/non/existent/path.json'), { message: /Trace file not found/, From a508b58b32c1fc75325102c8404380fb47898bc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 12:08:27 +0100 Subject: [PATCH 2/5] Put capture guidance in the agent skill and CLI diagnostics --- README.md | 22 ++++++++++------------ src/engine/extractors/overview.ts | 8 ++++++-- src/engine/extractors/shifts.ts | 7 +++---- src/engine/helpers.ts | 7 +++++-- src/engine/loader.ts | 3 ++- test/cli.test.ts | 26 ++++++++++++++++++++++++++ 6 files changed, 52 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 43098ab..5093c93 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ If your agent environment supports on-demand skills (such as `.gemini/skills/chr ````markdown --- name: chrome-trace-analysis -description: Inspect and query Chrome/DevTools performance trace files and test fixtures (.json, .json.gz) using trace-engine-cli. Use when analyzing trace events, insights, or fixtures. +description: Record or troubleshoot Chrome performance traces and analyze saved .json or .json.gz traces with trace-engine-cli. --- # Chrome & Chromium DevTools Trace Analysis @@ -81,6 +81,15 @@ Use `trace-engine-cli` to inspect, profile, and diagnose performance recordings --- +## Capture a trace + +- In the DevTools Performance panel, record the page activity and save the trace. Leave JavaScript samples enabled when investigating functions. +- With CDP, send `Tracing.start` on a session attached to the page target. Include `loading` for layout shifts and `disabled-by-default-v8.cpu_profiler` for sampled JavaScript stacks. + +If the CLI reports missing page frames, recapture from the page target. Use `trace-engine-cli scan ` if you only have the existing recording and need to search its raw events. + +--- + ## 1. Operational Constraints - **Never parse or search traces manually**: Do not write ad-hoc `node -e`, `python`, `jq`, `zcat`, `gzcat`, `zgrep`, `zless`, or shell loops to inspect or search trace files or fixtures. `trace-engine-cli` handles gzip decompression, multi-file scanning, trace engine parsing, model traversal, and formatting. @@ -552,14 +561,3 @@ npm run format Apache-2.0 Eligibility for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security) is determined by the [Google Open Source Software Vulnerability Reward Program Rules](https://bughunters.google.com/about/rules/open-source/google-open-source-software-vulnerability-reward-program-rules). - -### Recording a compatible trace - -Save the recording from the DevTools Performance panel. For CDP recordings, send -`Tracing.start` on a session attached to the page target. Browser-session recordings -can omit the frame tree required for page analysis. Use `scan` to search their raw -events. - -Include the `loading` category for layout shifts and -`disabled-by-default-v8.cpu_profiler` for sampled JavaScript stacks. In the DevTools -Performance panel, leave JavaScript samples enabled for function attribution. diff --git a/src/engine/extractors/overview.ts b/src/engine/extractors/overview.ts index 7bb5a6f..ac7418a 100644 --- a/src/engine/extractors/overview.ts +++ b/src/engine/extractors/overview.ts @@ -20,6 +20,7 @@ import { hasLayoutShiftData, MISSING_CPU_SAMPLES, MISSING_LAYOUT_SHIFT_DATA, + PAGE_TRACE_CAPTURE_HINT, } from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { CwvRating, OverviewResult } from '../types.js'; @@ -71,14 +72,16 @@ export function extractOverview( const durationMs = round(maxMs - minMs); // 2. Main URL & Navigation Start - const mainUrl = data.Meta.mainFrameURL || null; + const mainFrameId = data.Meta.mainFrameId; + // The engine can retain the previous trace's main frame ID and URL when no frame is recorded. + const hasMainFrame = data.Meta.rendererProcessesByFrame.has(mainFrameId); + const mainUrl = hasMainFrame ? data.Meta.mainFrameURL || null : null; const mainNavs = data.Meta.mainFrameNavigations || []; const allNavs = Array.from(data.Meta.navigationsByNavigationId?.values() || []); const firstNav = mainNavs[0] || allNavs[0]; const navigationStartMs = firstNav ? round(microToMilli(firstNav.ts)) : null; // 3. Core Web Vitals - const mainFrameId = data.Meta.mainFrameId; const pageMetrics = data.PageLoadMetrics?.metricScoresByFrameId?.get(mainFrameId); let fcp: OverviewResult['coreWebVitals']['fcp'] = null; @@ -241,6 +244,7 @@ export function extractOverview( // 5. Warnings const warnings: string[] = []; + if (!hasMainFrame) warnings.push(`No main page frame found. ${PAGE_TRACE_CAPTURE_HINT}`); if (!hasShiftData) warnings.push(MISSING_LAYOUT_SHIFT_DATA); if (mainThread && !mainThread.profileCalls.length) warnings.push(MISSING_CPU_SAMPLES); if (fcp && fcp.rating === 'poor') { diff --git a/src/engine/extractors/shifts.ts b/src/engine/extractors/shifts.ts index 58d1f73..433d7f5 100644 --- a/src/engine/extractors/shifts.ts +++ b/src/engine/extractors/shifts.ts @@ -156,8 +156,7 @@ export function extractShifts( // Sort by score descending clusters.sort((a, b) => b.cumulativeScore - a.cumulativeScore); - return { - clusters, - ...(!hasLayoutShiftData(loadedTrace) ? { warnings: [MISSING_LAYOUT_SHIFT_DATA] } : {}), - }; + const result: ShiftsResult = { clusters }; + if (!hasLayoutShiftData(loadedTrace)) result.warnings = [MISSING_LAYOUT_SHIFT_DATA]; + return result; } diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts index 85e9065..7027fe3 100644 --- a/src/engine/helpers.ts +++ b/src/engine/helpers.ts @@ -101,11 +101,14 @@ export function getPrimaryInsightSet( return findInsightEntry(parsedTrace, navigationId)?.model ?? null; } +export const PAGE_TRACE_CAPTURE_HINT = + 'Record and save a trace from the DevTools Performance panel, or send CDP Tracing.start on a page target session.'; + export const MISSING_LAYOUT_SHIFT_DATA = - 'No layout shift or loading-category events were recorded. Include the loading category to measure layout shifts.'; + 'No layout shift or loading-category events were recorded. To measure layout shifts, recapture in the DevTools Performance panel or include the loading category in CDP.'; export const MISSING_CPU_SAMPLES = - 'No CPU samples were recorded for this thread. Enable JavaScript samples in DevTools or include disabled-by-default-v8.cpu_profiler.'; + 'No CPU samples were recorded for this thread. Recapture with JavaScript samples enabled in the DevTools Performance panel, or include disabled-by-default-v8.cpu_profiler in CDP.'; export function hasLayoutShiftData({ rawEvents, parsedTrace }: LoadedTrace): boolean { return Boolean(parsedTrace.data.LayoutShifts?.clusters.length) || rawEvents.some( diff --git a/src/engine/loader.ts b/src/engine/loader.ts index 8faea0b..11782e4 100644 --- a/src/engine/loader.ts +++ b/src/engine/loader.ts @@ -16,6 +16,7 @@ import fs from 'node:fs'; import path from 'node:path'; import zlib from 'node:zlib'; import { loadTraceEngine, type TraceEngine } from './adapter.js'; +import { PAGE_TRACE_CAPTURE_HINT } from './helpers.js'; export type ParsedTrace = NonNullable< ReturnType['parsedTrace']> @@ -152,7 +153,7 @@ export async function loadTraceFromFile( } catch (error) { if (error instanceof Error && error.message === 'No frames found in trace data') { throw new Error( - 'No frames found in trace data. Record with the DevTools Performance panel or send CDP Tracing.start on a page target session. Use scan to search raw events in this file.', + `No frames found in trace data. ${PAGE_TRACE_CAPTURE_HINT} Use scan to search raw events in this file.`, { cause: error }, ); } diff --git a/test/cli.test.ts b/test/cli.test.ts index cdcded2..ad6f469 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -13,6 +13,8 @@ // limitations under the License. import assert from 'node:assert/strict'; +import { mkdtemp, rm, writeFile } from 'node:fs/promises'; +import os from 'node:os'; import path from 'node:path'; import test, { describe } from 'node:test'; import { runCli } from '../src/cli.js'; @@ -38,6 +40,7 @@ describe('CLI Dispatcher', () => { assert.ok(output.includes('bounds:')); assert.ok(output.includes('https://example.com/test')); assert.ok(output.includes('Drill-down commands:')); + assert.doesNotMatch(output, /No main page frame found/); }); test('runs explicit overview command in markdown mode', async () => { @@ -311,4 +314,27 @@ describe('CLI Dispatcher', () => { ]); assert.ok(output.includes('https://example.com/styles.css')); }); + + test('offers a recapture hint when a trace parses without main frame metadata', async (t) => { + const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-')); + t.after(() => rm(dir, { recursive: true, force: true })); + const file = path.join(dir, 'no-frames.json'); + await writeFile(file, JSON.stringify([{ + name: 'TracingStartedInBrowser', + cat: 'disabled-by-default-devtools.timeline', + ph: 'I', + pid: 1, + tid: 1, + ts: 1000, + args: { data: { frames: [] } }, + }])); + + const args = ['node', 'trace-engine-cli', 'overview']; + const validFixture = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json'); + await captureCliOutput([...args, validFixture]); + + const output = await captureCliOutput([...args, file]); + assert.match(output, /^mainUrl: null$/m); + assert.match(output, /No main page frame found.*DevTools Performance panel.*page target session/); + }); }); From fe7e47ade326aa44407df779f5ff0d799c5ff57b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 12:17:51 +0100 Subject: [PATCH 3/5] Restore trace analysis skill scope and move capture caveats --- README.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5093c93..92bca83 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ If your agent environment supports on-demand skills (such as `.gemini/skills/chr ````markdown --- name: chrome-trace-analysis -description: Record or troubleshoot Chrome performance traces and analyze saved .json or .json.gz traces with trace-engine-cli. +description: Inspect and query saved Chrome/DevTools performance traces and test fixtures (.json, .json.gz) with trace-engine-cli. Use when analyzing trace events, CPU activity, Web Vitals, or diagnostic insights, or investigating missing capture data. --- # Chrome & Chromium DevTools Trace Analysis @@ -81,15 +81,6 @@ Use `trace-engine-cli` to inspect, profile, and diagnose performance recordings --- -## Capture a trace - -- In the DevTools Performance panel, record the page activity and save the trace. Leave JavaScript samples enabled when investigating functions. -- With CDP, send `Tracing.start` on a session attached to the page target. Include `loading` for layout shifts and `disabled-by-default-v8.cpu_profiler` for sampled JavaScript stacks. - -If the CLI reports missing page frames, recapture from the page target. Use `trace-engine-cli scan ` if you only have the existing recording and need to search its raw events. - ---- - ## 1. Operational Constraints - **Never parse or search traces manually**: Do not write ad-hoc `node -e`, `python`, `jq`, `zcat`, `gzcat`, `zgrep`, `zless`, or shell loops to inspect or search trace files or fixtures. `trace-engine-cli` handles gzip decompression, multi-file scanning, trace engine parsing, model traversal, and formatting. @@ -235,6 +226,14 @@ trace-engine-cli scan fixtures/traces/ --cat devtools.timeline --phase X 2. Inspect navigations and insight set IDs: `trace-engine-cli navigations ` 3. Inspect relevant subsystem: `trace-engine-cli shifts --events`, `trace-engine-cli network `, or `trace-engine-cli insights --category ` 4. Inspect raw event payloads: `trace-engine-cli events --name --fields ` + +--- + +## 5. Capture Caveats + +- **Missing page frames**. Browser-target CDP recordings can omit frame metadata. Record and save a trace from the DevTools Performance panel, or send `Tracing.start` on a CDP session attached to the page target. Use `trace-engine-cli scan ` to search raw events in an existing recording. +- **Missing layout-shift data**. Include the `loading` category in CDP recordings for CLS analysis. +- **Missing JavaScript samples**. Leave JavaScript sampling enabled in DevTools or include `disabled-by-default-v8.cpu_profiler` in CDP recordings for sampled call stacks. ```` From 75a5b82e16dd2ab64d9725797b44330d6c0ba76a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 12:37:46 +0100 Subject: [PATCH 4/5] Use the requested trace analysis skill description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 92bca83..4a27ca9 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ If your agent environment supports on-demand skills (such as `.gemini/skills/chr ````markdown --- name: chrome-trace-analysis -description: Inspect and query saved Chrome/DevTools performance traces and test fixtures (.json, .json.gz) with trace-engine-cli. Use when analyzing trace events, CPU activity, Web Vitals, or diagnostic insights, or investigating missing capture data. +description: Inspect and query saved Chrome/DevTools performance trace files and test fixtures (.json, .json.gz) using trace-engine-cli. Use when analyzing trace events, CPU activity, Web Vitals, or diagnostic insights. --- # Chrome & Chromium DevTools Trace Analysis From 7b1335835164dd41a7621b08a55d08427c01088d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 14:06:32 +0100 Subject: [PATCH 5/5] Scope layout shift capture warnings to navigation traces --- src/engine/extractors/overview.ts | 10 +++++----- src/engine/extractors/shifts.ts | 10 ++++++++-- src/engine/helpers.ts | 22 ++++++++++++++++------ test/cli.test.ts | 10 +++++++--- test/extractors/overview.test.ts | 15 +++++++++++++++ test/loader.test.ts | 5 +++-- 6 files changed, 54 insertions(+), 18 deletions(-) diff --git a/src/engine/extractors/overview.ts b/src/engine/extractors/overview.ts index ac7418a..6928192 100644 --- a/src/engine/extractors/overview.ts +++ b/src/engine/extractors/overview.ts @@ -17,10 +17,10 @@ import { microToMilli, round } from '../../utils/units.js'; import { getMainRendererThread, getPrimaryInsightSet, - hasLayoutShiftData, MISSING_CPU_SAMPLES, - MISSING_LAYOUT_SHIFT_DATA, PAGE_TRACE_CAPTURE_HINT, + shouldWarnAboutLayoutShiftCapture, + UNCONFIRMED_LAYOUT_SHIFT_CAPTURE, } from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { CwvRating, OverviewResult } from '../types.js'; @@ -135,8 +135,8 @@ export function extractOverview( // CLS let cls: OverviewResult['coreWebVitals']['cls'] = null; const layoutShifts = data.LayoutShifts; - const hasShiftData = hasLayoutShiftData(loadedTrace); - if (layoutShifts && hasShiftData) { + const warnAboutShiftCapture = shouldWarnAboutLayoutShiftCapture(loadedTrace); + if (layoutShifts && !warnAboutShiftCapture) { const score = layoutShifts.sessionMaxScore ?? 0; const worstCluster = layoutShifts.clusters?.[0]?.clusterCumulativeScore; cls = { @@ -245,7 +245,7 @@ export function extractOverview( // 5. Warnings const warnings: string[] = []; if (!hasMainFrame) warnings.push(`No main page frame found. ${PAGE_TRACE_CAPTURE_HINT}`); - if (!hasShiftData) warnings.push(MISSING_LAYOUT_SHIFT_DATA); + if (warnAboutShiftCapture) warnings.push(UNCONFIRMED_LAYOUT_SHIFT_CAPTURE); if (mainThread && !mainThread.profileCalls.length) warnings.push(MISSING_CPU_SAMPLES); if (fcp && fcp.rating === 'poor') { warnings.push(`Poor First Contentful Paint: ${fcp.valueMs}ms (threshold: 1800ms)`); diff --git a/src/engine/extractors/shifts.ts b/src/engine/extractors/shifts.ts index 433d7f5..8a851d3 100644 --- a/src/engine/extractors/shifts.ts +++ b/src/engine/extractors/shifts.ts @@ -14,7 +14,11 @@ import { isEventInBounds, type TimeRange } from '../../utils/filter.js'; import { microToMilli, round } from '../../utils/units.js'; -import { getPrimaryInsightSet, hasLayoutShiftData, MISSING_LAYOUT_SHIFT_DATA } from '../helpers.js'; +import { + getPrimaryInsightSet, + shouldWarnAboutLayoutShiftCapture, + UNCONFIRMED_LAYOUT_SHIFT_CAPTURE, +} from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { ShiftClusterItem, @@ -157,6 +161,8 @@ export function extractShifts( clusters.sort((a, b) => b.cumulativeScore - a.cumulativeScore); const result: ShiftsResult = { clusters }; - if (!hasLayoutShiftData(loadedTrace)) result.warnings = [MISSING_LAYOUT_SHIFT_DATA]; + if (shouldWarnAboutLayoutShiftCapture(loadedTrace)) { + result.warnings = [UNCONFIRMED_LAYOUT_SHIFT_CAPTURE]; + } return result; } diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts index 7027fe3..2c0b810 100644 --- a/src/engine/helpers.ts +++ b/src/engine/helpers.ts @@ -104,18 +104,28 @@ export function getPrimaryInsightSet( export const PAGE_TRACE_CAPTURE_HINT = 'Record and save a trace from the DevTools Performance panel, or send CDP Tracing.start on a page target session.'; -export const MISSING_LAYOUT_SHIFT_DATA = - 'No layout shift or loading-category events were recorded. To measure layout shifts, recapture in the DevTools Performance panel or include the loading category in CDP.'; +export const UNCONFIRMED_LAYOUT_SHIFT_CAPTURE = + 'No layout shifts or loading-category events were observed in this navigation recording. If you used CDP, check whether the loading category was enabled.'; export const MISSING_CPU_SAMPLES = 'No CPU samples were recorded for this thread. Recapture with JavaScript samples enabled in the DevTools Performance panel, or include disabled-by-default-v8.cpu_profiler in CDP.'; -export function hasLayoutShiftData({ rawEvents, parsedTrace }: LoadedTrace): boolean { - return Boolean(parsedTrace.data.LayoutShifts?.clusters.length) || rawEvents.some( +const LOADING_CATEGORY = /(?:^|,)loading(?:,|$)/; + +export function shouldWarnAboutLayoutShiftCapture({ + rawEvents, + parsedTrace, +}: LoadedTrace): boolean { + const { Meta, LayoutShifts } = parsedTrace.data; + // A recording of an already-loaded page may contain no loading events even with CLS enabled. + if (!Meta.mainFrameNavigations.length || LayoutShifts?.clusters.length) return false; + + return !rawEvents.some( (event) => - typeof event === 'object' && event !== null && + typeof event === 'object' && + event !== null && (('name' in event && event.name === 'LayoutShift') || - ('cat' in event && typeof event.cat === 'string' && event.cat.split(',').includes('loading'))), + ('cat' in event && typeof event.cat === 'string' && LOADING_CATEGORY.test(event.cat))), ); } diff --git a/test/cli.test.ts b/test/cli.test.ts index ad6f469..0449eec 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -319,7 +319,7 @@ describe('CLI Dispatcher', () => { const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-')); t.after(() => rm(dir, { recursive: true, force: true })); const file = path.join(dir, 'no-frames.json'); - await writeFile(file, JSON.stringify([{ + const tracingStarted = { name: 'TracingStartedInBrowser', cat: 'disabled-by-default-devtools.timeline', ph: 'I', @@ -327,7 +327,8 @@ describe('CLI Dispatcher', () => { tid: 1, ts: 1000, args: { data: { frames: [] } }, - }])); + }; + await writeFile(file, JSON.stringify([tracingStarted])); const args = ['node', 'trace-engine-cli', 'overview']; const validFixture = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json'); @@ -335,6 +336,9 @@ describe('CLI Dispatcher', () => { const output = await captureCliOutput([...args, file]); assert.match(output, /^mainUrl: null$/m); - assert.match(output, /No main page frame found.*DevTools Performance panel.*page target session/); + assert.match( + output, + /No main page frame found.*DevTools Performance panel.*page target session/, + ); }); }); diff --git a/test/extractors/overview.test.ts b/test/extractors/overview.test.ts index 0c7a13c..1dce1ca 100644 --- a/test/extractors/overview.test.ts +++ b/test/extractors/overview.test.ts @@ -16,6 +16,7 @@ import assert from 'node:assert/strict'; import path from 'node:path'; import test, { describe } from 'node:test'; import { extractOverview } from '../../src/engine/extractors/overview.js'; +import { extractShifts } from '../../src/engine/extractors/shifts.js'; import { loadTraceFromFile } from '../../src/engine/loader.js'; describe('Overview Extractor', () => { @@ -104,4 +105,18 @@ describe('Overview Extractor', () => { worstClusterScore: 0.15, }); }); + + test('reports zero CLS without capture warnings for a recording without navigation', async () => { + const fixture = path.resolve(import.meta.dirname, '../fixtures/wrapped-trace.json'); + const loaded = await loadTraceFromFile(fixture); + + const overview = extractOverview(loaded); + assert.equal(overview.navigationStartMs, null); + assert.equal(overview.coreWebVitals.cls?.value, 0); + assert.doesNotMatch(overview.warnings.join(' '), /loading category/); + + const shifts = extractShifts(loaded); + assert.deepEqual(shifts.clusters, []); + assert.equal(shifts.warnings, undefined); + }); }); diff --git a/test/loader.test.ts b/test/loader.test.ts index ef2cdb4..08d1eb9 100644 --- a/test/loader.test.ts +++ b/test/loader.test.ts @@ -81,7 +81,7 @@ describe('Trace Loader', () => { const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-')); t.after(() => rm(dir, { recursive: true, force: true })); const file = path.join(dir, 'browser.json'); - await writeFile(file, JSON.stringify([{ + const tracingStarted = { name: 'TracingStartedInBrowser', cat: 'disabled-by-default-devtools.timeline', ph: 'I', @@ -89,7 +89,8 @@ describe('Trace Loader', () => { tid: 1, ts: 1000, args: {}, - }])); + }; + await writeFile(file, JSON.stringify([tracingStarted])); await assert.rejects(() => loadTraceFromFile(file), { message: /page target session.*scan/ }); });