Skip to content

Chrome DevTools for coding agents

feat: add ignoreCache option to performance_start_trace (#2931)

Mathias Bynens3467d40da8f2
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 145f6c01..ace49e47 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -330,6 +330,7 @@
- **pageId** (number) **(required)**: Targets a specific page by ID.
- **autoStop** (boolean) _(optional)_: Determines if the trace recording should be automatically stopped.
- **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
+- **ignoreCache** (boolean) _(optional)_: Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true.
- **reload** (boolean) _(optional)_: Determines if, once tracing has started, the target page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
---
diff --git a/src/config/cli-options.ts b/src/config/cli-options.ts
index 4d11e304..55a5cd76 100644
--- a/src/config/cli-options.ts
+++ b/src/config/cli-options.ts
@@ -1358,6 +1358,13 @@ export const commands: Commands = {
required: false,
default: true,
},
+ ignoreCache: {
+ name: 'ignoreCache',
+ type: 'boolean',
+ description:
+ 'Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true.',
+ required: false,
+ },
filePath: {
name: 'filePath',
type: 'string',
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index bb41dcc6..c7ebb788 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -478,6 +478,10 @@
{
"name": "page_id",
"argType": "number"
+ },
+ {
+ "name": "ignore_cache",
+ "argType": "boolean"
}
]
},
diff --git a/src/third_party/index.ts b/src/third_party/index.ts
index 20815105..b0a4f002 100644
--- a/src/third_party/index.ts
+++ b/src/third_party/index.ts
@@ -60,6 +60,7 @@ export {
Target,
TargetType,
TimeoutError,
+ Tracing,
WebWorker,
WebMCP,
WebMCPTool,
diff --git a/src/tools/performance.ts b/src/tools/performance.ts
index 810ee2d9..beafff92 100644
--- a/src/tools/performance.ts
+++ b/src/tools/performance.ts
@@ -45,6 +45,12 @@ export const startTrace = definePageTool(() => ({
.describe(
'Determines if the trace recording should be automatically stopped.',
),
+ ignoreCache: zod
+ .boolean()
+ .optional()
+ .describe(
+ 'Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true.',
+ ),
filePath: filePathSchema,
},
blockedByDialog: true,
@@ -85,9 +91,21 @@ export const startTrace = definePageTool(() => ({
});
if (request.params.reload) {
- await page.pptrPage.goto(pageUrlForTracing, {
- waitUntil: ['load'],
- });
+ const ignoreCache = request.params.ignoreCache ?? false;
+ if (ignoreCache) {
+ // Disable the HTTP cache so that the main document and all
+ // subresources are fetched from the network, like a hard reload.
+ await page.pptrPage.setCacheEnabled(false);
+ }
+ try {
+ await page.pptrPage.goto(pageUrlForTracing, {
+ waitUntil: ['load'],
+ });
+ } finally {
+ if (ignoreCache) {
+ await page.pptrPage.setCacheEnabled(true);
+ }
+ }
}
if (request.params.autoStop) {
diff --git a/tests/mocks.ts b/tests/mocks.ts
index c3b78599..610b52f1 100644
--- a/tests/mocks.ts
+++ b/tests/mocks.ts
@@ -52,6 +52,7 @@ import {
Locator,
Target,
TargetType,
+ Tracing,
WebWorker,
WebMCP,
WebMCPTool,
@@ -235,6 +236,15 @@ export function createMockPuppeteerPage(): sinon.SinonStubbedInstance<Page> & {
configurable: true,
});
+ // The real `tracing` getter reads a private field, which throws on a stub
+ // instance, so it is replaced with a stubbed Tracing instance.
+ const tracing = sinon.createStubInstance(Tracing);
+ Object.defineProperty(page, 'tracing', {
+ value: tracing,
+ writable: true,
+ configurable: true,
+ });
+
page.evaluateHandle.resolves(createMockElementHandle().handle);
return Object.assign(page, {webmcp});
diff --git a/tests/tools/performance.test.ts b/tests/tools/performance.test.ts
index 1debe1bb..792ad5d4 100644
--- a/tests/tools/performance.test.ts
+++ b/tests/tools/performance.test.ts
@@ -49,7 +49,9 @@ describe('performance', () => {
await withMcpContext(async (response, context, args) => {
context.setIsRunningPerformanceTrace(false);
const selectedPage = context.getSelectedMcpPage().pptrPage;
- sinon.stub(selectedPage, 'url').callsFake(() => 'https://www.test.com');
+ sinon
+ .stub(selectedPage, 'url')
+ .callsFake(() => 'https://trace.example/');
sinon.stub(selectedPage, 'goto').resolves(null);
const startTracingStub = sinon.stub(selectedPage.tracing, 'start');
await startTrace(args).handler(
@@ -82,7 +84,9 @@ describe('performance', () => {
it('can navigate to about:blank and record a page reload', async () => {
await withMcpContext(async (response, context, args) => {
const selectedPage = context.getSelectedMcpPage().pptrPage;
- sinon.stub(selectedPage, 'url').callsFake(() => 'https://www.test.com');
+ sinon
+ .stub(selectedPage, 'url')
+ .callsFake(() => 'https://trace.example/');
const gotoStub = sinon.stub(selectedPage, 'goto');
const startTracingStub = sinon.stub(selectedPage.tracing, 'start');
await startTrace(args).handler(
@@ -97,7 +101,7 @@ describe('performance', () => {
sinon.assert.calledWithExactly(gotoStub, 'about:blank', {
waitUntil: 'load',
});
- sinon.assert.calledWithExactly(gotoStub, 'https://www.test.com', {
+ sinon.assert.calledWithExactly(gotoStub, 'https://trace.example/', {
waitUntil: ['load'],
});
assert.ok(context.isRunningPerformanceTrace());
@@ -109,12 +113,73 @@ describe('performance', () => {
});
});
+ it('disables the cache during the reload when ignoreCache is set', async () => {
+ const {page, context, response, args} = createHandlerMocks();
+ page.pptrPage.url.returns('https://cold-load.example/');
+
+ await startTrace(args).handler(
+ {params: {reload: true, autoStop: false, ignoreCache: true}, page},
+ response,
+ context,
+ );
+
+ const {goto, setCacheEnabled} = page.pptrPage;
+ sinon.assert.calledTwice(setCacheEnabled);
+ sinon.assert.calledWithExactly(setCacheEnabled.firstCall, false);
+ sinon.assert.calledWithExactly(setCacheEnabled.secondCall, true);
+ sinon.assert.calledWithExactly(
+ goto.secondCall,
+ 'https://cold-load.example/',
+ {waitUntil: ['load']},
+ );
+ assert.ok(setCacheEnabled.firstCall.calledAfter(goto.firstCall));
+ assert.ok(setCacheEnabled.firstCall.calledBefore(goto.secondCall));
+ assert.ok(setCacheEnabled.secondCall.calledAfter(goto.secondCall));
+ });
+
+ it('re-enables the cache if the reload fails when ignoreCache is set', async () => {
+ const {page, context, response, args} = createHandlerMocks();
+ page.pptrPage.url.returns('https://cold-load.example/');
+ const error = new Error('Navigation failed');
+ page.pptrPage.goto.onSecondCall().rejects(error);
+
+ await assert.rejects(
+ startTrace(args).handler(
+ {params: {reload: true, autoStop: false, ignoreCache: true}, page},
+ response,
+ context,
+ ),
+ error,
+ );
+
+ sinon.assert.calledTwice(page.pptrPage.setCacheEnabled);
+ sinon.assert.calledWithExactly(
+ page.pptrPage.setCacheEnabled.secondCall,
+ true,
+ );
+ });
+
+ it('does not touch the cache when ignoreCache is not set', async () => {
+ const {page, context, response, args} = createHandlerMocks();
+ page.pptrPage.url.returns('https://cold-load.example/');
+
+ await startTrace(args).handler(
+ {params: {reload: true, autoStop: false}, page},
+ response,
+ context,
+ );
+
+ sinon.assert.notCalled(page.pptrPage.setCacheEnabled);
+ });
+
it('can autostop and store a recording', async () => {
const rawData = loadTraceAsBuffer('basic-trace.json.gz');
await withMcpContext(async (response, context, args) => {
const selectedPage = context.getSelectedMcpPage().pptrPage;
- sinon.stub(selectedPage, 'url').callsFake(() => 'https://www.test.com');
+ sinon
+ .stub(selectedPage, 'url')
+ .callsFake(() => 'https://trace.example/');
sinon.stub(selectedPage, 'goto').callsFake(() => Promise.resolve(null));
const startTracingStub = sinon.stub(selectedPage.tracing, 'start');
const stopTracingStub = sinon
@@ -178,7 +243,9 @@ describe('performance', () => {
it('resets the running flag if a setup step throws', async () => {
await withMcpContext(async (response, context, args) => {
const selectedPage = context.getSelectedMcpPage().pptrPage;
- sinon.stub(selectedPage, 'url').callsFake(() => 'https://www.test.com');
+ sinon
+ .stub(selectedPage, 'url')
+ .callsFake(() => 'https://trace.example/');
const gotoStub = sinon
.stub(selectedPage, 'goto')
.rejects(new Error('Navigation failed'));
@@ -225,7 +292,9 @@ describe('performance', () => {
await withMcpContext(async (response, context, args) => {
const filePath = 'test-trace.json.gz';
const selectedPage = context.getSelectedMcpPage().pptrPage;
- sinon.stub(selectedPage, 'url').callsFake(() => 'https://www.test.com');
+ sinon
+ .stub(selectedPage, 'url')
+ .callsFake(() => 'https://trace.example/');
sinon.stub(selectedPage, 'goto').callsFake(() => Promise.resolve(null));
sinon.stub(selectedPage.tracing, 'start');
sinon.stub(selectedPage.tracing, 'stop').resolves(rawData);