Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(browser)!: preserve WebSocket connections and comparable payload coverage

morlutodb4e36084654
diff --git a/scripts/lib/browser-verifier-assertions.mjs b/scripts/lib/browser-verifier-assertions.mjs
index 8e484afa1..2ca836011 100644
--- a/scripts/lib/browser-verifier-assertions.mjs
+++ b/scripts/lib/browser-verifier-assertions.mjs
@@ -65,7 +65,11 @@ function assertObservationEvents(result) {
throw new Error(
"Real Chrome attach-window console observation was missing",
);
- if (result.network.websocket_events.length < 1)
+ if (
+ !result.network.websocket_connections.some(
+ (connection) => connection.events.length > 0,
+ )
+ )
throw new Error("Real Chrome WebSocket metadata was missing");
}
@@ -77,8 +81,8 @@ function assertObservationPrivacy(result) {
result.network.requests.some(
(request) => request.body_shapes.status !== "not_approved",
) ||
- result.network.websocket_events.some(
- (event) => event.payload_shape !== null,
+ result.network.websocket_connections.some((connection) =>
+ connection.events.some((event) => event.payload_shape !== null),
)
)
throw new Error(
@@ -246,15 +250,17 @@ export function assertSensitiveShapes(result) {
)
throw new Error("Real Chrome selected console text was not preserved");
if (
- !result.network.websocket_events.some(
- (event) =>
- event.payload_shape?.format === "json" &&
- event.payload_shape.json_shape?.properties.some(
- ({ path }) =>
- path.length === 1 &&
- path[0].kind === "property" &&
- path[0].name === "token",
- ),
+ !result.network.websocket_connections.some((connection) =>
+ connection.events.some(
+ (event) =>
+ event.payload_shape?.format === "json" &&
+ event.payload_shape.json_shape?.properties.some(
+ ({ path }) =>
+ path.length === 1 &&
+ path[0].kind === "property" &&
+ path[0].name === "token",
+ ),
+ ),
)
)
throw new Error("Real Chrome WebSocket JSON shape was missing");
diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjs
index a63024b49..9cb611458 100644
--- a/scripts/verify-real-browser.mjs
+++ b/scripts/verify-real-browser.mjs
@@ -355,7 +355,11 @@ try {
scripts: observed.value.scripts.items.length,
networkRequests: observed.value.network.requests.length,
consoleEvents: observed.value.console.events.length,
- websocketEvents: observed.value.network.websocket_events.length,
+ websocketConnections: observed.value.network.websocket_connections.length,
+ websocketFrames: observed.value.network.websocket_connections.reduce(
+ (total, connection) => total + connection.events.length,
+ 0,
+ ),
bundleScripts: bundle.capture.scripts_analyzed,
sourceMaps: bundle.observations.source_maps.processed,
bundle_cli_and_stdio_mcp: true,
diff --git a/src/browser/CdpCaptureEventHandlers.ts b/src/browser/CdpCaptureEventHandlers.ts
index 3e4c1290f..e37e2f789 100644
--- a/src/browser/CdpCaptureEventHandlers.ts
+++ b/src/browser/CdpCaptureEventHandlers.ts
@@ -1,4 +1,5 @@
import type { WebPageInspection } from "../domain/browserObservationSchemas.js";
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
import { inferJsonShape } from "../domain/jsonShape.js";
import { safeResponseMetadata } from "./CdpSafeMetadata.js";
import {
@@ -487,23 +488,20 @@ export const handleWebSocketFrame = (
direction: "sent" | "received",
): void => {
const requestId = cdpStringValue(params.requestId);
- if (
- requestId === undefined ||
- (!state.network.has(requestId) && !state.allowedWebSockets.has(requestId))
- )
- return;
+ if (requestId === undefined) return;
+ const connection = state.webSocketConnectionsById.get(requestId);
+ if (connection === undefined) return;
const response = recordValue(params.response);
const payload = cdpStringValue(response?.payloadData) ?? "";
const opcode = Math.max(0, Math.trunc(numberValue(response?.opcode) ?? 0));
const decoded = opcode === 1 ? undefined : decodeBase64(payload);
if (opcode !== 1 && decoded === undefined)
state.completeness.exclude("websocket_frames", "invalid_protocol_value");
- state.websockets.push({
- request_id: requestId,
+ connection.events.push({
direction,
opcode,
payload_bytes:
- opcode === 1 ? Buffer.byteLength(payload) : (decoded?.byteLength ?? 0),
+ opcode === 1 ? Buffer.byteLength(payload) : (decoded?.byteLength ?? null),
payload_shape: captureWebSocketShape(state, payload, opcode),
});
};
@@ -512,7 +510,7 @@ const captureWebSocketShape = (
state: CdpCaptureEventsState,
payload: string,
opcode: number,
-): WebPageInspection["network"]["websocket_events"][number]["payload_shape"] => {
+): WebPageInspection["network"]["websocket_connections"][number]["events"][number]["payload_shape"] => {
if (!state.input.include_websocket_shapes) return null;
if (opcode !== 1) return { format: "binary", json_shape: null };
const shape = inferJsonShape(payload);
@@ -542,9 +540,10 @@ export const handleWebSocketCreated = (
);
return;
}
+ const sourceUrl = sanitizeBrowserUrl(rawUrl).url;
let parsed: URL;
try {
- parsed = new URL(rawUrl);
+ parsed = new URL(sourceUrl);
} catch (cause: unknown) {
// Unparseable URLs are recorded as unsupported, not as failures.
void cause;
@@ -561,7 +560,18 @@ export const handleWebSocketCreated = (
state.completeness.exclude("websocket_connections", "disallowed_origin");
return;
}
- state.allowedWebSockets.add(requestId);
+ if (state.webSocketConnectionsById.has(requestId)) {
+ state.completeness.exclude(
+ "websocket_connections",
+ "invalid_protocol_value",
+ );
+ return;
+ }
+ state.webSocketConnectionsById.set(requestId, {
+ request_id: requestId,
+ url: sourceUrl,
+ events: [],
+ });
};
export const handleFrameNavigated = (
diff --git a/src/browser/CdpCaptureEventState.ts b/src/browser/CdpCaptureEventState.ts
index b09e63063..9883a3a3c 100644
--- a/src/browser/CdpCaptureEventState.ts
+++ b/src/browser/CdpCaptureEventState.ts
@@ -16,9 +16,11 @@ export interface CdpCaptureEventsState {
readonly network: Map<string, NetworkState>;
readonly networkRequestTimestamps: Map<string, number>;
readonly malformedRedirectRequestIds: Set<string>;
- readonly allowedWebSockets: Set<string>;
+ readonly webSocketConnectionsById: Map<
+ string,
+ WebPageInspection["network"]["websocket_connections"][number]
+ >;
console: WebPageInspection["console"]["events"];
- websockets: WebPageInspection["network"]["websocket_events"];
responseMetadata: WebPageInspection["metadata"]["responses"];
agentHints: WebPageInspection["metadata"]["agent_hints"];
readonly completeness: CdpCaptureCompleteness;
diff --git a/src/browser/CdpCaptureEvents.ts b/src/browser/CdpCaptureEvents.ts
index b5dcc7218..547d31b3a 100644
--- a/src/browser/CdpCaptureEvents.ts
+++ b/src/browser/CdpCaptureEvents.ts
@@ -22,9 +22,11 @@ export class CdpCaptureEvents implements CdpCaptureEventsState {
readonly network = new Map<string, NetworkState>();
readonly networkRequestTimestamps = new Map<string, number>();
readonly malformedRedirectRequestIds = new Set<string>();
- readonly allowedWebSockets = new Set<string>();
+ readonly webSocketConnectionsById = new Map<
+ string,
+ WebPageInspection["network"]["websocket_connections"][number]
+ >();
console: WebPageInspection["console"]["events"] = [];
- websockets: WebPageInspection["network"]["websocket_events"] = [];
responseMetadata: WebPageInspection["metadata"]["responses"] = [];
agentHints: WebPageInspection["metadata"]["agent_hints"] = [];
readonly completeness = new CdpCaptureCompleteness([
@@ -63,9 +65,8 @@ export class CdpCaptureEvents implements CdpCaptureEventsState {
this.network.clear();
this.networkRequestTimestamps.clear();
this.malformedRedirectRequestIds.clear();
- this.allowedWebSockets.clear();
+ this.webSocketConnectionsById.clear();
this.console.length = 0;
- this.websockets.length = 0;
this.responseMetadata.length = 0;
this.agentHints.length = 0;
this.completeness.reset();
diff --git a/src/browser/CdpPageCapture.ts b/src/browser/CdpPageCapture.ts
index 75d629e03..fdbc81fb4 100644
--- a/src/browser/CdpPageCapture.ts
+++ b/src/browser/CdpPageCapture.ts
@@ -300,7 +300,7 @@ const normalizedInspection = (
resources: [...captured.resources],
network: {
requests: [...state.events.network.values()],
- websocket_events: [...state.events.websockets],
+ websocket_connections: [...state.events.webSocketConnectionsById.values()],
coverage_started_at: state.startedAt,
prior_activity_available: false,
},
diff --git a/src/contracts/browserToolContracts.ts b/src/contracts/browserToolContracts.ts
index 4ac468b41..7d5a23313 100644
--- a/src/contracts/browserToolContracts.ts
+++ b/src/contracts/browserToolContracts.ts
@@ -223,7 +223,7 @@ export const BROWSER_TOOL_CONTRACTS = [
name: "compare_web_captures",
...toolContractMetadata("compare_web_captures"),
description:
- "Compare passive web captures by providing before and after, each with the complete inspect_web_page normalized_result in inspection and an optional complete discover_webmcp_tools normalized_result in webmcp; or compare recorded scenarios by passing complete capture_browser_scenario normalized_result objects in before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
+ "Compare passive web captures by providing before and after, each with the complete inspect_web_page normalized_result in inspection and an optional complete discover_webmcp_tools normalized_result in webmcp; or compare recorded scenarios by passing complete capture_browser_scenario normalized_result objects in before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Network comparison includes observed HTTP requests and WebSocket frame streams; same-URL connections are compared as an unordered collection of ordered streams, retaining connection counts without claiming stable identity between individual connections. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
kind: "browser-provider",
inputSchema: browserCaptureComparisonInputSchema,
outputSchema: captureDiffOutputSchema,
diff --git a/src/domain/browserObservationSchemas.ts b/src/domain/browserObservationSchemas.ts
index d771a2970..bfa25117b 100644
--- a/src/domain/browserObservationSchemas.ts
+++ b/src/domain/browserObservationSchemas.ts
@@ -173,11 +173,10 @@ const browserConsoleEventSchema = z.object({
retained_bytes: z.number().int().min(0),
}),
});
-const browserWebSocketEventSchema = z.object({
- request_id: z.string(),
+const browserWebSocketFrameSchema = z.object({
direction: z.enum(["sent", "received"]),
opcode: z.number().int().min(0),
- payload_bytes: z.number().int().min(0),
+ payload_bytes: z.number().int().min(0).nullable(),
payload_shape: z
.object({
format: z.enum(["json", "text", "binary"]),
@@ -185,6 +184,11 @@ const browserWebSocketEventSchema = z.object({
})
.nullable(),
});
+const browserWebSocketConnectionSchema = z.object({
+ request_id: z.string(),
+ url: z.string(),
+ events: z.array(browserWebSocketFrameSchema),
+});
const browserWorkerSchema = z.object({
target_id: z.string(),
type: z.string(),
@@ -296,7 +300,7 @@ export const webPageInspectionSchema = z.object({
resources: z.array(browserResourceSchema),
network: z.object({
requests: z.array(browserNetworkRequestSchema),
- websocket_events: z.array(browserWebSocketEventSchema),
+ websocket_connections: z.array(browserWebSocketConnectionSchema),
coverage_started_at: z.iso.datetime(),
prior_activity_available: z.literal(false),
}),
diff --git a/src/domain/webBundleAnalyzer.test.ts b/src/domain/webBundleAnalyzer.test.ts
index 896359e94..1cfe649dc 100644
--- a/src/domain/webBundleAnalyzer.test.ts
+++ b/src/domain/webBundleAnalyzer.test.ts
@@ -458,7 +458,7 @@ const inspection = (source: string) =>
resources: [],
network: {
requests: [],
- websocket_events: [],
+ websocket_connections: [],
coverage_started_at: "2026-07-14T00:00:00.000Z",
prior_activity_available: false,
},
diff --git a/src/domain/webCaptureDiff.ts b/src/domain/webCaptureDiff.ts
index 08c896818..768f73c0b 100644
--- a/src/domain/webCaptureDiff.ts
+++ b/src/domain/webCaptureDiff.ts
@@ -38,7 +38,7 @@ export const compareWebCaptures = (
dimensions,
limitations: [
"A changed status proves an observed difference; an unknown status means absence could not be established from capture completeness.",
- "Network comparison covers only activity observed after each CDP attachment.",
+ "Network comparison covers only activity observed after each CDP attachment. WebSocket connections with the same URL are compared as an unordered collection of ordered frame streams, retaining connection counts; their individual identities are not stable across captures.",
"Accessibility roles, ignored state, text, and hierarchy are compared only when the accessibility tree was fully captured and text capture was selected and not truncated.",
"Storage key inventories are compared only when selected and complete; usage and quota are compared only when reported. Redacted content is compared through complete SHA-256 fingerprints.",
],
@@ -238,6 +238,12 @@ const bodyShapesSelected = (inspection: WebPageInspection): boolean =>
({ body_shapes }) => body_shapes.status !== "not_approved",
));
+const webSocketShapesSelected = (inspection: WebPageInspection): boolean =>
+ !inspection.completeness.excluded.some(
+ ({ section, reason }) =>
+ section === "websocket_shapes" && reason === "not_approved",
+ );
+
const networkIdentity = (
request: WebPageInspection["network"]["requests"][number],
): string =>
@@ -248,6 +254,8 @@ const networkDimension = (
after: WebPageInspection,
): Dimension => {
const selected = bodyShapesSelected(before) && bodyShapesSelected(after);
+ const webSocketShapes =
+ webSocketShapesSelected(before) && webSocketShapesSelected(after);
const sources = new Map<string, BodyShapeSources>();
if (selected) {
const observedSources = (inspection: WebPageInspection) => {
@@ -284,13 +292,49 @@ const networkDimension = (
({ body_shapes }) => body_shapes.status === "included",
),
);
+ const webSocketShapesComplete =
+ !webSocketShapes ||
+ [before, after].every(
+ (inspection) =>
+ sectionsComplete(inspection, ["websocket_shapes"]) &&
+ inspection.network.websocket_connections.every((connection) =>
+ connection.events.every((event) => event.payload_shape !== null),
+ ),
+ );
+ const webSocketPayloadBytesComplete = [before, after].every((inspection) =>
+ inspection.network.websocket_connections.every((connection) =>
+ connection.events.every((event) => event.payload_bytes !== null),
+ ),
+ );
+ const beforeWebSockets = webSocketGroups(before);
+ const afterWebSockets = webSocketGroups(after);
+ const [beforeWebSocketPayload, afterWebSocketPayload] = webSocketPayloadMaps(
+ beforeWebSockets,
+ afterWebSockets,
+ webSocketShapes,
+ );
return compareDimension(
- networkMap(before, sources),
- networkMap(after, sources),
- sectionsComplete(before, ["network_requests"]) &&
- sectionsComplete(after, ["network_requests"]) &&
- shapesComplete,
- "Network capture or selected JSON body-shape coverage is attach-window limited, unavailable, or incomplete.",
+ new Map([
+ ...networkMap(before, sources),
+ ...webSocketMetadataMap(beforeWebSockets),
+ ...beforeWebSocketPayload,
+ ]),
+ new Map([
+ ...networkMap(after, sources),
+ ...webSocketMetadataMap(afterWebSockets),
+ ...afterWebSocketPayload,
+ ]),
+ [before, after].every((inspection) =>
+ sectionsComplete(inspection, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ ]),
+ ) &&
+ shapesComplete &&
+ webSocketPayloadBytesComplete &&
+ webSocketShapesComplete,
+ "Network capture or selected HTTP/WebSocket payload-shape coverage is attach-window limited, unavailable, or incomplete.",
);
};
@@ -334,6 +378,120 @@ const networkMap = (
);
};
+type WebSocketGroup = {
+ readonly url: string;
+ readonly stream: string;
+ readonly connections: WebPageInspection["network"]["websocket_connections"];
+};
+
+const webSocketGroups = (
+ inspection: WebPageInspection,
+): ReadonlyMap<string, WebSocketGroup> => {
+ const groups = new Map<string, WebSocketGroup>();
+ for (const connection of inspection.network.websocket_connections) {
+ const stream = digestCanonicalValue(
+ connection.events.map(({ direction, opcode }) => ({
+ direction,
+ opcode,
+ })),
+ );
+ const key = digestCanonicalValue({ url: connection.url, stream });
+ const previous = groups.get(key);
+ if (previous !== undefined) previous.connections.push(connection);
+ else
+ groups.set(key, {
+ url: connection.url,
+ stream,
+ connections: [connection],
+ });
+ }
+ return groups;
+};
+
+const webSocketMetadataMap = (
+ groups: ReadonlyMap<string, WebSocketGroup>,
+): ReadonlyMap<string, string> => {
+ const byUrl = new Map<string, string[]>();
+ for (const group of groups.values()) {
+ const streams = byUrl.get(group.url) ?? [];
+ for (let index = 0; index < group.connections.length; index += 1)
+ streams.push(group.stream);
+ byUrl.set(group.url, streams);
+ }
+ return new Map(
+ [...byUrl].map(([url, streams]) => [
+ `ws_${digestCanonicalValue(url)}`,
+ digestCanonicalValue(streams.sort(compareUnicodeCodePoints)),
+ ]),
+ );
+};
+
+const webSocketPayloadMaps = (
+ beforeGroups: ReadonlyMap<string, WebSocketGroup>,
+ afterGroups: ReadonlyMap<string, WebSocketGroup>,
+ selected: boolean,
+): readonly [ReadonlyMap<string, string>, ReadonlyMap<string, string>] => {
+ const left = new Map<string, string>();
+ const right = new Map<string, string>();
+ for (const [groupKey, beforeGroup] of beforeGroups) {
+ const afterGroup = afterGroups.get(groupKey);
+ if (
+ afterGroup === undefined ||
+ beforeGroup.connections.length !== afterGroup.connections.length
+ )
+ continue;
+ const eventCount = beforeGroup.connections[0]?.events.length ?? 0;
+ const comparableBytes = new Set<number>();
+ const comparableShapes = new Set<number>();
+ for (let index = 0; index < eventCount; index += 1) {
+ if (
+ beforeGroup.connections.every(
+ (connection) => connection.events[index]?.payload_bytes !== null,
+ ) &&
+ afterGroup.connections.every(
+ (connection) => connection.events[index]?.payload_bytes !== null,
+ )
+ )
+ comparableBytes.add(index);
+ // Compare only when every same-metadata connection has shape evidence
+ // on both sides; this avoids assigning an unknown shape to a known one.
+ if (
+ selected &&
+ beforeGroup.connections.every(
+ (connection) => connection.events[index]?.payload_shape !== null,
+ ) &&
+ afterGroup.connections.every(
+ (connection) => connection.events[index]?.payload_shape !== null,
+ )
+ )
+ comparableShapes.add(index);
+ }
+ if (comparableBytes.size === 0 && comparableShapes.size === 0) continue;
+ const project = (group: WebSocketGroup) =>
+ digestCanonicalValue(
+ group.connections
+ .map((connection) =>
+ connection.events.map((event, index) => {
+ const comparablePayload: Record<string, unknown> = {};
+ if (comparableBytes.has(index))
+ comparablePayload.payload_bytes = event.payload_bytes;
+ if (comparableShapes.has(index))
+ comparablePayload.payload_shape = event.payload_shape;
+ return Object.keys(comparablePayload).length === 0
+ ? null
+ : comparablePayload;
+ }),
+ )
+ .map((stream) => digestCanonicalValue(stream))
+ .sort(compareUnicodeCodePoints),
+ );
+ const identity = `wss_${groupKey}`;
+ left.set(identity, project(beforeGroup));
+ right.set(identity, project(afterGroup));
+ }
+ return [left, right];
+};
+
const webMcpMap = (
discovery: WebMcpDiscovery | null,
): ReadonlyMap<string, string> =>
diff --git a/tests/boundary/browser/cdpBrowserProvider.sensitive_data.test.ts b/tests/boundary/browser/cdpBrowserProvider.sensitive_data.test.ts
index e079bead0..2a9662577 100644
--- a/tests/boundary/browser/cdpBrowserProvider.sensitive_data.test.ts
+++ b/tests/boundary/browser/cdpBrowserProvider.sensitive_data.test.ts
@@ -69,20 +69,24 @@ describe("CdpBrowserProvider: passive evidence redaction", () => {
line: 3,
column: 5,
});
- expect(result.value.network.websocket_events).toEqual([
+ expect(result.value.network.websocket_connections).toEqual([
{
request_id: "websocket-1",
- direction: "sent",
- opcode: 1,
- payload_bytes: Buffer.byteLength("websocket-secret"),
- payload_shape: null,
- },
- {
- request_id: "websocket-1",
- direction: "received",
- opcode: 2,
- payload_bytes: 3,
- payload_shape: null,
+ url: `ws://${new URL(browser.allowedOrigin).host}/live?token=websocket-url-secret`,
+ events: [
+ {
+ direction: "sent",
+ opcode: 1,
+ payload_bytes: Buffer.byteLength("websocket-secret"),
+ payload_shape: null,
+ },
+ {
+ direction: "received",
+ opcode: 2,
+ payload_bytes: 3,
+ payload_shape: null,
+ },
+ ],
},
]);
expect(result.value.console.events[0]?.argument_types).toEqual(["string"]);
@@ -288,27 +292,31 @@ describe("CdpBrowserProvider: explicitly requested text and payload shapes", ()
]),
},
});
- expect(result.value.network.websocket_events).toEqual([
+ expect(result.value.network.websocket_connections).toEqual([
expect.objectContaining({
- opcode: 1,
- payload_shape: expect.objectContaining({
- format: "json",
- json_shape: expect.objectContaining({
- properties: expect.arrayContaining([
- expect.objectContaining({
- path: [{ kind: "property", name: "token" }],
- types: ["string"],
+ events: [
+ expect.objectContaining({
+ opcode: 1,
+ payload_shape: expect.objectContaining({
+ format: "json",
+ json_shape: expect.objectContaining({
+ properties: expect.arrayContaining([
+ expect.objectContaining({
+ path: [{ kind: "property", name: "token" }],
+ types: ["string"],
+ }),
+ ]),
}),
- ]),
+ }),
}),
- }),
- }),
- expect.objectContaining({
- opcode: 2,
- payload_shape: {
- format: "binary",
- json_shape: null,
- },
+ expect.objectContaining({
+ opcode: 2,
+ payload_shape: {
+ format: "binary",
+ json_shape: null,
+ },
+ }),
+ ],
}),
]);
const serialized = JSON.stringify(result.value);
@@ -326,6 +334,29 @@ describe("CdpBrowserProvider: explicitly requested text and payload shapes", ()
});
});
+describe("CdpBrowserProvider: WebSocket connection projection", () => {
+ it("retains allowed connections created without observed frames", async () => {
+ const browser = await startFakeCdpBrowser({ webSocketWithoutFrames: true });
+ trackBrowser(browser);
+ const result = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ observation_ms: 0,
+ }),
+ );
+ if (!result.ok) throw result.error;
+ expect(result.value.network.websocket_connections).toEqual([
+ {
+ request_id: "websocket-1",
+ url: `ws://${new URL(browser.allowedOrigin).host}/live?token=websocket-url-secret`,
+ events: [],
+ },
+ ]);
+ });
+});
+
describe("CdpBrowserProvider: malformed approved payloads", () => {
it("fails closed on malformed approved response and binary payload encodings", async () => {
const browser = await startFakeCdpBrowser({
@@ -359,9 +390,11 @@ describe("CdpBrowserProvider: malformed approved payloads", () => {
// The security-relevant claim: malformed base64 never yields a shape.
response: null,
});
- expect(result.value.network.websocket_events[1]).toMatchObject({
+ expect(
+ result.value.network.websocket_connections[0]?.events[1],
+ ).toMatchObject({
opcode: 2,
- payload_bytes: 0,
+ payload_bytes: null,
payload_shape: { format: "binary", json_shape: null },
});
expect(result.value.completeness.unavailable_sections).toEqual(
diff --git a/tests/boundary/browser/cdpJsonShapeComparison.test.ts b/tests/boundary/browser/cdpJsonShapeComparison.test.ts
index 6784b478e..734a276eb 100644
--- a/tests/boundary/browser/cdpJsonShapeComparison.test.ts
+++ b/tests/boundary/browser/cdpJsonShapeComparison.test.ts
@@ -385,7 +385,7 @@ const captureBody = (source: BodySource, body: string): WebPageInspection => {
resources: [],
network: {
requests: [...events.network.values()],
- websocket_events: events.websockets,
+ websocket_connections: [...events.webSocketConnectionsById.values()],
coverage_started_at: CAPTURE_TIME,
prior_activity_available: false,
},
diff --git a/tests/boundary/browser/webCaptureDiff.test.ts b/tests/boundary/browser/webCaptureDiff.test.ts
index 290e94550..7a3698d77 100644
--- a/tests/boundary/browser/webCaptureDiff.test.ts
+++ b/tests/boundary/browser/webCaptureDiff.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it } from "vitest";
import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js";
import { inspectWebPageInputSchema } from "../../../src/domain/browserObservation.js";
+import type { WebPageInspection } from "../../../src/domain/browserObservationSchemas.js";
import { compareWebCaptures } from "../../../src/domain/webCaptureDiff.js";
import {
compareWebCapturesInputSchema,
@@ -126,7 +127,325 @@ describe("web capture diff", () => {
expect(result.dimensions.dom_structure.status).toBe("unknown");
expect(result.dimensions.dom_structure.reason).toContain("incomplete");
});
+});
+
+describe("web capture WebSocket comparison", () => {
+ it("compares complete ordered WebSocket streams by source URL, not request IDs", async () => {
+ const browser = await startFakeCdpBrowser({ binaryWebSocketEvent: true });
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ observation_ms: 0,
+ include_websocket_shapes: true,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const before = structuredClone(captured.value);
+ markSectionsComplete(before, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ "websocket_shapes",
+ ]);
+ expect(before.network.websocket_connections).toHaveLength(1);
+ expect(before.network.websocket_connections[0]?.url).toBe(
+ `ws://${new URL(browser.allowedOrigin).host}/live?token=websocket-url-secret`,
+ );
+ expect(before.network.websocket_connections[0]?.events).toHaveLength(2);
+
+ const idOnlyChange = structuredClone(before);
+ const idOnlyConnection = idOnlyChange.network.websocket_connections[0];
+ if (idOnlyConnection === undefined)
+ throw new Error("Missing captured WebSocket connection");
+ idOnlyConnection.request_id = "capture-local-id-2";
+ expect(compareNetwork(before, idOnlyChange)).toMatchObject({
+ status: "unchanged",
+ total_changes: 0,
+ });
+
+ const changeFrame = (
+ update: (
+ event: WebPageInspection["network"]["websocket_connections"][number]["events"][number],
+ ) => void,
+ ): WebPageInspection => {
+ const changed = structuredClone(before);
+ const event = changed.network.websocket_connections[0]?.events[0];
+ if (event === undefined)
+ throw new Error("Missing captured WebSocket frame");
+ update(event);
+ return changed;
+ };
+ const eventChanges: readonly ((
+ event: WebPageInspection["network"]["websocket_connections"][number]["events"][number],
+ ) => void)[] = [
+ (event) => {
+ event.direction = "received";
+ },
+ (event) => {
+ event.opcode = 2;
+ },
+ (event) => {
+ event.payload_shape = { format: "binary", json_shape: null };
+ },
+ ];
+ for (const update of eventChanges)
+ expect(compareNetwork(before, changeFrame(update)).status).toBe(
+ "changed",
+ );
+
+ const changed = structuredClone(before);
+ const connection = changed.network.websocket_connections[0];
+ const event = connection?.events[0];
+ if (connection === undefined || event === undefined)
+ throw new Error("Missing captured WebSocket frame");
+ if (event.payload_bytes === null)
+ throw new Error("Expected captured WebSocket byte count");
+ connection.request_id = "capture-local-id-3";
+ event.direction = "received";
+ event.opcode = 2;
+ event.payload_bytes += 1;
+ event.payload_shape = { format: "binary", json_shape: null };
+ expect(compareNetwork(before, changed)).toMatchObject({
+ status: "changed",
+ changes: [expect.objectContaining({ change: "modified" })],
+ });
+
+ const reordered = structuredClone(before);
+ reordered.network.websocket_connections[0]?.events.reverse();
+ expect(compareNetwork(before, reordered)).toMatchObject({
+ status: "changed",
+ changes: [expect.objectContaining({ change: "modified" })],
+ });
+
+ const addedEmptyConnection = structuredClone(before);
+ addedEmptyConnection.network.websocket_connections.push({
+ request_id: "new-empty-connection",
+ url: before.network.websocket_connections[0]!.url,
+ events: [],
+ });
+ expect(compareNetwork(before, addedEmptyConnection)).toMatchObject({
+ status: "changed",
+ changes: [expect.objectContaining({ change: "modified" })],
+ });
+ });
+});
+describe("web capture WebSocket shape comparison", () => {
+ it("aligns WebSocket shape streams only through common known coverage", async () => {
+ const browser = await startFakeCdpBrowser({ binaryWebSocketEvent: true });
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ observation_ms: 0,
+ include_websocket_shapes: true,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const before = structuredClone(captured.value);
+ markSectionsComplete(before, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ "websocket_shapes",
+ ]);
+
+ const sameUrlStreams = structuredClone(before);
+ sameUrlStreams.network.websocket_connections.push({
+ ...structuredClone(sameUrlStreams.network.websocket_connections[0]!),
+ request_id: "second-local-id",
+ });
+ const reorderedConnections = structuredClone(sameUrlStreams);
+ reorderedConnections.network.websocket_connections.reverse();
+ for (const [
+ index,
+ item,
+ ] of reorderedConnections.network.websocket_connections.entries())
+ item.request_id = `new-local-id-${String(index)}`;
+ expect(compareNetwork(sameUrlStreams, reorderedConnections)).toMatchObject({
+ status: "unchanged",
+ total_changes: 0,
+ });
+
+ const correlatedBefore = structuredClone(before);
+ const correlatedConnection =
+ correlatedBefore.network.websocket_connections[0]!;
+ const shape = (root_type: "string" | "number") => ({
+ format: "json" as const,
+ json_shape: {
+ root_type,
+ node_count: 1,
+ max_depth_observed: 0,
+ properties: [],
+ },
+ });
+ const firstShape = shape("string");
+ const secondShape = shape("number");
+ for (const connection of [
+ correlatedConnection,
+ {
+ ...structuredClone(correlatedConnection),
+ request_id: "second-correlated-connection",
+ },
+ ]) {
+ connection.events[0]!.payload_shape = structuredClone(firstShape);
+ connection.events[1]!.payload_shape = structuredClone(secondShape);
+ }
+ correlatedBefore.network.websocket_connections = [
+ correlatedConnection,
+ {
+ ...structuredClone(correlatedConnection),
+ request_id: "second-correlated-connection",
+ },
+ ];
+ const crossed = structuredClone(correlatedBefore);
+ crossed.network.websocket_connections[0]!.events[1]!.payload_shape =
+ structuredClone(firstShape);
+ crossed.network.websocket_connections[1]!.events[0]!.payload_shape =
+ structuredClone(secondShape);
+ crossed.network.websocket_connections[1]!.events[1]!.payload_shape =
+ structuredClone(firstShape);
+ expect(compareNetwork(correlatedBefore, crossed).status).toBe("changed");
+
+ const partialShapes = structuredClone(correlatedBefore);
+ partialShapes.network.websocket_connections[0]!.events[1]!.payload_shape =
+ null;
+ const ambiguousShapeChange = structuredClone(partialShapes);
+ ambiguousShapeChange.network.websocket_connections[1]!.events[1]!.payload_shape =
+ structuredClone(firstShape);
+ expect(compareNetwork(partialShapes, ambiguousShapeChange)).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ changes: [],
+ });
+ const changedKnownShape = structuredClone(partialShapes);
+ changedKnownShape.network.websocket_connections[0]!.events[0]!.payload_shape =
+ structuredClone(secondShape);
+ expect(compareNetwork(partialShapes, changedKnownShape).status).toBe(
+ "changed",
+ );
+ });
+});
+
+describe("web capture WebSocket shape coverage", () => {
+ it("keeps unchanged unknown when selected WebSocket shapes are unavailable", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ observation_ms: 0,
+ include_websocket_shapes: true,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const unavailable = structuredClone(captured.value);
+ markSectionsComplete(unavailable, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ ]);
+ unavailable.completeness.unavailable_sections.push("websocket_shapes");
+ for (const connection of unavailable.network.websocket_connections)
+ for (const event of connection.events) event.payload_shape = null;
+ expect(
+ compareNetwork(unavailable, structuredClone(unavailable)),
+ ).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ changes: [],
+ });
+
+ const observed = structuredClone(unavailable);
+ for (const connection of observed.network.websocket_connections)
+ for (const event of connection.events)
+ event.payload_shape = { format: "binary", json_shape: null };
+ for (const [left, right] of [
+ [unavailable, observed],
+ [observed, unavailable],
+ ] as const)
+ expect(compareNetwork(left, right)).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ changes: [],
+ });
+
+ const metadataChanged = structuredClone(observed);
+ metadataChanged.network.websocket_connections[0]!.events[0]!.opcode = 2;
+ expect(compareNetwork(unavailable, metadataChanged).status).toBe("changed");
+
+ const truncated = structuredClone(observed);
+ truncated.network.websocket_connections[0]!.events[0]!.payload_shape = null;
+ truncated.completeness.truncated_sections.push("websocket_shapes");
+ for (const [left, right] of [
+ [truncated, observed],
+ [observed, truncated],
+ ] as const)
+ expect(compareNetwork(left, right)).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ changes: [],
+ });
+ });
+});
+
+describe("web capture WebSocket payload byte coverage", () => {
+ it("keeps unknown byte counts out of differences while comparing known metadata", async () => {
+ const browser = await startFakeCdpBrowser({ binaryWebSocketEvent: true });
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ observation_ms: 0,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const known = structuredClone(captured.value);
+ markSectionsComplete(known, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ ]);
+ const unknownBytes = structuredClone(known);
+ unknownBytes.network.websocket_connections[0]!.events[1]!.payload_bytes =
+ null;
+ for (const [left, right] of [
+ [unknownBytes, known],
+ [known, unknownBytes],
+ ] as const)
+ expect(compareNetwork(left, right)).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ changes: [],
+ });
+
+ const knownMetadataChanged = structuredClone(unknownBytes);
+ knownMetadataChanged.network.websocket_connections[0]!.events[1]!.direction =
+ "sent";
+ expect(compareNetwork(unknownBytes, knownMetadataChanged).status).toBe(
+ "changed",
+ );
+
+ const knownBytesChanged = structuredClone(known);
+ const knownBytesEvent =
+ knownBytesChanged.network.websocket_connections[0]!.events[1]!;
+ if (knownBytesEvent.payload_bytes === null)
+ throw new Error("Expected captured WebSocket byte count");
+ knownBytesEvent.payload_bytes += 1;
+ expect(compareNetwork(known, knownBytesChanged).status).toBe("changed");
+ });
+});
+
+describe("web capture diff", () => {
it("ignores transient request IDs and capture-approval state", async () => {
const browser = await startFakeCdpBrowser();
browsers.push(browser);
@@ -194,7 +513,11 @@ describe("web capture redirect comparison", () => {
redirect_event_timestamp: 2,
},
];
- markSectionsComplete(before, ["network_requests"]);
+ markSectionsComplete(before, [
+ "network_requests",
+ "websocket_connections",
+ "websocket_frames",
+ ]);
const after = structuredClone(before);
const afterRequest = after.network.requests[0];
@@ -496,3 +819,11 @@ const markSectionsComplete = (
(section) => !completed.has(section),
);
};
+
+const compareNetwork = (before: WebPageInspection, after: WebPageInspection) =>
+ compareWebCaptures(
+ compareWebCapturesInputSchema.parse({
+ before: { inspection: before },
+ after: { inspection: after },
+ }),
+ ).dimensions.network;
diff --git a/tests/boundary/mcp/browserMcp.test.ts b/tests/boundary/mcp/browserMcp.test.ts
index 8e31e4839..17a8f404a 100644
--- a/tests/boundary/mcp/browserMcp.test.ts
+++ b/tests/boundary/mcp/browserMcp.test.ts
@@ -194,9 +194,9 @@ const verifySessionAndComparisonTools = async (
normalized_result: { overall_status: "unknown" },
});
const parsedCapture = webPageInspectionSchema.parse(capture);
- const socket = parsedCapture.network.websocket_events.find(
- (event) => event.payload_shape?.json_shape != null,
- );
+ const socket = parsedCapture.network.websocket_connections
+ .flatMap((connection) => connection.events)
+ .find((event) => event.payload_shape?.json_shape != null);
const payload = socket?.payload_shape;
if (socket === undefined || payload == null || payload.json_shape === null)
throw new Error("Missing deep WebSocket JSON shape fixture");
@@ -204,18 +204,27 @@ const verifySessionAndComparisonTools = async (
...parsedCapture,
network: {
...parsedCapture.network,
- websocket_events: [
- {
- ...socket,
- payload_shape: {
- ...payload,
- json_shape: {
- ...payload.json_shape,
- properties: [{ path: "/event", types: [42], observations: 1 }],
- },
- },
- },
- ],
+ websocket_connections: parsedCapture.network.websocket_connections.map(
+ (connection) => ({
+ ...connection,
+ events: connection.events.map((event) =>
+ event === socket
+ ? {
+ ...event,
+ payload_shape: {
+ ...payload,
+ json_shape: {
+ ...payload.json_shape,
+ properties: [
+ { path: "/event", types: [42], observations: 1 },
+ ],
+ },
+ },
+ }
+ : event,
+ ),
+ }),
+ ),
},
};
const malformedComparison = await connected.client.callTool({
diff --git a/tests/fixtures/fakeCdpBrowserEvents.ts b/tests/fixtures/fakeCdpBrowserEvents.ts
index dda7ba3cd..536cc8b72 100644
--- a/tests/fixtures/fakeCdpBrowserEvents.ts
+++ b/tests/fixtures/fakeCdpBrowserEvents.ts
@@ -516,6 +516,7 @@ const emitNetworkEvents = (
requestId: "websocket-1",
url: `ws://127.0.0.1:${String(port)}/live?token=websocket-url-secret`,
});
+ if (options.webSocketWithoutFrames === true) return;
event(socket, "Network.webSocketFrameSent", command.sessionId, {
requestId: "websocket-1",
response: {
diff --git a/tests/fixtures/fakeCdpBrowserTypes.ts b/tests/fixtures/fakeCdpBrowserTypes.ts
index e10917814..4fd45bb12 100644
--- a/tests/fixtures/fakeCdpBrowserTypes.ts
+++ b/tests/fixtures/fakeCdpBrowserTypes.ts
@@ -89,6 +89,8 @@ export interface FakeOptions {
readonly responseAfterMalformedUrl?: string;
readonly unrelatedWorker?: boolean;
readonly binaryWebSocketEvent?: boolean;
+ /** Emit an allowed WebSocket creation without any frames in the capture window. */
+ readonly webSocketWithoutFrames?: boolean;
readonly invalidBinaryWebSocketEvent?: boolean;
readonly sourceMapBody?: string;
readonly sessionTimeline?: