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.mdindex 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.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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);