Implementation:Microsoft Playwright LaunchContext CLI

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

Overview

Concrete tool for selecting a browser engine and building a fully configured BrowserContext from CLI options, provided by the Playwright library.

Description

The LaunchContext CLI implementation provides two interlocking pieces:

1. commandWithOpenOptions() -- A factory function that attaches the full set of browser-selection and context-configuration flags to any CLI command. Every Playwright CLI command that opens a browser (open, codegen, screenshot, pdf, cr, ff, wk) is registered through this function, ensuring a consistent set of options.
2. launchContext() -- An async function that consumes the parsed CLI options, resolves the browser type, constructs LaunchOptions and BrowserContextOptions, launches the browser, creates a context, and returns a bundle containing the browser, context, both option objects, and a closeBrowser cleanup function.

The lookupBrowserType() helper maps option strings (cr, chromium, ff, firefox, wk, webkit) to the corresponding playwright.chromium, playwright.firefox, or playwright.webkit BrowserType instance. If a --device is specified, the device descriptor's defaultBrowserType takes precedence.

The function applies platform-specific adjustments (e.g., setting deviceScaleFactor to 2 on macOS in headful mode, removing hasTouch/isMobile for WebKit on Linux), layers user-specified overrides for viewport, geolocation, locale, timezone, color scheme, user agent, and proxy, and handles authentication state via --load-storage and --save-storage.

The returned closeBrowser callback handles graceful shutdown: saving storage state if --save-storage was specified, closing HAR recording if --save-har was active, and closing the browser. SIGINT is intercepted so the browser shuts down cleanly on Ctrl+C.

Usage

Use this implementation when:

• Building or extending a Playwright CLI command that needs to open a browser with full option support.
• Understanding how CLI flags are translated into Playwright API options.
• Debugging context configuration issues (viewport not matching, locale not applying, proxy not being used).
• Wrapping Playwright CLI commands in custom tooling.

Code Reference

Source Location

• Repository: playwright
• commandWithOpenOptions(): packages/playwright-core/src/cli/program.ts (lines 705-729)
• launchContext(): packages/playwright-core/src/cli/program.ts (lines 383-537)
• lookupBrowserType(): packages/playwright-core/src/cli/program.ts (lines 662-680)
• Options type: packages/playwright-core/src/cli/program.ts (lines 354-374)

Signature

// Factory that attaches open-browser options to a CLI command
function commandWithOpenOptions(
  command: string,
  description: string,
  options: any[][]
): Command;

// Launches a browser and returns a configured context bundle
async function launchContext(
  options: Options,
  extraOptions: LaunchOptions
): Promise<{
  browser: Browser;
  browserName: string;
  launchOptions: LaunchOptions;
  contextOptions: BrowserContextOptions;
  context: BrowserContext;
  closeBrowser: () => Promise<void>;
}>;

// Maps CLI name strings to BrowserType instances
function lookupBrowserType(options: Options): BrowserType;

// Options type consumed by launchContext
type Options = {
  browser: string;
  channel?: string;
  colorScheme?: string;
  device?: string;
  geolocation?: string;
  ignoreHttpsErrors?: boolean;
  lang?: string;
  loadStorage?: string;
  proxyServer?: string;
  proxyBypass?: string;
  blockServiceWorkers?: boolean;
  saveHar?: string;
  saveHarGlob?: string;
  saveStorage?: string;
  timeout: string;
  timezone?: string;
  viewportSize?: string;
  userAgent?: string;
  userDataDir?: string;
};

Import

# CLI usage -- options are attached automatically to commands like open, codegen, screenshot, pdf
npx playwright open --browser firefox --device "iPhone 11" https://example.com
npx playwright cr --viewport-size="1280,720" --lang en-GB https://example.com

I/O Contract

Inputs

Name	Type	Required	Description
--browser, -b	string	No (default: "chromium")	Browser engine to use: cr, chromium, ff, firefox, wk, webkit.
--channel	string	No	Chromium distribution channel: chrome, chrome-beta, msedge-dev, etc.
--device	string	No	Named device descriptor (e.g., "iPhone 11"). Overrides browser, viewport, user agent, and touch settings from the device catalog.
--viewport-size	string	No	Viewport dimensions as "width,height" (e.g., "1280,720").
--geolocation	string	No	Coordinates as "latitude,longitude" (e.g., "37.819722,-122.478611"). Automatically grants geolocation permission.
--color-scheme	string	No	Preferred color scheme: "light" or "dark".
--timezone	string	No	Timezone ID (e.g., "Europe/Rome").
--lang	string	No	Locale string (e.g., "en-GB").
--user-agent	string	No	Custom user agent string.
--proxy-server	string	No	Proxy server URL (e.g., "http://myproxy:3128" or "socks5://myproxy:8080").
--proxy-bypass	string	No	Comma-separated domains to bypass the proxy.
--user-data-dir	string	No	Path to a persistent user data directory. Uses launchPersistentContext() instead of ephemeral context.
--ignore-https-errors	boolean	No	Ignore HTTPS certificate errors.
--load-storage	string	No	Path to a JSON file containing cookies and localStorage to load into the context.
--save-storage	string	No	Path to save cookies and localStorage as JSON when the browser closes.
--save-har	string	No	Path to save a HAR file with all network activity. Blocks service workers.
--save-har-glob	string	No	Glob pattern to filter HAR entries by URL.
--block-service-workers	boolean	No	Block all service workers.
--timeout	string	No	Default timeout for Playwright actions in milliseconds. Default is no timeout (0).

Outputs

Name	Type	Description
browser	Browser	The launched browser instance.
browserName	string	Canonical browser name: "chromium", "firefox", or "webkit".
context	BrowserContext	A fully configured browser context with all CLI options applied.
contextOptions	BrowserContextOptions	The resolved context options object (useful for code generation and debugging).
launchOptions	LaunchOptions	The resolved launch options object (with headless, executablePath, and handleSIGINT removed for presentation).
closeBrowser	() => Promise<void>	Cleanup function that saves storage/HAR state and closes the browser.

Usage Examples

Basic Example

# Open an interactive Chromium browser
npx playwright open https://example.com

Device Emulation

# Open a page emulating an iPhone 11 in WebKit
npx playwright open --device "iPhone 11" https://example.com

Custom Viewport and Locale

# Open Firefox with a specific viewport and German locale
npx playwright open -b firefox --viewport-size="1920,1080" --lang de-DE https://example.com

Proxy and Geolocation

# Open Chromium through a proxy with a spoofed geolocation
npx playwright open --proxy-server="http://proxy:8080" --geolocation="48.8566,2.3522" https://example.com

Browser Shortcut Commands

# Shortcut: open directly in WebKit
npx playwright wk https://example.com

# Shortcut: open directly in Firefox
npx playwright ff https://example.com

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Select_Browser_and_Configure_Context

Requires Environment

• Environment:Microsoft_Playwright_Browser_Binaries_Environment
• Environment:Microsoft_Playwright_Platform_Support_Environment

Uses Heuristic

• Heuristic:Microsoft_Playwright_Browser_Specific_Workarounds