Skip to content

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.md
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,
+ );
+ });
+ });
});