Skip to content

Chrome DevTools for coding agents

feat(performance): chunked trace buffer parser for large recordings (#2721)

Jack Franklin23b9a480010d
diff --git a/src/processors/ChunkedTraceParser.ts b/src/processors/ChunkedTraceParser.ts
new file mode 100644
index 00000000..b74bdd84
--- /dev/null
+++ b/src/processors/ChunkedTraceParser.ts
@@ -0,0 +1,470 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Provides memory-efficient chunked parsing for Chrome DevTools trace files.
+ * Large performance traces can exceed V8 string length limits and cause heap exhaustion.
+ * This parser scans raw byte buffers, finds event boundaries, and parses events in batches.
+ */
+
+import type {DevTools} from '../third_party/index.js';
+
+/**
+ * Represents the output of a parsed trace buffer.
+ */
+export interface ParsedTraceBuffer {
+ /** The collection of parsed trace events extracted from the buffer. */
+ events: DevTools.TraceEngine.Types.Events.Event[];
+ /** Optional file metadata extracted from the trace object container. */
+ metadata?: DevTools.TraceEngine.Types.File.MetaData;
+}
+
+/**
+ * Configuration options for trace buffer parsing.
+ */
+export interface ParseTraceBufferOptions {
+ /**
+ * The maximum number of trace events to decode and parse in a single batch.
+ * Lower values reduce memory spikes during string decoding.
+ * Higher values decrease the total number of JSON.parse calls.
+ * Non-positive or non-finite values fall back to the default.
+ * @defaultValue 10_000
+ */
+ eventsPerBatch?: number;
+ /**
+ * The maximum byte size of raw trace event data to decode in a single batch.
+ * Flushes batches before V8 string length limits are approached.
+ * Non-positive or non-finite values fall back to the default.
+ * @defaultValue 33_554_432 (32 MB)
+ */
+ maxBatchBytes?: number;
+}
+
+interface BatchConfig {
+ eventsPerBatch: number;
+ maxBatchBytes: number;
+ decoder: TextDecoder;
+}
+
+const DEFAULT_EVENTS_PER_BATCH = 10_000;
+const DEFAULT_MAX_BATCH_BYTES = 32 * 1024 * 1024;
+
+// ASCII character byte constants used by the state machine.
+// All values are strictly less than 0x80 (standard ASCII).
+// In UTF-8 encoding, multi-byte code units only contain bytes from 0x80 through 0xFF.
+// Therefore, scanning for these byte values will never match bytes inside multi-byte characters.
+const BYTE_QUOTE = 0x22;
+const BYTE_BACKSLASH = 0x5c;
+const BYTE_OPEN_BRACE = 0x7b;
+const BYTE_CLOSE_BRACE = 0x7d;
+const BYTE_OPEN_BRACKET = 0x5b;
+const BYTE_CLOSE_BRACKET = 0x5d;
+const BYTE_COLON = 0x3a;
+const BYTE_COMMA = 0x2c;
+
+/**
+ * Advances past any RFC 8259 JSON whitespace bytes.
+ *
+ * @param buffer - The trace byte buffer to inspect.
+ * @param start - The buffer index where scanning begins.
+ * @returns The index of the first non-whitespace byte, or the buffer length if the buffer ends.
+ */
+function skipWhitespace(
+ buffer: Uint8Array<ArrayBufferLike>,
+ start: number,
+): number {
+ let i = start;
+ while (i < buffer.length) {
+ const byte = buffer[i];
+ if (byte !== 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d) {
+ break;
+ }
+ i++;
+ }
+ return i;
+}
+
+/**
+ * Scans past a JSON string starting at the opening quotation mark.
+ *
+ * @param buffer - The trace byte buffer to scan.
+ * @param startQuotePos - The buffer index of the opening quotation mark.
+ * @returns The index immediately following the closing quotation mark.
+ * @throws {SyntaxError} If the string is unterminated before the end of the buffer.
+ */
+function skipString(
+ buffer: Uint8Array<ArrayBufferLike>,
+ startQuotePos: number,
+): number {
+ let pos = startQuotePos + 1;
+ while (pos < buffer.length) {
+ const byte = buffer[pos];
+ if (byte === BYTE_BACKSLASH) {
+ if (pos + 1 >= buffer.length) {
+ throw new SyntaxError('Unterminated string in JSON');
+ }
+ pos += 2;
+ continue;
+ }
+ if (byte === BYTE_QUOTE) {
+ return pos + 1;
+ }
+ pos++;
+ }
+ throw new SyntaxError('Unterminated string in JSON');
+}
+
+/**
+ * Scans past a complete JSON value starting at the specified buffer position.
+ * Skips strings, compound objects, arrays, and primitive values without parsing them into memory.
+ *
+ * @param buffer - The trace byte buffer to scan.
+ * @param startPos - The buffer index where the value begins.
+ * @returns The index immediately following the skipped JSON value.
+ * @throws {SyntaxError} If the value contains unbalanced delimiters, unterminated strings, or empty primitive tokens.
+ */
+function skipValue(
+ buffer: Uint8Array<ArrayBufferLike>,
+ startPos: number,
+): number {
+ let pos = skipWhitespace(buffer, startPos);
+ if (pos >= buffer.length) {
+ return pos;
+ }
+ const firstByte = buffer[pos];
+ if (firstByte === BYTE_QUOTE) {
+ return skipString(buffer, pos);
+ }
+ if (firstByte === BYTE_OPEN_BRACE || firstByte === BYTE_OPEN_BRACKET) {
+ const delimiterStack: number[] = [];
+ delimiterStack.push(
+ firstByte === BYTE_OPEN_BRACE ? BYTE_CLOSE_BRACE : BYTE_CLOSE_BRACKET,
+ );
+ pos++;
+ while (pos < buffer.length) {
+ const byte = buffer[pos];
+ if (byte === BYTE_QUOTE) {
+ pos = skipString(buffer, pos);
+ continue;
+ }
+ if (byte === BYTE_OPEN_BRACE) {
+ delimiterStack.push(BYTE_CLOSE_BRACE);
+ } else if (byte === BYTE_OPEN_BRACKET) {
+ delimiterStack.push(BYTE_CLOSE_BRACKET);
+ } else if (byte === BYTE_CLOSE_BRACE || byte === BYTE_CLOSE_BRACKET) {
+ const expected = delimiterStack.pop();
+ if (expected !== byte) {
+ throw new SyntaxError('Unexpected delimiter in JSON');
+ }
+ if (delimiterStack.length === 0) {
+ pos++;
+ return pos;
+ }
+ }
+ pos++;
+ }
+ throw new SyntaxError('Unexpected end of JSON input');
+ }
+
+ const valStart = pos;
+ while (pos < buffer.length) {
+ const byte = buffer[pos];
+ if (
+ byte === BYTE_COMMA ||
+ byte === BYTE_CLOSE_BRACE ||
+ byte === BYTE_CLOSE_BRACKET ||
+ byte === 0x20 ||
+ byte === 0x09 ||
+ byte === 0x0a ||
+ byte === 0x0d
+ ) {
+ break;
+ }
+ pos++;
+ }
+ if (pos === valStart) {
+ throw new SyntaxError('Expected JSON value');
+ }
+ return pos;
+}
+
+/**
+ * Scans trace events from a JSON array in bounded batches to limit memory consumption.
+ *
+ * @param buffer - The raw byte buffer containing the events array.
+ * @param startPos - The index immediately after the opening array bracket.
+ * @param config - Configuration settings controlling batch sizes and text decoding.
+ * @returns An object containing the parsed events and the ending buffer position.
+ * @throws {SyntaxError} If the event array contains malformed JSON, unbalanced delimiters, or unexpected tokens.
+ */
+function parseEventsArray(
+ buffer: Uint8Array<ArrayBufferLike>,
+ startPos: number,
+ config: BatchConfig,
+): {events: DevTools.TraceEngine.Types.Events.Event[]; endPos: number} {
+ const events: DevTools.TraceEngine.Types.Events.Event[] = [];
+ let batchStart = -1;
+ let lastEventEnd = -1;
+ let batchEventCount = 0;
+ let depth = 0;
+ let i = startPos;
+ let closed = false;
+ let state:
+ 'expect_element_or_end' | 'expect_element' | 'expect_comma_or_end' =
+ 'expect_element_or_end';
+
+ const flushBatch = (): void => {
+ if (batchStart !== -1 && lastEventEnd > batchStart) {
+ // Slicing between batchStart and lastEventEnd is safe for UTF-8 decoding.
+ // Both boundaries are ASCII structural braces ({ and }) that align with code unit boundaries.
+ const slice = buffer.subarray(batchStart, lastEventEnd);
+ const chunkText = config.decoder.decode(slice);
+ // Wrapping comma-delimited event objects in brackets creates a valid JSON array for the parser.
+ const parsed: DevTools.TraceEngine.Types.Events.Event[] = JSON.parse(
+ `[${chunkText}]`,
+ );
+ // Append items iteratively to avoid exceeding V8 call stack size limits on large batches.
+ for (const event of parsed) {
+ events.push(event);
+ }
+ batchStart = -1;
+ batchEventCount = 0;
+ }
+ };
+
+ while (i < buffer.length) {
+ const byte = buffer[i];
+
+ if (depth > 0) {
+ if (byte === BYTE_QUOTE) {
+ i = skipString(buffer, i);
+ continue;
+ }
+ if (byte === BYTE_OPEN_BRACE) {
+ depth++;
+ i++;
+ continue;
+ }
+ if (byte === BYTE_CLOSE_BRACE) {
+ depth--;
+ if (depth === 0) {
+ lastEventEnd = i + 1;
+ batchEventCount++;
+ state = 'expect_comma_or_end';
+
+ // Check thresholds after recording the completed event.
+ // Checking batchEventCount after incrementing ensures batches cap at exactly eventsPerBatch.
+ // Individual events are atomic JSON objects and cannot be split mid-event; when an event
+ // pushes currentBatchBytes over maxBatchBytes, the completed event is flushed immediately.
+ const currentBatchBytes = lastEventEnd - batchStart;
+ if (
+ batchEventCount >= config.eventsPerBatch ||
+ currentBatchBytes >= config.maxBatchBytes
+ ) {
+ flushBatch();
+ }
+ }
+ i++;
+ continue;
+ }
+ i++;
+ continue;
+ }
+
+ // When depth is 0, scan top-level array delimiter and separator tokens.
+ if (byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d) {
+ i++;
+ continue;
+ }
+
+ if (byte === BYTE_OPEN_BRACE) {
+ if (state !== 'expect_element_or_end' && state !== 'expect_element') {
+ throw new SyntaxError('Expected "," or "]" in JSON array');
+ }
+ depth = 1;
+ if (batchStart === -1) {
+ batchStart = i;
+ }
+ i++;
+ continue;
+ }
+
+ if (byte === BYTE_COMMA) {
+ if (state !== 'expect_comma_or_end') {
+ throw new SyntaxError('Unexpected token "," in JSON array');
+ }
+ state = 'expect_element';
+ i++;
+ continue;
+ }
+
+ if (byte === BYTE_CLOSE_BRACKET) {
+ if (state === 'expect_element') {
+ throw new SyntaxError('Unexpected token "]" in JSON array');
+ }
+ closed = true;
+ i++;
+ break;
+ }
+
+ if (byte === BYTE_CLOSE_BRACE) {
+ throw new SyntaxError('Unexpected token "}" in JSON');
+ }
+
+ throw new SyntaxError('Unexpected token in JSON array');
+ }
+
+ if (!closed || depth !== 0) {
+ throw new SyntaxError('Unexpected end of JSON input');
+ }
+
+ flushBatch();
+ return {events, endPos: i};
+}
+
+/**
+ * Parses Chrome DevTools trace events and metadata from a raw byte buffer.
+ * Supports both root array format ([...]) and object container format ({"traceEvents": [...]}).
+ * Parses events in chunks to prevent V8 string length and memory exhaustion errors.
+ *
+ * @param buffer - The raw trace buffer to parse.
+ * @param options - Optional configuration settings for batch processing.
+ * @returns A {@link ParsedTraceBuffer} containing parsed trace events and optional file metadata, or an object with an empty events array if the buffer is empty or contains only whitespace.
+ * @throws {Error} If the buffer contains non-whitespace data that does not begin with a valid JSON array or object.
+ * @throws {SyntaxError} If the underlying JSON syntax within batches or metadata is invalid.
+ */
+export function parseTraceEventsFromBuffer(
+ buffer: Uint8Array<ArrayBufferLike>,
+ options: ParseTraceBufferOptions = {},
+): ParsedTraceBuffer {
+ const eventsPerBatch =
+ typeof options.eventsPerBatch === 'number' &&
+ Number.isFinite(options.eventsPerBatch) &&
+ options.eventsPerBatch > 0
+ ? options.eventsPerBatch
+ : DEFAULT_EVENTS_PER_BATCH;
+
+ const maxBatchBytes =
+ typeof options.maxBatchBytes === 'number' &&
+ Number.isFinite(options.maxBatchBytes) &&
+ options.maxBatchBytes > 0
+ ? options.maxBatchBytes
+ : DEFAULT_MAX_BATCH_BYTES;
+
+ const decoder = new TextDecoder();
+ const config: BatchConfig = {
+ eventsPerBatch,
+ maxBatchBytes,
+ decoder,
+ };
+
+ let pos = skipWhitespace(buffer, 0);
+ if (pos >= buffer.length) {
+ return {events: []};
+ }
+
+ const firstByte = buffer[pos];
+
+ if (firstByte === BYTE_OPEN_BRACKET) {
+ const {events, endPos} = parseEventsArray(buffer, pos + 1, config);
+ const trailingPos = skipWhitespace(buffer, endPos);
+ if (trailingPos < buffer.length) {
+ throw new SyntaxError('Unexpected non-whitespace character after JSON');
+ }
+ return {events};
+ }
+
+ if (firstByte === BYTE_OPEN_BRACE) {
+ pos++;
+ let events: DevTools.TraceEngine.Types.Events.Event[] = [];
+ let metadata: DevTools.TraceEngine.Types.File.MetaData | undefined;
+ let closed = false;
+ let expectComma = false;
+
+ while (pos < buffer.length) {
+ pos = skipWhitespace(buffer, pos);
+ if (pos >= buffer.length) {
+ break;
+ }
+
+ if (buffer[pos] === BYTE_CLOSE_BRACE) {
+ closed = true;
+ pos++;
+ break;
+ }
+
+ if (expectComma) {
+ if (buffer[pos] !== BYTE_COMMA) {
+ throw new SyntaxError(
+ 'Expected "," or "}" after property value in JSON',
+ );
+ }
+ pos++;
+ pos = skipWhitespace(buffer, pos);
+ }
+
+ if (pos >= buffer.length) {
+ break;
+ }
+
+ if (buffer[pos] !== BYTE_QUOTE) {
+ throw new SyntaxError('Expected property name or "}" in JSON');
+ }
+
+ const keyStart = pos;
+ pos = skipString(buffer, pos);
+ const keyJson = decoder.decode(buffer.subarray(keyStart, pos));
+ const parsedKey: unknown = JSON.parse(keyJson);
+ if (typeof parsedKey !== 'string') {
+ throw new SyntaxError('Expected property name in JSON');
+ }
+ const key = parsedKey;
+
+ pos = skipWhitespace(buffer, pos);
+ if (pos >= buffer.length || buffer[pos] !== BYTE_COLON) {
+ throw new SyntaxError('Expected ":" after property name in JSON');
+ }
+ pos++;
+ pos = skipWhitespace(buffer, pos);
+
+ if (key === 'traceEvents') {
+ if (pos >= buffer.length || buffer[pos] !== BYTE_OPEN_BRACKET) {
+ throw new SyntaxError('Expected "[" for "traceEvents" in JSON');
+ }
+ const arrayResult = parseEventsArray(buffer, pos + 1, config);
+ events = arrayResult.events;
+ pos = arrayResult.endPos;
+ } else if (key === 'metadata') {
+ if (pos >= buffer.length || buffer[pos] !== BYTE_OPEN_BRACE) {
+ throw new SyntaxError('Expected "{" for "metadata" in JSON');
+ }
+ const metaStart = pos;
+ pos = skipValue(buffer, pos);
+ const metaSlice = buffer.subarray(metaStart, pos);
+ const metaText = decoder.decode(metaSlice);
+ const parsedMetadata: DevTools.TraceEngine.Types.File.MetaData =
+ JSON.parse(metaText);
+ metadata = parsedMetadata;
+ } else {
+ pos = skipValue(buffer, pos);
+ }
+ expectComma = true;
+ }
+
+ if (!closed) {
+ throw new SyntaxError('Unexpected end of JSON input');
+ }
+
+ const trailingPos = skipWhitespace(buffer, pos);
+ if (trailingPos < buffer.length) {
+ throw new SyntaxError('Unexpected non-whitespace character after JSON');
+ }
+
+ return {events, metadata};
+ }
+
+ throw new Error('Invalid trace buffer: expected JSON object or array.');
+}
diff --git a/src/processors/PerformanceTrace.ts b/src/processors/PerformanceTrace.ts
index d876c777..2c61fd2d 100644
--- a/src/processors/PerformanceTrace.ts
+++ b/src/processors/PerformanceTrace.ts
@@ -6,19 +6,35 @@
import {DevTools} from '../third_party/index.js';
import {logger} from '../utils/logger.js';
+import {parseTraceEventsFromBuffer} from './ChunkedTraceParser.js';
+/**
+ * Represents the successful output of processing a performance trace.
+ */
export interface TraceResult {
+ /** The fully processed trace model output containing event graphs and handler data. */
parsedTrace: DevTools.TraceEngine.TraceModel.ParsedTrace;
+ /** Computed performance insights for navigations in the trace, or null if unavailable. */
insights: DevTools.TraceEngine.Insights.Types.TraceInsightSets | null;
}
+/**
+ * Type guard that verifies if an operation returned a valid TraceResult.
+ *
+ * @param x - The result or error object to inspect.
+ * @returns True if the object is a TraceResult; otherwise false.
+ */
export function traceResultIsSuccess(
x: TraceResult | TraceParseError,
): x is TraceResult {
return 'parsedTrace' in x;
}
+/**
+ * Represents an error encountered while reading or parsing a trace buffer.
+ */
export interface TraceParseError {
+ /** The descriptive error message detailing why trace processing failed. */
error: string;
}
@@ -26,12 +42,13 @@ export interface TraceParseError {
* Parses raw JSON trace buffer bytes into a DevTools TraceEngine representation.
*
* Accepts either a JSON array of trace events or an object with a `traceEvents` field.
- * A new trace engine model is created per call to ensure session isolation and prevent
- * memory retention.
+ * Events are parsed in chunks directly from the raw byte buffer to avoid V8 string
+ * allocation limits. A new trace engine model is created per call to ensure session
+ * isolation and prevent memory retention.
*
- * @param buffer Raw UTF-8 encoded JSON bytes representing trace data.
- * @param metadata Optional throttling configurations applied during recording.
- * @returns A {@link TraceResult} with parsed traces and insights, or a {@link TraceParseError} on failure.
+ * @param buffer - Raw binary trace data representing trace events and metadata.
+ * @param metadata - Optional throttling configurations applied during recording; overrides embedded file metadata when defined.
+ * @returns A promise resolving to a {@link TraceResult} with parsed traces and insights, or a {@link TraceParseError} on failure.
*/
export async function parseRawTraceBuffer(
buffer: Uint8Array<ArrayBufferLike> | undefined,
@@ -40,31 +57,37 @@ export async function parseRawTraceBuffer(
networkThrottling?: string;
},
): Promise<TraceResult | TraceParseError> {
- if (!buffer) {
+ if (!buffer || buffer.length === 0) {
return {
error: 'No buffer was provided.',
};
}
- const asString = new TextDecoder().decode(buffer);
- if (!asString) {
- return {
- error: 'Decoding the trace buffer returned an empty string.',
- };
- }
try {
- const data = JSON.parse(asString) as
- | {
- traceEvents: DevTools.TraceEngine.Types.Events.Event[];
- }
- | DevTools.TraceEngine.Types.Events.Event[];
+ const {events, metadata: fileMetadata} = parseTraceEventsFromBuffer(buffer);
+ if (events.length === 0) {
+ return {
+ error: 'No trace events were found in the trace buffer.',
+ };
+ }
+ const combinedMetadata: DevTools.TraceEngine.Types.File.MetaData = {
+ ...fileMetadata,
+ ...(metadata?.cpuThrottling !== undefined
+ ? {cpuThrottling: metadata.cpuThrottling}
+ : {}),
+ ...(metadata?.networkThrottling !== undefined
+ ? {networkThrottling: metadata.networkThrottling}
+ : {}),
+ };
+ const hasMetadata = Object.keys(combinedMetadata).length > 0;
- const events = Array.isArray(data) ? data : data.traceEvents;
// Instantiate a fresh TraceModel per invocation because Model permanently
// retains parsed traces in its internal `#traces` array, which causes an
// unbounded memory leak if reused across sessions.
const engine =
DevTools.TraceEngine.TraceModel.Model.createWithAllHandlers();
- await engine.parse(events, {metadata});
+ await engine.parse(events, {
+ metadata: hasMetadata ? combinedMetadata : undefined,
+ });
const parsedTrace = engine.parsedTrace();
if (!parsedTrace) {
return {
@@ -93,6 +116,13 @@ ${DevTools.PerformanceTraceFormatter.callFrameDataFormatDescription}
${DevTools.PerformanceTraceFormatter.networkDataFormatDescription}`;
+/**
+ * Generates a Markdown summary of main thread activity and network metrics from a parsed trace.
+ *
+ * @param result - The parsed trace result to summarize.
+ * @param deviceScope - Optional CrUX device scope to filter field data.
+ * @returns Formatted Markdown text describing performance findings.
+ */
export function getTraceSummary(
result: TraceResult,
deviceScope?: DevTools.CrUXManager.DeviceScope | null,
@@ -107,10 +137,22 @@ ${summaryText}
${extraFormatDescriptions}`;
}
+/** Identifies a specific performance insight model type supported by the trace engine. */
export type InsightName =
keyof DevTools.TraceEngine.Insights.Types.InsightModels;
+
+/** Represents the result of an insight formatting request. */
export type InsightOutput = {output: string} | {error: string};
+/**
+ * Formats a specific performance insight from a parsed trace for display.
+ *
+ * @param result - The parsed trace result containing computed insight sets.
+ * @param insightSetId - The identifier of the target insight set.
+ * @param insightName - The name of the insight model to extract.
+ * @param deviceScope - Optional CrUX device scope to contextualize metrics.
+ * @returns An object containing the formatted insight output text or an error message.
+ */
export function getInsightOutput(
result: TraceResult,
insightSetId: string,
diff --git a/tests/McpResponse.test.js.snapshot b/tests/McpResponse.test.js.snapshot
index 9b94ec5f..8e9de822 100644
--- a/tests/McpResponse.test.js.snapshot
+++ b/tests/McpResponse.test.js.snapshot
@@ -786,8 +786,8 @@ exports[`McpResponse network pagination > trace summaries > includes the trace s
## Summary of Performance trace findings:
URL: https://web.dev/
Trace bounds: {min: 122410994891µs, max: 122416385853µs}
-CPU throttling: none
-Network throttling: none
+CPU throttling: 1x
+Network throttling: No throttling
# Available insight sets
@@ -903,8 +903,8 @@ exports[`McpResponse network pagination > trace summaries > includes the trace s
## Summary of Performance trace findings:
URL: https://web.dev/
Trace bounds: {min: 122410994891µs, max: 122416385853µs}
-CPU throttling: none
-Network throttling: none
+CPU throttling: 1x
+Network throttling: No throttling
# Available insight sets
diff --git a/tests/trace-processing/ChunkedTraceParser.test.ts b/tests/trace-processing/ChunkedTraceParser.test.ts
new file mode 100644
index 00000000..fc2de5c6
--- /dev/null
+++ b/tests/trace-processing/ChunkedTraceParser.test.ts
@@ -0,0 +1,407 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {parseTraceEventsFromBuffer} from '../../src/processors/ChunkedTraceParser.js';
+
+import {loadTraceAsBuffer} from './fixtures/load.js';
+
+describe('ChunkedTraceParser', () => {
+ const encoder = new TextEncoder();
+
+ it('parses an empty trace array', () => {
+ const buffer = encoder.encode('[]');
+ const result = parseTraceEventsFromBuffer(buffer);
+ assert.strictEqual(result.events.length, 0);
+ });
+
+ it('parses an empty traceEvents object', () => {
+ const buffer = encoder.encode('{"traceEvents": []}');
+ const result = parseTraceEventsFromBuffer(buffer);
+ assert.strictEqual(result.events.length, 0);
+ });
+
+ it('parses a bare array of events', () => {
+ const json = JSON.stringify([
+ {name: 'event-1', ph: 'X', ts: 100},
+ {name: 'event-2', ph: 'B', ts: 200},
+ ]);
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 2);
+ assert.strictEqual(result.events[0]?.name, 'event-1');
+ assert.strictEqual(result.events[1]?.name, 'event-2');
+ });
+
+ it('parses an object with traceEvents and metadata', () => {
+ const json = JSON.stringify({
+ traceEvents: [
+ {name: 'event-1', ph: 'X', ts: 100},
+ {name: 'event-2', ph: 'E', ts: 150},
+ ],
+ metadata: {
+ cpuThrottling: 4,
+ },
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 2);
+ assert.strictEqual(result.events[0]?.name, 'event-1');
+ assert.strictEqual(result.events[1]?.name, 'event-2');
+ assert.strictEqual(result.metadata?.cpuThrottling, 4);
+ });
+
+ it('parses metadata when metadata appears before traceEvents', () => {
+ const json = JSON.stringify({
+ metadata: {
+ cpuThrottling: 2,
+ },
+ traceEvents: [{name: 'event-1', ph: 'X', ts: 50}],
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 1);
+ assert.strictEqual(result.events[0]?.name, 'event-1');
+ assert.strictEqual(result.metadata?.cpuThrottling, 2);
+ });
+
+ it('skips unrelated top-level properties', () => {
+ const json = JSON.stringify({
+ displayTimeUnit: 'ms',
+ traceEvents: [{name: 'event-1', ph: 'X', ts: 10}],
+ otherData: {nested: true, count: 42},
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 1);
+ assert.strictEqual(result.events[0]?.name, 'event-1');
+ });
+
+ it('handles strings containing braces, brackets, and escaped quotes', () => {
+ const json = JSON.stringify({
+ traceEvents: [
+ {
+ name: 'event-{with-braces}',
+ args: {
+ data: {
+ url: 'https://example.com/hello?q=} { [bracket] "escaped" \\\\ backslash',
+ },
+ },
+ },
+ ],
+ metadata: {
+ title: 'nested } braces { inside',
+ },
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 1);
+ assert.strictEqual(result.events[0]?.name, 'event-{with-braces}');
+ assert.strictEqual(
+ result.events[0]?.args?.data?.url,
+ 'https://example.com/hello?q=} { [bracket] "escaped" \\\\ backslash',
+ );
+ assert.strictEqual(result.metadata?.title, 'nested } braces { inside');
+ });
+
+ it('handles nested objects in event args data', () => {
+ const json = JSON.stringify({
+ traceEvents: [
+ {
+ name: 'deep',
+ args: {
+ data: {
+ url: 'https://example.com',
+ },
+ },
+ },
+ ],
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+
+ assert.strictEqual(result.events.length, 1);
+ assert.strictEqual(result.events[0]?.name, 'deep');
+ assert.strictEqual(
+ result.events[0]?.args?.data?.url,
+ 'https://example.com',
+ );
+ });
+
+ it('batches events correctly according to eventsPerBatch', () => {
+ const json = JSON.stringify({
+ traceEvents: [
+ {name: 'e1', ts: 1},
+ {name: 'e2', ts: 2},
+ {name: 'e3', ts: 3},
+ {name: 'e4', ts: 4},
+ {name: 'e5', ts: 5},
+ ],
+ });
+ const buffer = encoder.encode(json);
+ // Batch size of 2 on 5 items tests full batches and remainder batch.
+ const result = parseTraceEventsFromBuffer(buffer, {eventsPerBatch: 2});
+
+ assert.strictEqual(result.events.length, 5);
+ assert.strictEqual(result.events[0]?.name, 'e1');
+ assert.strictEqual(result.events[1]?.name, 'e2');
+ assert.strictEqual(result.events[2]?.name, 'e3');
+ assert.strictEqual(result.events[3]?.name, 'e4');
+ assert.strictEqual(result.events[4]?.name, 'e5');
+ });
+
+ it('parses a real trace fixture matching standard JSON.parse', () => {
+ const rawData = loadTraceAsBuffer('basic-trace.json.gz');
+ const result = parseTraceEventsFromBuffer(rawData, {eventsPerBatch: 10});
+
+ const standardJsonText = new TextDecoder().decode(rawData);
+ const standardParsed:
+ | Array<{name: string; ts: number}>
+ | {traceEvents: Array<{name: string; ts: number}>} =
+ JSON.parse(standardJsonText);
+ const expectedEvents = Array.isArray(standardParsed)
+ ? standardParsed
+ : standardParsed.traceEvents;
+
+ assert.strictEqual(result.events.length, expectedEvents.length);
+ assert.strictEqual(result.events[0]?.name, expectedEvents[0]?.name);
+ assert.strictEqual(result.events[0]?.ts, expectedEvents[0]?.ts);
+ const lastIndex = result.events.length - 1;
+ assert.strictEqual(
+ result.events[lastIndex]?.name,
+ expectedEvents[lastIndex]?.name,
+ );
+ });
+
+ it('parses a larger trace fixture in multiple batches', () => {
+ const rawData = loadTraceAsBuffer('web-dev-with-commit.json.gz');
+ const result = parseTraceEventsFromBuffer(rawData, {eventsPerBatch: 5000});
+
+ const standardJsonText = new TextDecoder().decode(rawData);
+ const standardParsed:
+ | Array<{name: string; ts: number}>
+ | {traceEvents: Array<{name: string; ts: number}>} =
+ JSON.parse(standardJsonText);
+ const expectedEvents = Array.isArray(standardParsed)
+ ? standardParsed
+ : standardParsed.traceEvents;
+
+ assert.strictEqual(result.events.length, expectedEvents.length);
+ assert.strictEqual(result.events.length, 47705);
+ assert.strictEqual(result.events[0]?.name, expectedEvents[0]?.name);
+ const lastIndex = result.events.length - 1;
+ assert.strictEqual(
+ result.events[lastIndex]?.name,
+ expectedEvents[lastIndex]?.name,
+ );
+ });
+
+ it('throws SyntaxError when a bare array is truncated before closing bracket', () => {
+ const buffer = encoder.encode('[{"name": "e1", "ts": 1}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when a string inside an event is unterminated', () => {
+ const buffer = encoder.encode('[{"name": "unterminated');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when an object container is truncated before closing brace', () => {
+ const buffer = encoder.encode('{"traceEvents": [{"name": "e1"}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on stray closing braces', () => {
+ const buffer = encoder.encode('[{"name": "e1"}}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('handles multibyte UTF-8 characters across batch boundaries', () => {
+ const json = JSON.stringify({
+ traceEvents: [
+ {
+ name: '日本語テスト-1',
+ args: {data: {url: 'https://example.com/こんにちは世界-🚀'}},
+ },
+ {
+ name: 'emoji-🎉-2',
+ args: {data: {url: 'https://example.com/€100-and-50¢'}},
+ },
+ {
+ name: 'umlaut-äöü-3',
+ args: {data: {url: 'https://example.com/Deutsch-äöü'}},
+ },
+ ],
+ });
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer, {eventsPerBatch: 1});
+
+ assert.strictEqual(result.events.length, 3);
+ assert.strictEqual(result.events[0]?.name, '日本語テスト-1');
+ assert.strictEqual(
+ result.events[0]?.args?.data?.url,
+ 'https://example.com/こんにちは世界-🚀',
+ );
+ assert.strictEqual(result.events[1]?.name, 'emoji-🎉-2');
+ assert.strictEqual(
+ result.events[1]?.args?.data?.url,
+ 'https://example.com/€100-and-50¢',
+ );
+ assert.strictEqual(result.events[2]?.name, 'umlaut-äöü-3');
+ assert.strictEqual(
+ result.events[2]?.args?.data?.url,
+ 'https://example.com/Deutsch-äöü',
+ );
+ });
+
+ it('parses large batches exceeding function argument limits without call stack errors', () => {
+ const eventCount = 70_000;
+ const items: string[] = [];
+ for (let idx = 0; idx < eventCount; idx++) {
+ items.push(`{"name":"evt-${idx}","ts":${idx}}`);
+ }
+ const buffer = encoder.encode(`[${items.join(',')}]`);
+ const result = parseTraceEventsFromBuffer(buffer, {
+ eventsPerBatch: eventCount,
+ });
+
+ assert.strictEqual(result.events.length, eventCount);
+ assert.strictEqual(result.events[0]?.name, 'evt-0');
+ assert.strictEqual(result.events[69_999]?.name, 'evt-69999');
+ });
+
+ it('throws SyntaxError when non-whitespace characters follow a closed array', () => {
+ const buffer = encoder.encode('[{"name": "e1"}] extra');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when non-whitespace characters follow a closed object', () => {
+ const buffer = encoder.encode('{"traceEvents": []} extra');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when a property key is missing a colon in object container', () => {
+ const buffer = encoder.encode('{"traceEvents" []}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when a comma is missing between object properties', () => {
+ const buffer = encoder.encode('{"traceEvents": [] "metadata": {}}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when an object key string is unterminated', () => {
+ const buffer = encoder.encode('{"traceEvents');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('batches events by maxBatchBytes when byte threshold is exceeded', () => {
+ const e1 = {
+ name: 'event-one-long-name',
+ args: {detail: 'some-payload-string-1'},
+ };
+ const e2 = {
+ name: 'event-two-long-name',
+ args: {detail: 'some-payload-string-2'},
+ };
+ const json = JSON.stringify([e1, e2]);
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer, {
+ eventsPerBatch: 100,
+ maxBatchBytes: 40,
+ });
+ assert.strictEqual(result.events.length, 2);
+ assert.strictEqual(result.events[0]?.name, 'event-one-long-name');
+ assert.strictEqual(result.events[1]?.name, 'event-two-long-name');
+ });
+
+ it('falls back to defaults when invalid batch options are provided', () => {
+ const json = JSON.stringify([{name: 'e1'}, {name: 'e2'}]);
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer, {
+ eventsPerBatch: -5,
+ maxBatchBytes: NaN,
+ });
+ assert.strictEqual(result.events.length, 2);
+ assert.strictEqual(result.events[0]?.name, 'e1');
+ assert.strictEqual(result.events[1]?.name, 'e2');
+ });
+
+ it('throws SyntaxError when a comma is missing between events', () => {
+ const buffer = encoder.encode('[{"name": "e1"} {"name": "e2"}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on trailing comma in events array', () => {
+ const buffer = encoder.encode('[{"name": "e1"}, ]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on non-object items in events array', () => {
+ const buffer1 = encoder.encode('[null, {"name": "e1"}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer1), SyntaxError);
+
+ const buffer2 = encoder.encode('[123, {"name": "e1"}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer2), SyntaxError);
+
+ const buffer3 = encoder.encode('["invalid", {"name": "e1"}]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer3), SyntaxError);
+ });
+
+ it('throws SyntaxError on nested array elements in events array', () => {
+ const buffer = encoder.encode('[ [], {"name": "e1"} ]');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on mismatched delimiters in skipped values', () => {
+ const buffer = encoder.encode('{"other": {"a": ]}, "traceEvents": []}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on empty primitive value in container object', () => {
+ const buffer = encoder.encode('{"other": , "traceEvents": []}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on unterminated escape in skipped string', () => {
+ const buffer = encoder.encode('{"other": "\\');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('correctly decodes escaped container object keys', () => {
+ const json =
+ '{"\\u0074raceEvents": [{"name": "e1"}], "\\u006d\\u0065\\u0074\\u0061\\u0064\\u0061\\u0074\\u0061": {"cpuThrottling": 2}}';
+ const buffer = encoder.encode(json);
+ const result = parseTraceEventsFromBuffer(buffer);
+ assert.strictEqual(result.events.length, 1);
+ assert.strictEqual(result.events[0]?.name, 'e1');
+ assert.strictEqual(result.metadata?.cpuThrottling, 2);
+ });
+
+ it('throws SyntaxError when traceEvents property value is not an array', () => {
+ const buffer = encoder.encode('{"traceEvents": "not-an-array"}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError when metadata property value is not an object', () => {
+ const buffer = encoder.encode(
+ '{"metadata": "not-an-object", "traceEvents": []}',
+ );
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+
+ it('throws SyntaxError on trailing comma in container object', () => {
+ const buffer = encoder.encode('{"traceEvents": [],}');
+ assert.throws(() => parseTraceEventsFromBuffer(buffer), SyntaxError);
+ });
+});
diff --git a/tests/trace-processing/parse.test.js.snapshot b/tests/trace-processing/parse.test.js.snapshot
index bf59cc4f..ca7c7a8a 100644
--- a/tests/trace-processing/parse.test.js.snapshot
+++ b/tests/trace-processing/parse.test.js.snapshot
@@ -2,8 +2,8 @@ exports[`Trace parsing > can format results of a trace 1`] = `
## Summary of Performance trace findings:
URL: https://web.dev/
Trace bounds: {min: 122410994891µs, max: 122416385853µs}
-CPU throttling: none
-Network throttling: none
+CPU throttling: 1x
+Network throttling: No throttling
# Available insight sets
diff --git a/tests/trace-processing/parse.test.ts b/tests/trace-processing/parse.test.ts
index 670e5bf7..bed919b6 100644
--- a/tests/trace-processing/parse.test.ts
+++ b/tests/trace-processing/parse.test.ts
@@ -78,4 +78,36 @@ describe('Trace parsing', () => {
error: 'No buffer was provided.',
});
});
+
+ it('does not clobber file metadata with undefined caller properties', async () => {
+ const rawData = loadTraceAsBuffer('web-dev-with-commit.json.gz');
+ // The caller passes explicit undefined for networkThrottling (matching production behavior when conditions are null).
+ const result = await parseRawTraceBuffer(rawData, {
+ cpuThrottling: undefined,
+ networkThrottling: undefined,
+ });
+ if ('error' in result) {
+ assert.fail(`Unexpected parse failure: ${result.error}`);
+ }
+ const summary = getTraceSummary(result);
+ // Verify that throttling from file metadata is preserved rather than reverting to 'none'.
+ assert.ok(summary.includes('CPU throttling: 1x'));
+ assert.ok(summary.includes('Network throttling: No throttling'));
+ });
+
+ it('overrides file metadata when caller specifies defined throttling options', async () => {
+ const rawData = loadTraceAsBuffer('web-dev-with-commit.json.gz');
+ // The caller passes explicit defined overrides.
+ const result = await parseRawTraceBuffer(rawData, {
+ cpuThrottling: 4,
+ networkThrottling: 'Slow 3G',
+ });
+ if ('error' in result) {
+ assert.fail(`Unexpected parse failure: ${result.error}`);
+ }
+ const summary = getTraceSummary(result);
+ // Verify that caller-specified throttling overrides file metadata.
+ assert.ok(summary.includes('CPU throttling: 4x'));
+ assert.ok(summary.includes('Network throttling: Slow 3G'));
+ });
});