Chrome DevTools for coding agents
feat: support emulating additional CSS media features (#2929)
Mathias Bynens69524f0948d0
diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex f0ad98c8..145f6c01 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -285,8 +285,11 @@- **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. Omit or set the rate to 1 to disable throttling- **extraHttpHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.+- **forcedColors** (enum: "active", "none", "auto") _(optional)_: [`Emulate`](#emulate) the `forced-colors` CSS media feature. Set to "auto" to reset to the default.- **geolocation** (string) _(optional)_: Geolocation (`<latitude>,<longitude>`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.- **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.+- **prefersContrast** (enum: "more", "less", "custom", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.+- **prefersReducedMotion** (enum: "reduce", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.- **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/McpPage.ts b/src/McpPage.tsindex 76ac0489..22d8538c 100644--- a/src/McpPage.ts+++ b/src/McpPage.ts@@ -40,7 +40,10 @@ import type {} from './tools/ToolDefinition.js';import type {EmulationSettings,+ ForcedColors,GeolocationOptions,+ PrefersContrast,+ PrefersReducedMotion,TextSnapshotNode,} from './types.js';import {logger} from './utils/logger.js';@@ -594,6 +597,18 @@ export class McpPage implements ContextPage {return this.emulationSettings.colorScheme ?? null;}+ get forcedColors(): ForcedColors | null {+ return this.emulationSettings.forcedColors ?? null;+ }++ get prefersContrast(): PrefersContrast | null {+ return this.emulationSettings.prefersContrast ?? null;+ }++ get prefersReducedMotion(): PrefersReducedMotion | null {+ return this.emulationSettings.prefersReducedMotion ?? null;+ }+// Public for testability: tests spy on this method to verify throttle multipliers.createWaitForHelper(cpuMultiplier: number,@@ -1055,12 +1070,30 @@ export class McpPage implements ContextPage {await this.emulate(currentSetting);}+ async #emulateMediaFeatures(settings: EmulationSettings): Promise<void> {+ // `page.emulateMediaFeatures` replaces all previously emulated media+ // features, so every supported feature is sent on each call. An empty+ // value disables the override for that feature.+ await this.pptrPage.emulateMediaFeatures([+ {name: 'prefers-color-scheme', value: settings.colorScheme ?? ''},+ {name: 'forced-colors', value: settings.forcedColors ?? ''},+ {name: 'prefers-contrast', value: settings.prefersContrast ?? ''},+ {+ name: 'prefers-reduced-motion',+ value: settings.prefersReducedMotion ?? '',+ },+ ]);+ }+async emulate(options: {networkConditions?: string;cpuThrottlingRate?: number;geolocation?: GeolocationOptions;userAgent?: string;colorScheme?: 'dark' | 'light' | 'auto';+ forcedColors?: ForcedColors | 'auto';+ prefersContrast?: PrefersContrast | 'auto';+ prefersReducedMotion?: PrefersReducedMotion | 'auto';viewport?: Viewport;extraHttpHeaders?: Record<string, string> | undefined;}): Promise<void> {@@ -1130,17 +1163,34 @@ export class McpPage implements ContextPage {}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.forcedColors || options.forcedColors === 'auto') {+ delete newSettings.forcedColors;+ } else {+ newSettings.forcedColors = options.forcedColors;+ }++ if (!options.prefersContrast || options.prefersContrast === 'auto') {+ delete newSettings.prefersContrast;+ } else {+ newSettings.prefersContrast = options.prefersContrast;+ }++ if (+ !options.prefersReducedMotion ||+ options.prefersReducedMotion === 'auto'+ ) {+ delete newSettings.prefersReducedMotion;+ } else {+ newSettings.prefersReducedMotion = options.prefersReducedMotion;+ }++ await this.#emulateMediaFeatures(newSettings);+if (!options.viewport) {delete newSettings.viewport;} else {diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 0b835569..8b820941 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -885,6 +885,9 @@ export class McpResponse implements Response {userAgent?: string;cpuThrottlingRate?: number;colorScheme?: string;+ forcedColors?: string;+ prefersContrast?: string;+ prefersReducedMotion?: string;dialog?: {type: string;message: string;@@ -1011,6 +1014,26 @@ export class McpResponse implements Response {structuredContent.colorScheme = colorScheme;}+ const forcedColors = this.#page?.forcedColors;+ if (forcedColors) {+ response.push(`Emulating forced-colors: ${forcedColors}`);+ structuredContent.forcedColors = forcedColors;+ }++ const prefersContrast = this.#page?.prefersContrast;+ if (prefersContrast) {+ response.push(`Emulating prefers-contrast: ${prefersContrast}`);+ structuredContent.prefersContrast = prefersContrast;+ }++ const prefersReducedMotion = this.#page?.prefersReducedMotion;+ if (prefersReducedMotion) {+ response.push(+ `Emulating prefers-reduced-motion: ${prefersReducedMotion}`,+ );+ structuredContent.prefersReducedMotion = prefersReducedMotion;+ }+const dialog = this.#page?.getDialog();if (dialog) {const defaultValueIfNeeded =diff --git a/src/config/cli-options.ts b/src/config/cli-options.tsindex 67403590..4d11e304 100644--- a/src/config/cli-options.ts+++ b/src/config/cli-options.ts@@ -276,6 +276,30 @@ export const commands: Commands = {required: false,enum: ['dark', 'light', 'auto'],},+ forcedColors: {+ name: 'forcedColors',+ type: 'string',+ description:+ 'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',+ required: false,+ enum: ['active', 'none', 'auto'],+ },+ prefersContrast: {+ name: 'prefersContrast',+ type: 'string',+ description:+ 'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',+ required: false,+ enum: ['more', 'less', 'custom', 'no-preference', 'auto'],+ },+ prefersReducedMotion: {+ name: 'prefersReducedMotion',+ type: 'string',+ description:+ 'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',+ required: false,+ enum: ['reduce', 'no-preference', 'auto'],+ },viewport: {name: 'viewport',type: 'string',diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.jsonindex 57bbeba5..bb41dcc6 100644--- a/src/telemetry/tool_call_metrics.json+++ b/src/telemetry/tool_call_metrics.json@@ -105,6 +105,18 @@{"name": "page_id","argType": "number"+ },+ {+ "name": "forced_colors",+ "argType": "string"+ },+ {+ "name": "prefers_contrast",+ "argType": "string"+ },+ {+ "name": "prefers_reduced_motion",+ "argType": "string"}]},diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex f539ca4f..1003dc8d 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -43,6 +43,9 @@ import type {GeolocationOptions,CD4ACommentThread,PaginationOptions,+ ForcedColors,+ PrefersContrast,+ PrefersReducedMotion,} from '../types.js';import type {McpWorker} from '../McpWorker.js';import type {@@ -426,6 +429,9 @@ export type ContextPage = Readonly<{geolocation?: GeolocationOptions;userAgent?: string;colorScheme?: 'dark' | 'light' | 'auto';+ forcedColors?: ForcedColors | 'auto';+ prefersContrast?: PrefersContrast | 'auto';+ prefersReducedMotion?: PrefersReducedMotion | 'auto';viewport?: Viewport;}): Promise<void>;waitForTextOnPage(text: string[], timeout?: number): Promise<Element>;diff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex 0255b947..7ccacb6a 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -6,6 +6,11 @@*/import {zod, PredefinedNetworkConditions} from '../third_party/index.js';+import {+ FORCED_COLORS_VALUES,+ PREFERS_CONTRAST_VALUES,+ PREFERS_REDUCED_MOTION_VALUES,+} from '../types.js';import {ToolCategory} from './categories.js';import {@@ -84,6 +89,24 @@ export const emulate = definePageTool(() => ({.describe('Emulate the dark or the light mode. Set to "auto" to reset to the default.',),+ forcedColors: zod+ .enum([...FORCED_COLORS_VALUES, 'auto'])+ .optional()+ .describe(+ 'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',+ ),+ prefersContrast: zod+ .enum([...PREFERS_CONTRAST_VALUES, 'auto'])+ .optional()+ .describe(+ 'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',+ ),+ prefersReducedMotion: zod+ .enum([...PREFERS_REDUCED_MOTION_VALUES, 'auto'])+ .optional()+ .describe(+ 'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',+ ),viewport: zod.string().transform(viewportTransform)diff --git a/src/types.ts b/src/types.tsindex b91ae792..320faed3 100644--- a/src/types.ts+++ b/src/types.ts@@ -22,12 +22,33 @@ export interface GeolocationOptions {longitude: number;}+export const FORCED_COLORS_VALUES = ['active', 'none'] as const;+export type ForcedColors = (typeof FORCED_COLORS_VALUES)[number];++export const PREFERS_CONTRAST_VALUES = [+ 'more',+ 'less',+ 'custom',+ 'no-preference',+] as const;+export type PrefersContrast = (typeof PREFERS_CONTRAST_VALUES)[number];++export const PREFERS_REDUCED_MOTION_VALUES = [+ 'reduce',+ 'no-preference',+] as const;+export type PrefersReducedMotion =+ (typeof PREFERS_REDUCED_MOTION_VALUES)[number];+export interface EmulationSettings {networkConditions?: string;cpuThrottlingRate?: number;geolocation?: GeolocationOptions;userAgent?: string;colorScheme?: 'dark' | 'light';+ forcedColors?: ForcedColors;+ prefersContrast?: PrefersContrast;+ prefersReducedMotion?: PrefersReducedMotion;viewport?: Viewport;extraHttpHeaders?: Record<string, string>;}diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.tsindex 6e475a25..a341d6f4 100644--- a/tests/McpPage.test.ts+++ b/tests/McpPage.test.ts@@ -539,24 +539,74 @@ describe('McpPage', () => {});});- it('calls emulateMediaFeatures with dark color scheme', async () => {- const {mcpPage, pptrPage} = await createMcpPage();- await mcpPage.emulate({colorScheme: 'dark'});- assert.strictEqual(mcpPage.colorScheme, 'dark');- sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [- {name: 'prefers-color-scheme', value: 'dark'},- ]);- });+ describe('media features', () => {+ it('emulates all media features in a single call', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ await mcpPage.emulate({+ colorScheme: 'dark',+ forcedColors: 'active',+ prefersContrast: 'more',+ prefersReducedMotion: 'reduce',+ });+ assert.strictEqual(mcpPage.colorScheme, 'dark');+ assert.strictEqual(mcpPage.forcedColors, 'active');+ assert.strictEqual(mcpPage.prefersContrast, 'more');+ assert.strictEqual(mcpPage.prefersReducedMotion, 'reduce');+ sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [+ {name: 'prefers-color-scheme', value: 'dark'},+ {name: 'forced-colors', value: 'active'},+ {name: 'prefers-contrast', value: 'more'},+ {name: 'prefers-reduced-motion', value: 'reduce'},+ ]);+ });- it('calls emulateMediaFeatures with empty string to reset color scheme', async () => {- const {mcpPage, pptrPage} = await createMcpPage();- await mcpPage.emulate({colorScheme: 'dark'});- await mcpPage.emulate({colorScheme: 'auto'});- assert.strictEqual(mcpPage.colorScheme, null);- sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);- sinon.assert.calledWithExactly(pptrPage.emulateMediaFeatures.secondCall, [- {name: 'prefers-color-scheme', value: ''},- ]);+ it('resets media features set to auto', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ await mcpPage.emulate({+ colorScheme: 'dark',+ forcedColors: 'active',+ prefersContrast: 'more',+ prefersReducedMotion: 'reduce',+ });+ await mcpPage.emulate({+ colorScheme: 'auto',+ forcedColors: 'auto',+ prefersContrast: 'auto',+ prefersReducedMotion: 'auto',+ });+ assert.strictEqual(mcpPage.colorScheme, null);+ assert.strictEqual(mcpPage.forcedColors, null);+ assert.strictEqual(mcpPage.prefersContrast, null);+ assert.strictEqual(mcpPage.prefersReducedMotion, null);+ sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);+ sinon.assert.calledWithExactly(+ pptrPage.emulateMediaFeatures.secondCall,+ [+ {name: 'prefers-color-scheme', value: ''},+ {name: 'forced-colors', value: ''},+ {name: 'prefers-contrast', value: ''},+ {name: 'prefers-reduced-motion', value: ''},+ ],+ );+ });++ it('resets omitted media features', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ await mcpPage.emulate({forcedColors: 'active'});+ await mcpPage.emulate({prefersContrast: 'less'});+ assert.strictEqual(mcpPage.forcedColors, null);+ assert.strictEqual(mcpPage.prefersContrast, 'less');+ sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);+ sinon.assert.calledWithExactly(+ pptrPage.emulateMediaFeatures.secondCall,+ [+ {name: 'prefers-color-scheme', value: ''},+ {name: 'forced-colors', value: ''},+ {name: 'prefers-contrast', value: 'less'},+ {name: 'prefers-reduced-motion', value: ''},+ ],+ );+ });});it('calls setViewport with the given dimensions merged with defaults', async () => {diff --git a/tests/ToolHandler.test.ts b/tests/ToolHandler.test.tsindex 70723158..7c244629 100644--- a/tests/ToolHandler.test.ts+++ b/tests/ToolHandler.test.ts@@ -1283,6 +1283,9 @@ describe('ToolHandler', () => {sinon.stub(mockPage, 'viewport').get(() => undefined);sinon.stub(mockPage, 'userAgent').get(() => undefined);sinon.stub(mockPage, 'colorScheme').get(() => undefined);+ sinon.stub(mockPage, 'forcedColors').get(() => undefined);+ sinon.stub(mockPage, 'prefersContrast').get(() => undefined);+ sinon.stub(mockPage, 'prefersReducedMotion').get(() => undefined);sinon.stub(mockPage, 'cpuThrottlingRate').get(() => 1);mockContext.getSelectedMcpPage.returns(mockPage);const canonicalFilePath = path.resolve('/canonical/output.png');diff --git a/tests/tools/emulation.test.ts b/tests/tools/emulation.test.tsindex e9387459..c4a44f1e 100644--- a/tests/tools/emulation.test.ts+++ b/tests/tools/emulation.test.ts@@ -9,6 +9,7 @@ import {afterEach, describe, it} from 'node:test';import sinon from 'sinon';+import {zod} from '../../src/third_party/index.js';import {emulate} from '../../src/tools/emulation.js';import {geolocationTransform,@@ -557,4 +558,48 @@ describe('emulation', () => {});});});++ describe('media features', () => {+ it('emulates forced-colors, prefers-contrast and prefers-reduced-motion', async () => {+ const {page, context, response, args} = createHandlerMocks();+ await emulate(args).handler(+ {+ params: {+ forcedColors: 'active',+ prefersContrast: 'more',+ prefersReducedMotion: 'reduce',+ },+ page,+ },+ response,+ context,+ );+ sinon.assert.calledOnceWithExactly(page.emulate, {+ forcedColors: 'active',+ prefersContrast: 'more',+ prefersReducedMotion: 'reduce',+ });+ sinon.assert.calledOnceWithExactly(+ response.appendResponseLine,+ 'Emulation configured successfully',+ );+ });++ it('rejects unsupported values', () => {+ const {args} = createHandlerMocks();+ const schema = zod.object(emulate(args).schema);+ assert.strictEqual(+ schema.safeParse({forcedColors: 'inactive'}).success,+ false,+ );+ assert.strictEqual(+ schema.safeParse({prefersContrast: 'high'}).success,+ false,+ );+ assert.strictEqual(+ schema.safeParse({prefersReducedMotion: 'yes'}).success,+ false,+ );+ });+ });});