Overview
The EmulationHandler module manages viewport dimensions, device emulation, timezone overrides, and geolocation spoofing through the Chrome DevTools Protocol Emulation domain.
Description
EmulationHandler is responsible for configuring the browser's rendering environment to simulate different devices, screen sizes, geographic locations, and time zones. It wraps four CDP Emulation commands -- setDeviceMetricsOverride, setTouchEmulationEnabled, setTimezoneOverride, and setGeolocationOverride -- behind a clean, validated API surface.
The handler listens for the createdSession event on the internal event bus. On session creation, it obtains the Emulation domain client and automatically reapplies any previously set viewport settings. This persistence across tab switches is achieved by storing the current viewport configuration in the module-level currentViewportSettings variable and reapplying it whenever a new CDP session is established.
The emulateDevice function provides a high-level device emulation capability by looking up a device model name from a built-in device catalog (sourced from lib/data/devices.js), applying its viewport settings, and setting its user agent string via the NetworkHandler.
Usage
Use EmulationHandler to test responsive layouts, simulate mobile devices, override the browser's geographic location for location-aware applications, or change the browser's timezone. These functions are exposed as top-level Taiko API methods (setViewport, emulateDevice, setLocation, setTimeZone) and are typically called during test setup before navigating to the target page.
Code Reference
Source Location
Signature
async function setViewport(options) -> void
async function setTimeZone(timezone) -> void
async function setLocation(options) -> void
async function emulateDevice(deviceModel) -> void
function resetViewportSettings() -> void
Import
const {
setLocation,
setViewport,
setTimeZone,
emulateDevice,
resetViewportSettings,
} = require("./handlers/emulationHandler");
I/O Contract
setViewport(options)
| Parameter |
Type |
Required |
Description
|
options.width |
number |
Yes |
Viewport width in pixels.
|
options.height |
number |
Yes |
Viewport height in pixels.
|
options.mobile |
boolean |
No |
Whether to emulate mobile viewport. Defaults to false.
|
options.deviceScaleFactor |
number |
No |
Device scale factor (DPR). Defaults to 1.
|
options.hasTouch |
boolean |
No |
Whether to enable touch emulation. Defaults to false.
|
options.isLandscape |
boolean |
No |
Whether to use landscape orientation. Defaults to portrait.
|
options.screenOrientation |
Object |
No |
Explicit screen orientation {angle, type}. Overrides isLandscape.
|
| Throws |
Condition
|
Error("No height and width provided") |
Either height or width is undefined.
|
setTimeZone(timezone)
| Parameter |
Type |
Description
|
timezone |
string |
IANA timezone identifier (e.g. "America/New_York", "Europe/London").
|
| Throws |
Condition
|
Error("Invalid timezone ID: ...") |
The provided timezone string is not recognized by the browser.
|
setLocation(options)
| Parameter |
Type |
Required |
Description
|
options.longitude |
number |
Yes |
Longitude in degrees. Must be between -180 and 180.
|
options.latitude |
number |
Yes |
Latitude in degrees. Must be between -90 and 90.
|
options.accuracy |
number |
No |
Accuracy in meters. Defaults to 0. Must be >= 0.
|
| Throws |
Condition
|
Error |
Longitude outside [-180, 180], latitude outside [-90, 90], or accuracy < 0.
|
emulateDevice(deviceModel)
| Parameter |
Type |
Description
|
deviceModel |
string |
Device name key from the built-in device catalog (e.g. "iPhone 6", "Nexus 5").
|
| Throws |
Condition
|
Error("Please set one of the given device models...") |
The provided device model name does not exist in the catalog. The error message lists all available device names.
|
Algorithm
The viewport persistence algorithm works as follows:
- When
setViewport is called, the options are stored in currentViewportSettings.
- When a new CDP session is created (new tab, navigation), the
createdSession event fires.
- The handler checks
currentViewportSettings; if non-null, it reapplies via applyViewportSettings.
applyViewportSettings issues two CDP calls in parallel: Emulation.setDeviceMetricsOverride and Emulation.setTouchEmulationEnabled.- The handler signals completion via the
handlerActingOnNewSession event promise, ensuring the session is fully configured before other operations proceed.
resetViewportSettings clears the stored settings, used during browser close to prevent stale state.
Screen orientation is derived from the isLandscape flag: landscape uses {angle: 90, type: "landscapePrimary"} and portrait uses {angle: 0, type: "portraitPrimary"}.
CDP Domain
This handler uses the Emulation domain with four commands:
Emulation.setDeviceMetricsOverride -- Sets viewport dimensions, device scale factor, mobile flag, and screen orientation.Emulation.setTouchEmulationEnabled -- Enables or disables touch event simulation.Emulation.setTimezoneOverride -- Overrides the browser's timezone to a specified IANA timezone ID.Emulation.setGeolocationOverride -- Overrides the browser's geolocation to specified latitude, longitude, and accuracy.
Usage Examples
// Set a custom viewport
const { setViewport } = require("./handlers/emulationHandler");
await setViewport({ width: 1280, height: 720 });
// Emulate a mobile device
const { emulateDevice } = require("./handlers/emulationHandler");
await emulateDevice("iPhone 6");
// Override timezone for testing
const { setTimeZone } = require("./handlers/emulationHandler");
await setTimeZone("Asia/Tokyo");
// Spoof geolocation
const { setLocation } = require("./handlers/emulationHandler");
await setLocation({ latitude: 48.8584, longitude: 2.2945, accuracy: 10 });
Related Pages
