Principle:Microsoft Playwright Select Browser and Configure Context

Knowledge Sources	Playwright CLI Playwright Emulation
Domains	Browser_Automation, CLI
Last Updated	2026-02-11 00:00 GMT

Overview

Selecting a browser engine and configuring the automation context with device emulation, viewport, locale, and proxy settings before executing any browser commands.

Description

Before any browser automation task can execute, two fundamental decisions must be made:

1. Which browser engine to use -- The user selects from a set of supported engines (typically Chromium, Firefox, or WebKit). The selection determines which binary is launched, which protocol is spoken, and which rendering behavior applies.
2. How to configure the browser context -- A browser context is an isolated environment within a browser instance that holds its own cookies, local storage, cache, and settings. Configuring the context means specifying device emulation, viewport dimensions, geolocation, locale, timezone, color scheme, user agent, proxy, and authentication state.

This two-phase decision is a universal pattern in browser automation. Whether the user is taking a screenshot, generating a PDF, running a code generator, or opening an interactive session, the same selection-and-configuration step occurs first.

Key configuration dimensions:

• Device emulation -- Selecting a named device (e.g., "iPhone 11") applies a bundle of preset values: viewport width/height, device scale factor, user agent string, and whether touch events and mobile mode are active.
• Viewport size -- Explicitly setting the browser window dimensions, independent of or overriding a device preset.
• Geolocation -- Providing latitude and longitude coordinates and granting the geolocation permission.
• Locale and timezone -- Setting the browser locale (e.g., "en-GB") and timezone ID (e.g., "Europe/Rome") to test internationalization behavior.
• Color scheme -- Emulating the user's preferred color scheme ("light" or "dark") to test theme switching.
• Proxy -- Routing all browser traffic through a specified proxy server, with optional bypass rules.
• User agent -- Overriding the browser's default user agent string.
• HTTPS error handling -- Ignoring HTTPS certificate errors for testing against self-signed certificates.
• Persistent user data -- Using a specified user data directory instead of creating a fresh ephemeral context.

Usage

Apply this principle whenever:

• A CLI tool or test framework must present a uniform interface for choosing which browser to automate.
• A device emulation catalog must be mapped to concrete context settings.
• Multiple automation commands (open, screenshot, pdf, codegen) share the same set of configuration options.
• The same configuration logic must work across headful and headless modes, adjusting defaults (such as device scale factor) accordingly.

Theoretical Basis

The selection and configuration process can be expressed as a pipeline of transformations applied to a default configuration object:

FUNCTION configureBrowserContext(options):
  1. RESOLVE browser engine:
     IF options.device is set:
       engine = DEVICE_CATALOG[options.device].defaultBrowserType
     ELSE:
       engine = options.browser   // e.g., "chromium", "firefox", "webkit"

  2. INITIALIZE contextOptions from device descriptor (if any):
     contextOptions = COPY(DEVICE_CATALOG[options.device]) OR empty object

  3. APPLY platform-specific adjustments:
     IF mode is headful:
       contextOptions.deviceScaleFactor = host DPI factor
     IF engine is "webkit" AND platform is Linux:
       REMOVE hasTouch, isMobile (GTK scrolling workaround)
     IF engine is "firefox":
       REMOVE isMobile (unsupported)

  4. LAYER user-specified overrides:
     FOR EACH option in [viewport, geolocation, locale, timezone,
                         colorScheme, userAgent, proxy, storageState, ...]:
       IF option is provided:
         APPLY option to contextOptions

  5. LAUNCH browser:
     IF options.userDataDir:
       context = engine.launchPersistentContext(userDataDir, mergedOptions)
     ELSE:
       browser = engine.launch(launchOptions)
       context = browser.newContext(contextOptions)

  6. RETURN { browser, context, contextOptions, launchOptions, closeBrowser }

Design principles:

• Layered defaults -- Device descriptors provide sensible defaults. User-specified options override them. Platform-specific fixups are applied silently.
• Separation of launch and context options -- Launch options (proxy, channel, executable path) apply to the browser process. Context options (viewport, locale, geolocation) apply to the isolated context. Keeping them separate allows a single browser process to host multiple differently-configured contexts.
• Browser name aliasing -- Short names like "cr", "ff", "wk" are mapped to their canonical forms, providing ergonomic CLI usage without ambiguity.

Related Pages

Implemented By

• Implementation:Microsoft_Playwright_LaunchContext_CLI