diff --git a/README.md b/README.md index 8e548d4..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 Chrome/DevTools performance trace files and test fixtures (.json, .json.gz) using trace-engine-cli. Use when analyzing trace events, insights, or fixtures. +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 @@ -226,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. ```` diff --git a/src/engine/extractors/overview.ts b/src/engine/extractors/overview.ts index 8d15292..6928192 100644 --- a/src/engine/extractors/overview.ts +++ b/src/engine/extractors/overview.ts @@ -14,7 +14,14 @@ import type { TimeRange } from '../../utils/filter.js'; import { microToMilli, round } from '../../utils/units.js'; -import { getMainRendererThread, getPrimaryInsightSet } from '../helpers.js'; +import { + getMainRendererThread, + getPrimaryInsightSet, + MISSING_CPU_SAMPLES, + 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'; @@ -65,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; @@ -126,7 +135,8 @@ export function extractOverview( // CLS let cls: OverviewResult['coreWebVitals']['cls'] = null; const layoutShifts = data.LayoutShifts; - if (layoutShifts) { + const warnAboutShiftCapture = shouldWarnAboutLayoutShiftCapture(loadedTrace); + if (layoutShifts && !warnAboutShiftCapture) { const score = layoutShifts.sessionMaxScore ?? 0; const worstCluster = layoutShifts.clusters?.[0]?.clusterCumulativeScore; cls = { @@ -234,6 +244,9 @@ export function extractOverview( // 5. Warnings const warnings: string[] = []; + if (!hasMainFrame) warnings.push(`No main page frame found. ${PAGE_TRACE_CAPTURE_HINT}`); + 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 73635a1..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 } from '../helpers.js'; +import { + getPrimaryInsightSet, + shouldWarnAboutLayoutShiftCapture, + UNCONFIRMED_LAYOUT_SHIFT_CAPTURE, +} from '../helpers.js'; import type { LoadedTrace } from '../loader.js'; import type { ShiftClusterItem, @@ -156,7 +160,9 @@ export function extractShifts( // Sort by score descending clusters.sort((a, b) => b.cumulativeScore - a.cumulativeScore); - return { - clusters, - }; + const result: ShiftsResult = { clusters }; + if (shouldWarnAboutLayoutShiftCapture(loadedTrace)) { + result.warnings = [UNCONFIRMED_LAYOUT_SHIFT_CAPTURE]; + } + return result; } diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts index 0d093b6..2c0b810 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,34 @@ 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 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.'; + +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 && + (('name' in event && event.name === 'LayoutShift') || + ('cat' in event && typeof event.cat === 'string' && LOADING_CATEGORY.test(event.cat))), + ); +} + /** * Traverses an object along a dot-separated property path. */ diff --git a/src/engine/loader.ts b/src/engine/loader.ts index f4a71e9..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']> @@ -149,6 +150,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. ${PAGE_TRACE_CAPTURE_HINT} 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/cli.test.ts b/test/cli.test.ts index cdcded2..0449eec 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,31 @@ 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'); + const tracingStarted = { + name: 'TracingStartedInBrowser', + cat: 'disabled-by-default-devtools.timeline', + ph: 'I', + pid: 1, + 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'); + 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/, + ); + }); }); diff --git a/test/extractors/overview.test.ts b/test/extractors/overview.test.ts index a2a5dc1..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', () => { @@ -24,6 +25,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); @@ -101,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/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..08d1eb9 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,24 @@ 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'); + const tracingStarted = { + name: 'TracingStartedInBrowser', + cat: 'disabled-by-default-devtools.timeline', + ph: 'I', + pid: 1, + tid: 1, + ts: 1000, + args: {}, + }; + await writeFile(file, JSON.stringify([tracingStarted])); + + 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/,