Chrome DevTools for coding agents
feat: support device viewport and user agent emulation (#798)
Alex Rudenkoa8169676f920
diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex 9dccd3e7..aae061da 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -200,6 +200,8 @@- **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.- **geolocation** (unknown) _(optional)_: Geolocation to [`emulate`](#emulate). Set to null to clear the geolocation override.- **networkConditions** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.+- **userAgent** (unknown) _(optional)_: User agent to [`emulate`](#emulate). Set to null to clear the user agent override.+- **viewport** (unknown) _(optional)_: Viewport to [`emulate`](#emulate). Set to null to reset to the default viewport.---diff --git a/scripts/eval_scenarios/emulation_userAgent_test.ts b/scripts/eval_scenarios/emulation_userAgent_test.tsnew file mode 100644index 00000000..ee0cfc7e--- /dev/null+++ b/scripts/eval_scenarios/emulation_userAgent_test.ts@@ -0,0 +1,22 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';++import type {TestScenario} from '../eval_gemini.ts';++export const scenario: TestScenario = {+ prompt: 'Emulate iPhone 14 user agent',+ maxTurns: 2,+ expectations: calls => {+ assert.strictEqual(calls.length, 1);+ assert.strictEqual(calls[0].name, 'emulate');+ assert.deepStrictEqual(+ calls[0].args.userAgent,+ 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1',+ );+ },+};diff --git a/scripts/eval_scenarios/emulation_viewport_test.ts b/scripts/eval_scenarios/emulation_viewport_test.tsnew file mode 100644index 00000000..0aed9f77--- /dev/null+++ b/scripts/eval_scenarios/emulation_viewport_test.ts@@ -0,0 +1,31 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';++import {KnownDevices} from 'puppeteer';++import type {TestScenario} from '../eval_gemini.ts';++export const scenario: TestScenario = {+ prompt: 'Emulate iPhone 14 viewport',+ maxTurns: 2,+ expectations: calls => {+ assert.strictEqual(calls.length, 1);+ assert.strictEqual(calls[0].name, 'emulate');+ assert.deepStrictEqual(+ {+ ...(calls[0].args.viewport as object),+ // models might not send defaults.+ isLandscape: KnownDevices['iPhone 14'].viewport.isLandscape ?? false,+ },+ {+ ...KnownDevices['iPhone 14'].viewport,+ height: 844, // Puppeteer is wrong about the expected height.+ },+ );+ },+};diff --git a/src/McpContext.ts b/src/McpContext.tsindex f1c9019e..5c5f510c 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -28,6 +28,7 @@ import type {Page,SerializedAXNode,PredefinedNetworkConditions,+ Viewport,} from './third_party/index.js';import {listPages} from './tools/pages.js';import {takeSnapshot} from './tools/snapshot.js';@@ -115,6 +116,8 @@ export class McpContext implements Context {#networkConditionsMap = new WeakMap<Page, string>();#cpuThrottlingRateMap = new WeakMap<Page, number>();#geolocationMap = new WeakMap<Page, GeolocationOptions>();+ #viewportMap = new WeakMap<Page, Viewport>();+ #userAgentMap = new WeakMap<Page, string>();#dialog?: Dialog;#pageIdMap = new WeakMap<Page, number>();@@ -314,6 +317,34 @@ export class McpContext implements Context {return this.#geolocationMap.get(page) ?? null;}+ setViewport(viewport: Viewport | null): void {+ const page = this.getSelectedPage();+ if (viewport === null) {+ this.#viewportMap.delete(page);+ } else {+ this.#viewportMap.set(page, viewport);+ }+ }++ getViewport(): Viewport | null {+ const page = this.getSelectedPage();+ return this.#viewportMap.get(page) ?? null;+ }++ setUserAgent(userAgent: string | null): void {+ const page = this.getSelectedPage();+ if (userAgent === null) {+ this.#userAgentMap.delete(page);+ } else {+ this.#userAgentMap.set(page, userAgent);+ }+ }++ getUserAgent(): string | null {+ const page = this.getSelectedPage();+ return this.#userAgentMap.get(page) ?? null;+ }+setIsRunningPerformanceTrace(x: boolean): void {this.#isRunningTrace = x;}diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex eddfde07..4f628c7a 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -432,6 +432,18 @@ export class McpResponse implements Response {);}+ const viewport = context.getViewport();+ if (viewport) {+ response.push(`## Viewport emulation`);+ response.push(`Emulating viewport: ${JSON.stringify(viewport)}`);+ }++ const userAgent = context.getUserAgent();+ if (userAgent) {+ response.push(`## UserAgent emulation`);+ response.push(`Emulating userAgent: ${userAgent}`);+ }+const cpuThrottlingRate = context.getCpuThrottlingRate();if (cpuThrottlingRate > 1) {response.push(`## CPU emulation`);diff --git a/src/third_party/index.ts b/src/third_party/index.tsindex f7587cf8..55c09495 100644--- a/src/third_party/index.ts+++ b/src/third_party/index.ts@@ -25,6 +25,7 @@ export {z as zod} from 'zod';export {Locator,PredefinedNetworkConditions,+ KnownDevices,CDPSessionEvent,} from 'puppeteer-core';export {default as puppeteer} from 'puppeteer-core';diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex 73bc18d1..78d0432a 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -6,7 +6,12 @@import type {TextSnapshotNode, GeolocationOptions} from '../McpContext.js';import {zod} from '../third_party/index.js';-import type {Dialog, ElementHandle, Page} from '../third_party/index.js';+import type {+ Dialog,+ ElementHandle,+ Page,+ Viewport,+} from '../third_party/index.js';import type {TraceResult} from '../trace-processing/parse.js';import type {PaginationOptions} from '../utils/types.js';@@ -105,6 +110,10 @@ export type Context = Readonly<{setNetworkConditions(conditions: string | null): void;setCpuThrottlingRate(rate: number): void;setGeolocation(geolocation: GeolocationOptions | null): void;+ setViewport(viewport: Viewport | null): void;+ getViewport(): Viewport | null;+ setUserAgent(userAgent: string | null): void;+ getUserAgent(): string | null;saveTemporaryFile(data: Uint8Array<ArrayBufferLike>,mimeType: 'image/png' | 'image/jpeg' | 'image/webp',diff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex 13119250..325e05f0 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -2,6 +2,7 @@* @license* Copyright 2025 Google LLC* SPDX-License-Identifier: Apache-2.0+ **/import {zod, PredefinedNetworkConditions} from '../third_party/index.js';@@ -55,10 +56,56 @@ export const emulate = defineTool({.describe('Geolocation to emulate. Set to null to clear the geolocation override.',),+ userAgent: zod+ .string()+ .nullable()+ .optional()+ .describe(+ 'User agent to emulate. Set to null to clear the user agent override.',+ ),+ viewport: zod+ .object({+ width: zod.number().int().min(0).describe('Page width in pixels.'),+ height: zod.number().int().min(0).describe('Page height in pixels.'),+ deviceScaleFactor: zod+ .number()+ .min(0)+ .optional()+ .describe('Specify device scale factor (can be thought of as dpr).'),+ isMobile: zod+ .boolean()+ .optional()+ .describe(+ 'Whether the meta viewport tag is taken into account. Defaults to false.',+ ),+ hasTouch: zod+ .boolean()+ .optional()+ .describe(+ 'Specifies if viewport supports touch events. This should be set to true for mobile devices.',+ ),+ isLandscape: zod+ .boolean()+ .optional()+ .describe(+ 'Specifies if viewport is in landscape mode. Defaults to false.',+ ),+ })+ .nullable()+ .optional()+ .describe(+ 'Viewport to emulate. Set to null to reset to the default viewport.',+ ),},handler: async (request, _response, context) => {const page = context.getSelectedPage();- const {networkConditions, cpuThrottlingRate, geolocation} = request.params;+ const {+ networkConditions,+ cpuThrottlingRate,+ geolocation,+ userAgent,+ viewport,+ } = request.params;if (networkConditions) {if (networkConditions === 'No emulation') {@@ -96,5 +143,35 @@ export const emulate = defineTool({context.setGeolocation(geolocation);}}++ if (userAgent !== undefined) {+ if (userAgent === null) {+ await page.setUserAgent({+ userAgent: undefined,+ });+ context.setUserAgent(null);+ } else {+ await page.setUserAgent({+ userAgent,+ });+ context.setUserAgent(userAgent);+ }+ }++ if (viewport !== undefined) {+ if (viewport === null) {+ await page.setViewport(null);+ context.setViewport(null);+ } else {+ const defaults = {+ deviceScaleFactor: 1,+ isMobile: false,+ hasTouch: false,+ isLandscape: false,+ };+ await page.setViewport({...defaults, ...viewport});+ context.setViewport({...defaults, ...viewport});+ }+ }},});diff --git a/tests/McpResponse.test.js.snapshot b/tests/McpResponse.test.js.snapshotindex 461c98d2..678305fc 100644--- a/tests/McpResponse.test.js.snapshot+++ b/tests/McpResponse.test.js.snapshot@@ -74,6 +74,18 @@ Emulating: Slow 3GDefault navigation timeout set to 100000 ms`;+exports[`McpResponse > adds userAgent emulation setting when it is set 1`] = `+# test response+## UserAgent emulation+Emulating userAgent: MyUA+`;++exports[`McpResponse > adds viewport emulation setting when it is set 1`] = `+# test response+## Viewport emulation+Emulating viewport: {"width":400,"height":400,"deviceScaleFactor":1}+`;+exports[`McpResponse > allows response text lines to be added 1`] = `# test responseTesting 1diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.tsindex f6c68b37..41e50fd4 100644--- a/tests/McpResponse.test.ts+++ b/tests/McpResponse.test.ts@@ -182,6 +182,22 @@ describe('McpResponse', () => {});});+ it('adds viewport emulation setting when it is set', async t => {+ await withMcpContext(async (response, context) => {+ context.setViewport({width: 400, height: 400, deviceScaleFactor: 1});+ const {content} = await response.handle('test', context);+ t.assert.snapshot?.(getTextContent(content[0]));+ });+ });++ it('adds userAgent emulation setting when it is set', async t => {+ await withMcpContext(async (response, context) => {+ context.setUserAgent('MyUA');+ const {content} = await response.handle('test', context);+ t.assert.snapshot?.(getTextContent(content[0]));+ });+ });+it('adds a prompt dialog', async t => {await withMcpContext(async (response, context) => {const page = context.getSelectedPage();diff --git a/tests/tools/emulation.test.ts b/tests/tools/emulation.test.tsindex 5275f564..0ad78449 100644--- a/tests/tools/emulation.test.ts+++ b/tests/tools/emulation.test.ts@@ -5,12 +5,15 @@*/import assert from 'node:assert';-import {describe, it} from 'node:test';+import {beforeEach, describe, it} from 'node:test';import {emulate} from '../../src/tools/emulation.js';-import {withMcpContext} from '../utils.js';+import {serverHooks} from '../server.js';+import {html, withMcpContext} from '../utils.js';describe('emulation', () => {+ const server = serverHooks();+describe('network', () => {it('emulates offline network conditions', async () => {await withMcpContext(async (response, context) => {@@ -234,4 +237,234 @@ describe('emulation', () => {});});});+ describe('viewport', () => {+ beforeEach(() => {+ server.addHtmlRoute('/viewport', html`Test page`);+ });++ it('emulates viewport', async () => {+ await withMcpContext(async (response, context) => {+ const page = context.getSelectedPage();+ await page.goto(server.baseUrl + '/viewport');+ await emulate.handler(+ {+ params: {+ viewport: {+ width: 400,+ height: 400,+ deviceScaleFactor: 2,+ isMobile: true,+ hasTouch: true,+ isLandscape: false,+ },+ },+ },+ response,+ context,+ );++ const viewportData = await page.evaluate(() => {+ return {+ width: window.innerWidth,+ height: window.innerHeight,+ deviceScaleFactor: window.devicePixelRatio,+ hasTouch: navigator.maxTouchPoints > 0,+ };+ });++ assert.deepStrictEqual(viewportData, {+ width: 400,+ height: 400,+ deviceScaleFactor: 2,+ hasTouch: true,+ });+ });+ });++ it('clears viewport override when viewport is set to null', async () => {+ await withMcpContext(async (response, context) => {+ const page = context.getSelectedPage();+ // First set a viewport+ await emulate.handler(+ {+ params: {+ viewport: {+ width: 400,+ height: 400,+ },+ },+ },+ response,+ context,+ );++ const viewportData = await page.evaluate(() => {+ return {+ width: window.innerWidth,+ height: window.innerHeight,+ };+ });++ assert.deepStrictEqual(viewportData, {+ width: 400,+ height: 400,+ });++ // Then clear it by setting viewport to null+ await emulate.handler(+ {+ params: {+ viewport: null,+ },+ },+ response,+ context,+ );++ assert.strictEqual(context.getViewport(), null);++ // Somehow reset of the viewport seems to be async.+ await context.getSelectedPage().waitForFunction(() => {+ return window.innerWidth !== 400 && window.innerHeight !== 400;+ });+ });+ });++ it('reports correctly for the currently selected page', async () => {+ await withMcpContext(async (response, context) => {+ await emulate.handler(+ {+ params: {+ viewport: {+ width: 400,+ height: 400,+ },+ },+ },+ response,+ context,+ );++ assert.ok(context.getViewport());++ const page = await context.newPage();+ context.selectPage(page);++ assert.strictEqual(context.getViewport(), null);+ assert.ok(+ await context.getSelectedPage().evaluate(() => {+ return window.innerWidth !== 400 && window.innerHeight !== 400;+ }),+ );+ });+ });+ });++ describe('userAgent', () => {+ it('emulates userAgent', async () => {+ await withMcpContext(async (response, context) => {+ await emulate.handler(+ {+ params: {+ userAgent: 'MyUA',+ },+ },+ response,+ context,+ );++ assert.strictEqual(context.getUserAgent(), 'MyUA');+ const page = context.getSelectedPage();+ const ua = await page.evaluate(() => navigator.userAgent);+ assert.strictEqual(ua, 'MyUA');+ });+ });++ it('updates userAgent', async () => {+ await withMcpContext(async (response, context) => {+ await emulate.handler(+ {+ params: {+ userAgent: 'UA1',+ },+ },+ response,+ context,+ );+ assert.strictEqual(context.getUserAgent(), 'UA1');++ await emulate.handler(+ {+ params: {+ userAgent: 'UA2',+ },+ },+ response,+ context,+ );+ assert.strictEqual(context.getUserAgent(), 'UA2');+ const page = context.getSelectedPage();+ const ua = await page.evaluate(() => navigator.userAgent);+ assert.strictEqual(ua, 'UA2');+ });+ });++ it('clears userAgent override when userAgent is set to null', async () => {+ await withMcpContext(async (response, context) => {+ await emulate.handler(+ {+ params: {+ userAgent: 'MyUA',+ },+ },+ response,+ context,+ );++ assert.strictEqual(context.getUserAgent(), 'MyUA');++ await emulate.handler(+ {+ params: {+ userAgent: null,+ },+ },+ response,+ context,+ );++ assert.strictEqual(context.getUserAgent(), null);+ const page = context.getSelectedPage();+ const ua = await page.evaluate(() => navigator.userAgent);+ assert.notStrictEqual(ua, 'MyUA');+ assert.ok(ua.length > 0);+ });+ });++ it('reports correctly for the currently selected page', async () => {+ await withMcpContext(async (response, context) => {+ await emulate.handler(+ {+ params: {+ userAgent: 'MyUA',+ },+ },+ response,+ context,+ );++ assert.strictEqual(context.getUserAgent(), 'MyUA');++ const page = await context.newPage();+ context.selectPage(page);++ assert.strictEqual(context.getUserAgent(), null);+ assert.ok(+ await context.getSelectedPage().evaluate(() => {+ return navigator.userAgent !== 'MyUA';+ }),+ );+ });+ });+ });});