Principle:Microsoft Playwright Configure Recording Context
| Knowledge Sources | |
|---|---|
| Domains | Testing, Code_Generation, Browser_Configuration |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Configuring the browser context for recording sessions ensures that tests are generated under realistic conditions, including device emulation, geolocation, viewport dimensions, and other environment-specific settings.
Description
Before any recording begins, the browser context must be properly configured to match the target testing environment. This configuration step is critical because the recorded test will implicitly depend on the context in which it was captured. A test recorded at a 1920x1080 viewport may behave differently from one recorded at a mobile viewport because responsive layouts change element positions, visibility, and available interactions.
Context configuration for recording encompasses several dimensions:
- Device emulation: Selecting a named device profile (e.g., "iPhone 13", "Pixel 5") automatically sets the viewport, user agent, device scale factor, and touch support to match that device.
- Viewport settings: Explicit width and height for the browser viewport, independent of device profiles.
- Geolocation: Latitude and longitude coordinates that the browser reports to web applications using the Geolocation API.
- Color scheme: Light or dark mode preference, affecting CSS media queries.
- Timezone: The timezone ID reported by the browser, affecting date/time rendering in applications.
- Language and locale: The Accept-Language header and navigator.language value.
- Proxy configuration: HTTP/SOCKS proxy settings for routing browser traffic.
- Storage state: Pre-loaded cookies and localStorage entries, enabling recording of authenticated sessions without re-logging in.
The principle of context configuration recognizes that a test's environment is as important as the test's actions. Two identical sequences of actions can produce different results in different contexts, so the context must be captured and reproduced alongside the actions themselves.
Usage
Apply this principle when:
- Testing responsive designs: Configure mobile, tablet, and desktop viewports to record tests for each breakpoint.
- Testing localized applications: Set language, locale, and timezone to match the target user population.
- Testing authenticated flows: Load saved storage state to bypass login screens and record post-authentication workflows.
- Testing location-aware features: Set geolocation coordinates to test maps, delivery estimation, or store locators.
- Testing accessibility preferences: Configure color scheme (dark/light) and reduced motion settings.
Always document the context configuration alongside the recorded test so that future test maintainers understand the environment assumptions.
Theoretical Basis
Context configuration follows a layered resolution model:
1. DEFAULTS
-> browser defaults (full viewport, no emulation)
2. DEVICE_PROFILE(device_name)
-> if specified, override defaults with device-specific settings:
viewport, userAgent, deviceScaleFactor, isMobile, hasTouch
3. EXPLICIT_OVERRIDES(options)
-> any explicitly provided option overrides both defaults and device profile:
viewport-size, geolocation, color-scheme, timezone, etc.
4. STORAGE_STATE(file_path)
-> load cookies and localStorage from a saved state file
-> enables recording in authenticated sessions
5. MERGE(defaults, device_profile, explicit_overrides, storage_state)
-> produce final contextOptions and launchOptions
-> pass to browser.newContext(contextOptions)
The layering ensures that:
- Device profiles provide convenient presets without requiring manual specification of every parameter.
- Explicit overrides always take precedence, giving the user full control.
- Storage state is orthogonal to other settings and can be combined with any configuration.
The resulting context options are also embedded in the generated test code, so that replaying the test recreates the same environment automatically.