Implementation:Puppeteer Puppeteer Cdp EmulationManager

Property	Value
sources	packages/puppeteer-core/src/cdp/EmulationManager.ts
domains	Device Emulation, CDP, Browser Automation
last_updated	2026-02-12 00:00 GMT

Overview

Description

The EmulationManager class manages all device and environment emulation via the CDP Emulation domain. It maintains a collection of EmulatedState objects, each representing a distinct emulation aspect (viewport, timezone, geolocation, etc.) that can be synchronized across multiple CDP sessions -- including speculative/prerender sessions.

Key emulation capabilities include:

• Viewport emulation -- Setting device metrics (width, height, device scale factor, mobile mode, touch, orientation) via Emulation.setDeviceMetricsOverride.
• Idle state emulation -- Overriding user idle detection via Emulation.setIdleOverride.
• Timezone emulation -- Overriding the browser timezone via Emulation.setTimezoneOverride.
• Vision deficiency emulation -- Simulating color blindness and other vision conditions via Emulation.setEmulatedVisionDeficiency.
• CPU throttling -- Simulating slower CPUs via Emulation.setCPUThrottlingRate.
• Media features -- Overriding CSS media features (prefers-color-scheme, prefers-reduced-motion, color-gamut) via Emulation.setEmulatedMedia.
• Media type -- Overriding CSS media type (screen/print) via Emulation.setEmulatedMedia.
• Geolocation -- Setting geolocation coordinates via Emulation.setGeolocationOverride.
• Background color -- Setting or clearing the default background color via Emulation.setDefaultBackgroundColorOverride.
• JavaScript control -- Enabling/disabling JavaScript execution via Emulation.setScriptExecutionDisabled.
• Focus emulation -- Controlling focus emulation via Emulation.setFocusEmulationEnabled.

The EmulatedState<T> generic class encapsulates each emulation state along with an updater function. When state changes, it syncs across all registered CDP sessions (primary and secondary/speculative). The @invokeAtMostOnceForArguments decorator is used to prevent redundant CDP calls for the same client+state combination.

Usage

The EmulationManager is used internally by CdpPage and is not directly exposed to users. Users interact with emulation through Page methods like page.setViewport(), page.emulateTimezone(), etc.

Code Reference

Source Location: packages/puppeteer-core/src/cdp/EmulationManager.ts (611 lines)

Signature:

export class EmulatedState<T extends { active: boolean }> {
  constructor(
    initialState: T,
    clientProvider: ClientProvider,
    updater: (client: CDPSession, state: T) => Promise<void>,
  );
  async setState(state: T): Promise<void>;
  get state(): T;
  async sync(): Promise<void>;
}

export class EmulationManager implements ClientProvider {
  constructor(client: CDPSession);
  async emulateViewport(viewport: Viewport | null): Promise<boolean>;
  async emulateIdleState(overrides?: { isUserActive: boolean; isScreenUnlocked: boolean }): Promise<void>;
  async emulateTimezone(timezoneId?: string): Promise<void>;
  async emulateVisionDeficiency(type?: string): Promise<void>;
  async emulateCPUThrottling(factor: number | null): Promise<void>;
  async emulateMediaFeatures(features?: MediaFeature[]): Promise<void>;
  async emulateMediaType(type?: string): Promise<void>;
  async setGeolocation(options: GeolocationOptions): Promise<void>;
  async setJavaScriptEnabled(enabled: boolean): Promise<void>;
  async emulateFocus(enabled: boolean): Promise<void>;
  async setTransparentBackgroundColor(): Promise<void>;
  async resetDefaultBackgroundColor(): Promise<void>;
}

Import:

import { EmulationManager, EmulatedState } from 'puppeteer-core/lib/cdp/EmulationManager.js';

I/O Contract

Inputs:

Parameter	Type	Required	Description
viewport	null	No	Device viewport settings (width, height, deviceScaleFactor, isMobile, hasTouch, isLandscape)
timezoneId	string	No	IANA timezone ID (e.g., "America/New_York")
visionDeficiency	string	No	One of: none, achromatopsia, blurredVision, deuteranopia, protanopia, reducedContrast, tritanopia
factor	null	No	CPU throttling factor (>= 1, or null to reset)
features	MediaFeature[]	No	CSS media feature overrides
geolocation	GeolocationOptions	No	Latitude (-90 to 90), longitude (-180 to 180), accuracy (>= 0)
enabled	boolean	No	JavaScript enabled state or focus emulation state

Outputs:

Output	Type	Description
emulateViewport return	boolean	Whether a page reload is needed (true if mobile or touch settings changed)
javascriptEnabled	boolean	The current JavaScript enabled state

Usage Examples

// Set viewport (via page API which delegates to EmulationManager)
await page.setViewport({
  width: 375,
  height: 812,
  isMobile: true,
  hasTouch: true,
  deviceScaleFactor: 3,
});

// Emulate timezone
await page.emulateTimezone('America/New_York');

// Emulate vision deficiency
await page.emulateVisionDeficiency('deuteranopia');

// Throttle CPU
await page.emulateCPUThrottling(4); // 4x slowdown

// Override geolocation
await page.setGeolocation({
  latitude: 51.507351,
  longitude: -0.127758,
  accuracy: 10,
});

// Emulate media features
await page.emulateMediaFeatures([
  { name: 'prefers-color-scheme', value: 'dark' },
  { name: 'prefers-reduced-motion', value: 'reduce' },
]);

// Set media type to print
await page.emulateMediaType('print');

// Disable JavaScript
await page.setJavaScriptEnabled(false);

// Emulate idle state
await page.emulateIdleState({
  isUserActive: false,
  isScreenUnlocked: false,
});

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime