Chrome DevTools for coding agents
fix: simplify emulation and script tools (#1073)
Alex Rudenkoe51ba4720338
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex f1fe4640..9f64034c 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -119,3 +119,10 @@ export const scenario: TestScenario = {},};```++## Restrictions on JSON schema++- no .nullable(), no .object() types.+- represent complex object as a short formatted string.++TODO: implement eslint for schema https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1076diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex 8c33310d..d11829c5 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -1,6 +1,6 @@<!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->-# Chrome DevTools MCP Tool Reference (~7324 cl100k_base tokens)+# Chrome DevTools MCP Tool Reference (~6919 cl100k_base tokens)- **[Input automation](#input-automation)** (9 tools)- [`click`](#click)@@ -222,11 +222,11 @@**Parameters:**- **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.-- **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.+- **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling+- **geolocation** (string) _(optional)_: Geolocation (`<latitude>x<longitude>`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.+- **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.+- **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.+- **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.---diff --git a/src/McpContext.ts b/src/McpContext.tsindex 0d8b6d76..8cb44f64 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -306,115 +306,95 @@ export class McpContext implements Context {async emulate(options: {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | 'auto' | null;- viewport?: Viewport | null;+ networkConditions?: string;+ cpuThrottlingRate?: number;+ geolocation?: GeolocationOptions;+ userAgent?: string;+ colorScheme?: 'dark' | 'light' | 'auto';+ viewport?: Viewport;},targetPage?: Page,): Promise<void> {const page = targetPage ?? this.getSelectedPptrPage();const mcpPage = this.#getMcpPage(page);const newSettings: EmulationSettings = {...mcpPage.emulationSettings};- let timeoutsNeedUpdate = false;-- if (options.networkConditions !== undefined) {- timeoutsNeedUpdate = true;- if (- options.networkConditions === null ||- options.networkConditions === 'No emulation'- ) {- await page.emulateNetworkConditions(null);- delete newSettings.networkConditions;- } else if (options.networkConditions === 'Offline') {- await page.emulateNetworkConditions({- offline: true,- download: 0,- upload: 0,- latency: 0,- });- newSettings.networkConditions = 'Offline';- } else if (options.networkConditions in PredefinedNetworkConditions) {- const networkCondition =- PredefinedNetworkConditions[- options.networkConditions as keyof typeof PredefinedNetworkConditions- ];- await page.emulateNetworkConditions(networkCondition);- newSettings.networkConditions = options.networkConditions;- }- }- if (options.cpuThrottlingRate !== undefined) {- timeoutsNeedUpdate = true;- if (options.cpuThrottlingRate === null) {- await page.emulateCPUThrottling(1);- delete newSettings.cpuThrottlingRate;- } else {- await page.emulateCPUThrottling(options.cpuThrottlingRate);- newSettings.cpuThrottlingRate = options.cpuThrottlingRate;- }+ if (!options.networkConditions) {+ await page.emulateNetworkConditions(null);+ delete newSettings.networkConditions;+ } else if (options.networkConditions === 'Offline') {+ await page.emulateNetworkConditions({+ offline: true,+ download: 0,+ upload: 0,+ latency: 0,+ });+ newSettings.networkConditions = 'Offline';+ } else if (options.networkConditions in PredefinedNetworkConditions) {+ const networkCondition =+ PredefinedNetworkConditions[+ options.networkConditions as keyof typeof PredefinedNetworkConditions+ ];+ await page.emulateNetworkConditions(networkCondition);+ newSettings.networkConditions = options.networkConditions;+ }++ if (!options.cpuThrottlingRate) {+ await page.emulateCPUThrottling(1);+ delete newSettings.cpuThrottlingRate;+ } else {+ await page.emulateCPUThrottling(options.cpuThrottlingRate);+ newSettings.cpuThrottlingRate = options.cpuThrottlingRate;}- if (options.geolocation !== undefined) {- if (options.geolocation === null) {- await page.setGeolocation({latitude: 0, longitude: 0});- delete newSettings.geolocation;- } else {- await page.setGeolocation(options.geolocation);- newSettings.geolocation = options.geolocation;- }+ if (!options.geolocation) {+ await page.setGeolocation({latitude: 0, longitude: 0});+ delete newSettings.geolocation;+ } else {+ await page.setGeolocation(options.geolocation);+ newSettings.geolocation = options.geolocation;}- if (options.userAgent !== undefined) {- if (options.userAgent === null) {- await page.setUserAgent({userAgent: undefined});- delete newSettings.userAgent;- } else {- await page.setUserAgent({userAgent: options.userAgent});- newSettings.userAgent = options.userAgent;- }+ if (!options.userAgent) {+ await page.setUserAgent({userAgent: undefined});+ delete newSettings.userAgent;+ } else {+ await page.setUserAgent({userAgent: options.userAgent});+ newSettings.userAgent = options.userAgent;}- if (options.colorScheme !== undefined) {- if (options.colorScheme === null || options.colorScheme === 'auto') {- await page.emulateMediaFeatures([- {name: 'prefers-color-scheme', value: ''},- ]);- delete newSettings.colorScheme;- } else {- await page.emulateMediaFeatures([- {name: 'prefers-color-scheme', value: options.colorScheme},- ]);- newSettings.colorScheme = options.colorScheme;- }+ if (!options.colorScheme || options.colorScheme === 'auto') {+ await page.emulateMediaFeatures([+ {name: 'prefers-color-scheme', value: ''},+ ]);+ delete newSettings.colorScheme;+ } else {+ await page.emulateMediaFeatures([+ {name: 'prefers-color-scheme', value: options.colorScheme},+ ]);+ newSettings.colorScheme = options.colorScheme;}- if (options.viewport !== undefined) {- if (options.viewport === null) {- await page.setViewport(null);- delete newSettings.viewport;- } else {- const defaults = {- deviceScaleFactor: 1,- isMobile: false,- hasTouch: false,- isLandscape: false,- };- const viewport = {...defaults, ...options.viewport};- await page.setViewport(viewport);- newSettings.viewport = viewport;- }+ if (!options.viewport) {+ await page.setViewport(null);+ delete newSettings.viewport;+ } else {+ const defaults = {+ deviceScaleFactor: 1,+ isMobile: false,+ hasTouch: false,+ isLandscape: false,+ };+ const viewport = {...defaults, ...options.viewport};+ await page.setViewport(viewport);+ newSettings.viewport = viewport;}mcpPage.emulationSettings = Object.keys(newSettings).length? newSettings: {};- if (timeoutsNeedUpdate) {- this.#updateSelectedPageTimeouts();- }+ this.#updateSelectedPageTimeouts();}setIsRunningPerformanceTrace(x: boolean): void {diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex 543b202d..5230a4db 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -150,12 +150,12 @@ export type Context = Readonly<{restoreEmulation(page: ContextPage): Promise<void>;emulate(options: {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | 'auto' | null;- viewport?: Viewport | null;+ networkConditions?: string;+ cpuThrottlingRate?: number;+ geolocation?: GeolocationOptions;+ userAgent?: string;+ colorScheme?: 'dark' | 'light' | 'auto';+ viewport?: Viewport;},targetPage?: Page,): Promise<void>;@@ -310,3 +310,46 @@ export const timeoutSchema = {return value && value <= 0 ? undefined : value;}),};++export function viewportTransform(arg: string | undefined):+ | {+ width: number;+ height: number;+ deviceScaleFactor?: number;+ isMobile?: boolean;+ isLandscape?: boolean;+ hasTouch?: boolean;+ }+ | undefined {+ if (!arg) {+ return undefined;+ }+ const [dimensions, ...tags] = arg.split(',');+ const isMobile = tags.includes('mobile');+ const hasTouch = tags.includes('touch');+ const isLandscape = tags.includes('landscape');+ const [width, height, dpr] = dimensions.split('x').map(Number) as [+ number,+ number,+ number | undefined,+ ];+ return {+ width,+ height,+ deviceScaleFactor: dpr,+ isMobile: isMobile,+ isLandscape: isLandscape,+ hasTouch: hasTouch,+ };+}++export function geolocationTransform(arg: string | undefined) {+ if (!arg) {+ return undefined;+ }+ const [latitude, longitude] = arg.split('x').map(Number) as [number, number];+ return {+ latitude,+ longitude,+ };+}diff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex ed6ded49..66eaa849 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -8,10 +8,13 @@import {zod, PredefinedNetworkConditions} from '../third_party/index.js';import {ToolCategory} from './categories.js';-import {definePageTool} from './ToolDefinition.js';+import {+ definePageTool,+ geolocationTransform,+ viewportTransform,+} from './ToolDefinition.js';const throttlingOptions: [string, ...string[]] = [- 'No emulation','Offline',...Object.keys(PredefinedNetworkConditions),];@@ -27,41 +30,27 @@ export const emulate = definePageTool({networkConditions: zod.enum(throttlingOptions).optional()- .describe(- `Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.`,- ),+ .describe(`Throttle network. Omit to disable throttling.`),cpuThrottlingRate: zod.number().min(1).max(20).optional().describe(- 'Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.',+ 'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling',),geolocation: zod- .object({- latitude: zod- .number()- .min(-90)- .max(90)- .describe('Latitude between -90 and 90.'),- longitude: zod- .number()- .min(-180)- .max(180)- .describe('Longitude between -180 and 180.'),- })- .nullable()+ .string().optional()+ .transform(geolocationTransform).describe(- 'Geolocation to emulate. Set to null to clear the geolocation override.',+ 'Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.',),userAgent: zod.string()- .nullable().optional().describe(- 'User agent to emulate. Set to null to clear the user agent override.',+ 'User agent to emulate. Set to empty string to clear the user agent override.',),colorScheme: zod.enum(['dark', 'light', 'auto'])@@ -70,37 +59,11 @@ export const emulate = definePageTool({'Emulate the dark or the light mode. Set to "auto" to reset to the default.',),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()+ .string().optional()+ .transform(viewportTransform).describe(- 'Viewport to emulate. Set to null to reset to the default viewport.',+ `Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`,),},handler: async (request, _response, context) => {diff --git a/src/tools/script.ts b/src/tools/script.tsindex fa2d18c1..e3ff14d7 100644--- a/src/tools/script.ts+++ b/src/tools/script.ts@@ -38,13 +38,11 @@ Example with arguments: \`(el) => {),args: zod.array(- zod.object({- uid: zod- .string()- .describe(- 'The uid of an element on the page from the page content snapshot',- ),- }),+ zod+ .string()+ .describe(+ 'The uid of an element on the page from the page content snapshot',+ ),).optional().describe(`An optional list of arguments to pass to the function.`),@@ -91,8 +89,8 @@ Example with arguments: \`(el) => {const args: Array<JSHandle<unknown>> = [];try {const frames = new Set<Frame>();- for (const el of uidArgs ?? []) {- const handle = await mcpPage.getElementByUid(el.uid);+ for (const uid of uidArgs ?? []) {+ const handle = await mcpPage.getElementByUid(uid);frames.add(handle.frame);args.push(handle);}diff --git a/src/types.ts b/src/types.tsindex a85796ed..4efd8dc9 100644--- a/src/types.ts+++ b/src/types.ts@@ -36,10 +36,10 @@ export interface TextSnapshot {}export interface EmulationSettings {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | null;- viewport?: Viewport | null;+ networkConditions?: string;+ cpuThrottlingRate?: number;+ geolocation?: GeolocationOptions;+ userAgent?: string;+ colorScheme?: 'dark' | 'light';+ viewport?: Viewport;}diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.tsindex 141f4f0b..0936a1e2 100644--- a/tests/McpResponse.test.ts+++ b/tests/McpResponse.test.ts@@ -302,7 +302,7 @@ describe('McpResponse', () => {'test',context,);- await context.emulate({networkConditions: null});+ await context.emulate({});assert.equal(content[0].type, 'text');assert.strictEqual(getTextContent(content[0]), `# test response`);t.assert.snapshot?.(diff --git a/tests/tools/emulation.test.ts b/tests/tools/emulation.test.tsindex 36e45aa2..721505fc 100644--- a/tests/tools/emulation.test.ts+++ b/tests/tools/emulation.test.ts@@ -8,12 +8,81 @@ import assert from 'node:assert';import {beforeEach, describe, it} from 'node:test';import {emulate} from '../../src/tools/emulation.js';+import {+ geolocationTransform,+ viewportTransform,+} from '../../src/tools/ToolDefinition.js';import {serverHooks} from '../server.js';import {html, withMcpContext} from '../utils.js';describe('emulation', () => {const server = serverHooks();+ describe('transforms', () => {+ describe('viewportTransform', () => {+ it('returns undefined for undefined input', () => {+ assert.strictEqual(viewportTransform(undefined), undefined);+ });++ it('parses basic dimensions', () => {+ assert.deepStrictEqual(viewportTransform('800x600'), {+ width: 800,+ height: 600,+ deviceScaleFactor: undefined,+ isMobile: false,+ isLandscape: false,+ hasTouch: false,+ });+ });++ it('parses dimensions with devicePixelRatio', () => {+ assert.deepStrictEqual(viewportTransform('1024x768x2'), {+ width: 1024,+ height: 768,+ deviceScaleFactor: 2,+ isMobile: false,+ isLandscape: false,+ hasTouch: false,+ });+ });++ it('parses mobile and touch tags', () => {+ assert.deepStrictEqual(viewportTransform('375x667x2,mobile,touch'), {+ width: 375,+ height: 667,+ deviceScaleFactor: 2,+ isMobile: true,+ hasTouch: true,+ isLandscape: false,+ });+ });++ it('parses landscape tag', () => {+ assert.deepStrictEqual(viewportTransform('1024x768x1,landscape'), {+ width: 1024,+ height: 768,+ deviceScaleFactor: 1,+ isMobile: false,+ hasTouch: false,+ isLandscape: true,+ });+ });+ });++ describe('geolocationTransform', () => {+ it('returns undefined for undefined input', () => {+ assert.strictEqual(geolocationTransform(undefined), undefined);+ });++ it('parses latitude and longitude', () => {+ assert.deepStrictEqual(geolocationTransform('48.137154x11.576124'), {+ latitude: 48.137154,+ longitude: 11.576124,+ });+ });+ });+ });+describe('network', () => {it('emulates offline network conditions', async () => {await withMcpContext(async (response, context) => {@@ -58,9 +127,7 @@ describe('emulation', () => {await withMcpContext(async (response, context) => {await emulate.handler({- params: {- networkConditions: 'No emulation',- },+ params: {},page: context.getSelectedMcpPage(),},response,@@ -229,9 +296,7 @@ describe('emulation', () => {// Then clear it by setting geolocation to nullawait emulate.handler({- params: {- geolocation: null,- },+ params: {},page: context.getSelectedMcpPage(),},response,@@ -347,9 +412,7 @@ describe('emulation', () => {// Then clear it by setting viewport to nullawait emulate.handler({- params: {- viewport: null,- },+ params: {},page: context.getSelectedMcpPage(),},response,@@ -465,9 +528,7 @@ describe('emulation', () => {await emulate.handler({- params: {- userAgent: null,- },+ params: {},page: context.getSelectedMcpPage(),},response,diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.tsindex 78736726..90c1b34b 100644--- a/tests/tools/script.test.ts+++ b/tests/tools/script.test.ts@@ -137,7 +137,7 @@ describe('script', () => {function: String(async (el: Element) => {return el.id;}),- args: [{uid: '1_1'}],+ args: ['1_1'],},},response,@@ -162,7 +162,7 @@ describe('script', () => {function: String((container: Element, child: Element) => {return container.contains(child);}),- args: [{uid: '1_0'}, {uid: '1_1'}],+ args: ['1_0', '1_1'],},},response,@@ -190,7 +190,7 @@ describe('script', () => {function: String((element: Element) => {return element.textContent;}),- args: [{uid: '1_3'}],+ args: ['1_3'],},},response,@@ -286,7 +286,7 @@ describe('script', () => {params: {function: String(() => 'test'),serviceWorkerId: 'example_service_worker',- args: [{uid: '1_1'}],+ args: ['1_1'],},},response,