Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import assert from 'node:assert';
import fs from 'node:fs/promises';
import {describe, it} from 'node:test';
import sinon from 'sinon';
import type {NetworkOverride} from '../../src/NetworkOverrideManager.js';
import {NetworkOverridesFormatter} from '../../src/formatters/NetworkOverridesFormatter.js';
import {
mockNetwork,
removeNetworkMock,
getNetworkRequest,
listNetworkRequests,
} from '../../src/tools/network.js';
import {createHandlerMocks, createMockParsedArguments} from '../mocks.js';
describe('network', () => {
describe('network mocks', () => {
it('rejects relative and empty routes with an actionable warning', () => {
const schema = mockNetwork(createMockParsedArguments()).schema.route;
for (const route of ['/app.js*', ' ']) {
assert.strictEqual(schema.safeParse(route).success, false);
}
assert.throws(() => schema.parse('/app.js*'), /absolute URLPattern/);
assert.strictEqual(schema.parse(' *://*:*/app.js '), '*://*:*/app.js');
});
it('rejects regex and named groups in routes for inspection, updates and removal', () => {
const args = createMockParsedArguments();
for (const tool of [mockNetwork(args), removeNetworkMock(args)]) {
for (const route of [
'https://example.com/(app|other).js',
'https://example.com/:name.js',
'https://:host/app.js',
'https://example.com/app.js?version=:version',
]) {
assert.throws(() => tool.schema.route.parse(route), /group/);
}
}
});
for (const params of [
{body: './script.js', upstream: 'https://example.com/script.js'},
{body: ' '},
{upstream: 'file:///tmp/script.js'},
{allowOrigin: 'https://example.com\r\nX-Header: value'},
{allowOrigin: '\n*\n'},
{allowOrigin: ' '},
{allowOrigin: 'https://example.com/path'},
{allowOrigin: 'https://example.com/'},
{allowOrigin: 'https://example.com?query=1'},
{allowOrigin: 'https://example.com#fragment'},
{allowOrigin: 'https://user:[email protected]'},
{allowOrigin: 'https://example.com:443'},
{allowOrigin: 'https://example.com https://other.example'},
{allowOrigin: 'example.com'},
{allowOrigin: 'file:///tmp/script.js'},
{route: '/app.js*', abort: true},
{resourceType: 'websocket', abort: true},
{route: '*app.js*', body: './app.js'},
{route: 'https://example.com/:file', body: './app.js'},
{route: 'https://example.com/(app|other).js', body: './app.js'},
]) {
it(
'rejects invalid mock parameters before any state change: ' +
JSON.stringify(params),
async () => {
const {page, context, response, args} = createHandlerMocks();
await assert.rejects(
mockNetwork(args).handler({params, page}, response, context),
);
sinon.assert.notCalled(context.validatePath);
sinon.assert.notCalled(page.mockNetwork);
sinon.assert.notCalled(page.listNetworkMocks);
sinon.assert.notCalled(response.appendResponseLine);
},
);
}
it('accepts wildcard, null, and serialized origins for allowOrigin', () => {
const schema = mockNetwork(createMockParsedArguments()).schema
.allowOrigin;
for (const origin of [
'*',
'null',
'https://example.com',
'http://localhost:8080',
'https://[::1]:8443',
]) {
assert.strictEqual(schema.parse(origin), origin);
}
});
it('updates an upstream mock with the exact supplied actions', async () => {
const {page, context, response, args} = createHandlerMocks();
const override = {
id: 7,
kind: 'upstream',
urlPattern: 'https://example.com/script.js*',
resourceType: 'script',
upstreamUrl: 'https://example.com/replacement.js',
allowOrigin: '*',
diagnostics: {hits: 0, errors: 0, navigations: 0},
} satisfies NetworkOverride;
page.mockNetwork.resolves(override);
await mockNetwork(args).handler(
{
params: {
route: override.urlPattern,
resourceType: 'script',
upstream: override.upstreamUrl,
allowOrigin: '*',
},
page,
},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
kind: 'upstream',
urlPattern: override.urlPattern,
resourceType: 'script',
upstreamUrl: override.upstreamUrl,
abort: undefined,
allowOrigin: '*',
});
sinon.assert.notCalled(page.listNetworkMocks);
sinon.assert.notCalled(context.validatePath);
sinon.assert.calledWithExactly(
response.appendResponseLine.firstCall,
'Network mock configured. Reload or navigate the page to apply it.',
);
sinon.assert.calledWithExactly(
response.appendResponseLine.secondCall,
new NetworkOverridesFormatter([override]).toString(),
);
});
for (const abort of [true, false]) {
it(
'treats abort=' + abort + ' as an update without inventing a source',
async () => {
const {page, context, response, args} = createHandlerMocks();
page.mockNetwork.resolves({
id: 1,
kind: 'passthrough',
urlPattern: '*://*:*/*',
resourceType: 'script',
abort,
diagnostics: {hits: 0, errors: 0, navigations: 0},
});
await mockNetwork(args).handler(
{params: {resourceType: 'script', abort}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
urlPattern: undefined,
resourceType: 'script',
abort,
allowOrigin: undefined,
});
sinon.assert.notCalled(page.listNetworkMocks);
},
);
}
it('updates only allowOrigin without replacing an existing source', async () => {
const {page, context, response, args} = createHandlerMocks();
page.mockNetwork.resolves({
id: 1,
kind: 'upstream',
urlPattern: '*://*:*/*',
upstreamUrl: 'https://example.com/app.js',
allowOrigin: '*',
diagnostics: {hits: 0, errors: 0, navigations: 0},
});
await mockNetwork(args).handler(
{params: {allowOrigin: '*'}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
urlPattern: undefined,
resourceType: undefined,
abort: undefined,
allowOrigin: '*',
});
sinon.assert.notCalled(page.listNetworkMocks);
});
it('configures an upstream source while aborting matching requests', async () => {
const {page, context, response, args} = createHandlerMocks();
page.mockNetwork.resolves({
id: 1,
kind: 'upstream',
urlPattern: '*://*:*/*',
upstreamUrl: 'https://example.com/app.js',
abort: true,
diagnostics: {hits: 0, errors: 0, navigations: 0},
});
await mockNetwork(args).handler(
{params: {upstream: 'https://example.com/app.js', abort: true}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
kind: 'upstream',
urlPattern: undefined,
resourceType: undefined,
abort: true,
allowOrigin: undefined,
upstreamUrl: 'https://example.com/app.js',
});
sinon.assert.notCalled(page.listNetworkMocks);
});
it('propagates upstream policy failures without reporting success', async () => {
const {page, context, response, args} = createHandlerMocks();
page.mockNetwork.rejects(new Error('Blocked by blocklist'));
await assert.rejects(
mockNetwork(args).handler(
{params: {upstream: 'https://blocked.example/script.js'}, page},
response,
context,
),
/Blocked by blocklist/,
);
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
kind: 'upstream',
urlPattern: undefined,
resourceType: undefined,
abort: undefined,
allowOrigin: undefined,
upstreamUrl: 'https://blocked.example/script.js',
});
sinon.assert.notCalled(response.appendResponseLine);
});
it('revalidates the canonical body file before each read', async () => {
const {page, context, response, args} = createHandlerMocks();
context.validatePath.resolves('/tmp/script.js');
page.mockNetwork.resolves({
id: 1,
kind: 'file',
urlPattern: '*://*:*/*',
responseFilePath: '/tmp/script.js',
contentType: 'application/javascript; charset=utf-8',
diagnostics: {hits: 0, errors: 0, navigations: 0},
});
const readFile = sinon
.stub(fs, 'readFile')
.resolves(Buffer.from('updated'));
await mockNetwork(args).handler(
{params: {body: '/tmp/script.js'}, page},
response,
context,
);
const input = page.mockNetwork.firstCall.args[0];
assert.ok(input.kind === 'file');
sinon.assert.calledOnceWithExactly(page.mockNetwork, {
kind: 'file',
urlPattern: undefined,
resourceType: undefined,
abort: undefined,
allowOrigin: undefined,
responseFilePath: '/tmp/script.js',
loadResponseFile: input.loadResponseFile,
});
sinon.assert.notCalled(context.validatePath);
sinon.assert.notCalled(readFile);
assert.deepStrictEqual(
await input.loadResponseFile(),
Buffer.from('updated'),
);
sinon.assert.calledOnceWithExactly(
context.validatePath,
'/tmp/script.js',
);
sinon.assert.calledOnceWithMatch(
readFile,
sinon.match.same('/tmp/script.js'),
);
context.validatePath.rejects(new Error('Access denied'));
readFile.resetHistory();
await assert.rejects(input.loadResponseFile(), /Access denied/);
sinon.assert.notCalled(readFile);
});
for (const params of [
{},
{route: '*://*:*/app.js'},
{resourceType: 'script'},
{route: '*://*:*/app.js', resourceType: 'script'},
] satisfies Array<{route?: string; resourceType?: 'script'}>) {
it(
'inspects supplied filters without changing mocks: ' +
JSON.stringify(params),
async () => {
const {page, context, response, args} = createHandlerMocks();
page.listNetworkMocks.returns([]);
await mockNetwork(args).handler({params, page}, response, context);
sinon.assert.calledOnceWithExactly(page.listNetworkMocks, {
urlPattern: params.route,
resourceType: params.resourceType,
});
sinon.assert.notCalled(page.mockNetwork);
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'No network mocks match these filters.',
);
},
);
}
it('formats hit counts, unmatched warnings and replacement errors when inspecting', async () => {
const {page, context, response, args} = createHandlerMocks();
page.listNetworkMocks.returns([
{
id: 1,
diagnostics: {
hits: 2,
errors: 1,
navigations: 1,
lastError: 'File missing',
},
kind: 'file',
urlPattern: '*://*:*/*.js',
resourceType: 'script',
responseFilePath: '/tmp/script.js',
contentType: 'text/javascript',
},
{
id: 2,
diagnostics: {hits: 0, errors: 0, navigations: 1},
kind: 'upstream',
urlPattern: 'https://example.com/missing.js',
upstreamUrl: 'https://example.com/replacement.js',
},
]);
await mockNetwork(args).handler({params: {}, page}, response, context);
sinon.assert.calledOnceWithExactly(page.listNetworkMocks, {
urlPattern: undefined,
resourceType: undefined,
});
sinon.assert.notCalled(page.mockNetwork);
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
new NetworkOverridesFormatter(
page.listNetworkMocks.firstCall.returnValue,
).toString(),
);
});
});
describe('remove_network_mock', () => {
for (const params of [
{},
{route: '*://*:*/app.js'},
{resourceType: 'script'},
{route: '*://*:*/app.js', resourceType: 'script'},
] satisfies Array<{route?: string; resourceType?: 'script'}>) {
it('removes supplied filters: ' + JSON.stringify(params), async () => {
const {page, context, response, args} = createHandlerMocks();
page.removeNetworkMocks.resolves(2);
await removeNetworkMock(args).handler(
{params, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.removeNetworkMocks, {
urlPattern: params.route,
resourceType: params.resourceType,
});
sinon.assert.notCalled(page.mockNetwork);
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'Removed 2 network mocks.',
);
});
}
it('reports when no mock matched for removal', async () => {
const {page, context, response, args} = createHandlerMocks();
page.removeNetworkMocks.resolves(0);
await removeNetworkMock(args).handler(
{params: {route: '*://*:*/*'}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(page.removeNetworkMocks, {
urlPattern: '*://*:*/*',
resourceType: undefined,
});
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'Removed 0 network mocks.',
);
});
it('propagates removal failure without reporting success', async () => {
const {page, context, response, args} = createHandlerMocks();
page.removeNetworkMocks.rejects(
new Error('Cannot change mocks during a trace'),
);
await assert.rejects(
removeNetworkMock(args).handler({params: {}, page}, response, context),
/during a trace/,
);
sinon.assert.notCalled(response.appendResponseLine);
});
});
describe('list_network_requests', () => {
it('describes the default preserved navigation history', () => {
const tool = listNetworkRequests(createMockParsedArguments());
assert.strictEqual(
tool.schema.includePreservedRequests.description,
'Set to true to return the preserved requests over the last 3 navigations.',
);
});
it('describes preserved requests using maxNavigationSaved', () => {
const tool = listNetworkRequests(
createMockParsedArguments({maxNavigationSaved: 5}),
);
assert.strictEqual(
tool.schema.includePreservedRequests.description,
'Set to true to return the preserved requests over the last 5 navigations.',
);
});
it('handles default parameters', async () => {
const {page, context, response, args} = createHandlerMocks();
page.getDevToolsData.resolves({});
await listNetworkRequests(args).handler(
{params: {}, page},
response,
context,
);
sinon.assert.calledOnce(page.getDevToolsData);
sinon.assert.calledOnceWithExactly(response.attachDevToolsData, {});
sinon.assert.calledOnceWithExactly(
response.setIncludeNetworkRequests,
true,
{
pageSize: undefined,
pageIdx: undefined,
resourceTypes: undefined,
includePreservedRequests: undefined,
networkRequestIdInDevToolsUI: undefined,
},
);
});
it('passes custom filters and pagination options', async () => {
const {page, context, response, args} = createHandlerMocks();
page.getDevToolsData.resolves({});
await listNetworkRequests(args).handler(
{
params: {
pageSize: 25,
pageIdx: 1,
resourceTypes: ['xhr', 'fetch'],
includePreservedRequests: true,
},
page,
},
response,
context,
);
sinon.assert.calledOnceWithExactly(
response.setIncludeNetworkRequests,
true,
{
pageSize: 25,
pageIdx: 1,
resourceTypes: ['xhr', 'fetch'],
includePreservedRequests: true,
networkRequestIdInDevToolsUI: undefined,
},
);
});
it('resolves cdpRequestId from DevTools data when present', async () => {
const {page, context, response, args} = createHandlerMocks();
const devToolsData = {
cdpRequestId: 'req-cdp-123',
};
page.getDevToolsData.resolves(devToolsData);
page.resolveCdpRequestId.withArgs('req-cdp-123').returns(42);
await listNetworkRequests(args).handler(
{params: {}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(
response.attachDevToolsData,
devToolsData,
);
sinon.assert.calledOnceWithExactly(
page.resolveCdpRequestId,
'req-cdp-123',
);
sinon.assert.calledOnceWithExactly(
response.setIncludeNetworkRequests,
true,
{
pageSize: undefined,
pageIdx: undefined,
resourceTypes: undefined,
includePreservedRequests: undefined,
networkRequestIdInDevToolsUI: 42,
},
);
});
});
describe('get_network_request', () => {
it('attaches request with explicit reqid', async () => {
const {page, context, response, args} = createHandlerMocks();
await getNetworkRequest(args).handler(
{params: {reqid: 10}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(response.attachNetworkRequest, 10, {
requestFilePath: undefined,
responseFilePath: undefined,
});
sinon.assert.notCalled(page.getDevToolsData);
});
it('forwards requestFilePath and responseFilePath when reqid is provided', async () => {
const {page, context, response, args} = createHandlerMocks();
await getNetworkRequest(args).handler(
{
params: {
reqid: 10,
requestFilePath: '/path/req.txt',
responseFilePath: '/path/res.txt',
},
page,
},
response,
context,
);
sinon.assert.calledOnceWithExactly(response.attachNetworkRequest, 10, {
requestFilePath: '/path/req.txt',
responseFilePath: '/path/res.txt',
});
});
it('falls back to DevTools selected request when reqid is omitted', async () => {
const {page, context, response, args} = createHandlerMocks();
const devToolsData = {
cdpRequestId: 'req-cdp-selected',
};
page.getDevToolsData.resolves(devToolsData);
page.resolveCdpRequestId.withArgs('req-cdp-selected').returns(99);
await getNetworkRequest(args).handler(
{
params: {
requestFilePath: '/path/req.txt',
responseFilePath: '/path/res.txt',
},
page,
},
response,
context,
);
sinon.assert.calledOnce(page.getDevToolsData);
sinon.assert.calledOnceWithExactly(
response.attachDevToolsData,
devToolsData,
);
sinon.assert.calledOnceWithExactly(
page.resolveCdpRequestId,
'req-cdp-selected',
);
sinon.assert.calledOnceWithExactly(response.attachNetworkRequest, 99, {
requestFilePath: '/path/req.txt',
responseFilePath: '/path/res.txt',
});
});
it('appends message when reqid is omitted and nothing is selected in DevTools', async () => {
const {page, context, response, args} = createHandlerMocks();
page.getDevToolsData.resolves({});
await getNetworkRequest(args).handler(
{params: {}, page},
response,
context,
);
sinon.assert.calledOnce(page.getDevToolsData);
sinon.assert.calledOnceWithExactly(response.attachDevToolsData, {});
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'Nothing is currently selected in the DevTools Network panel.',
);
sinon.assert.notCalled(response.attachNetworkRequest);
});
it('appends message when DevTools data exists but cdpRequestId cannot be resolved', async () => {
const {page, context, response, args} = createHandlerMocks();
page.getDevToolsData.resolves({cdpRequestId: 'unknown-cdp-id'});
page.resolveCdpRequestId.withArgs('unknown-cdp-id').returns(undefined);
await getNetworkRequest(args).handler(
{params: {}, page},
response,
context,
);
sinon.assert.calledOnceWithExactly(
page.resolveCdpRequestId,
'unknown-cdp-id',
);
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'Nothing is currently selected in the DevTools Network panel.',
);
sinon.assert.notCalled(response.attachNetworkRequest);
});
});
});