Browser & device configuration

Choosing a browser engine, viewport and device profile, what emulation does and does not prove, timeouts, and real Chrome mode.

Each test carries a config that decides where it runs: which browser engine, at what size, on what device, headed or headless, and how long a step may take.

Browser

Three engines, all real browsers:

`browser`	Engine
`chromium`	Chromium (the default)
`firefox`	Firefox
`webkit`	WebKit — the engine behind Safari

WebKit is the one worth running deliberately. It is the closest you get to Safari without a Mac, and it is where layout and date-parsing differences actually show up.

Viewport

A width and a height in CSS pixels. Three presets are built in:

Preset	Size
`desktop`	1280 × 720
`tablet`	768 × 1024
`mobile`	390 × 844

A test can also list several viewports and be run across all of them, which is how one test covers a responsive layout instead of three near-identical copies.

Changing a test's viewport invalidates its visual baselines — a screenshot is only comparable to a capture at the same size. See Visual regression.

Device emulation

Setting a device picks a Playwright device profile, which overrides the browser type and viewport together and adds the right user agent, scale factor and touch support. Seventeen profiles:

Phones — iPhone 15 Pro Max, iPhone 15 Pro, iPhone 15, iPhone 14, iPhone SE (3rd gen), Galaxy S24, Galaxy A55, Pixel 7, Pixel 5

Tablets — iPad Pro 11, iPad (gen 11), iPad Mini, Galaxy Tab S9

Desktop — Desktop Chrome, Desktop Safari, Desktop Firefox, Desktop Chrome HiDPI

A device profile is emulation, not a real device: it is a real browser engine with a phone's viewport, user agent and touch input. It catches responsive layout and touch-target problems. It does not catch iOS Safari's actual quirks, real device performance, or anything involving the platform itself — for that you need native mobile runs.

Because a device sets the browser type, device and browser do not combine: the device wins.

Headless

Headless is the default and is what you want almost always — it is faster and it is what CI runs. Headed mode is for watching a test to understand why it does something unexpected.

Timeout

The per-step timeout in milliseconds. It bounds how long a step waits for its element or navigation before failing.

Raising it globally to fix one slow step is the wrong lever: it makes every genuine failure take that much longer to report. Prefer an explicit wait for the thing you are actually waiting for.

Real Chrome mode

Ordinary Chromium is detectable — bot-detection and WAF layers can tell, and some apps behave differently or block the run outright. Real Chrome mode launches the system-installed Google Chrome instead, with a matching user agent.

Use it when a target actively fights automation. It requires Google Chrome installed on the machine running the test, so it is a local/self-hosted option rather than something that works on any runner. It also does not combine with device emulation — a device profile already dictates the browser and user agent.

Engine: Playwright or WebDriver

By default tests execute through the in-process Playwright driver. A test (or an environment) can instead select the WebDriver engine and run against a Selenium grid or standalone server. Native mobile uses Appium.

That is a bigger choice than a config flag — the capability matrix differs between engines. See Test engines.

Where config is resolved

Values are layered, later winning:

The test's own config.
The named environment the run targets — this is what lets one test run against staging and production without editing it.
Suite-level matrix cells, when a suite runs a device × browser matrix (see Suites & the run matrix).

Concurrency

Browsers are pooled and capped process-wide, so a large batch queues rather than launching fifty browsers and exhausting the machine. Batch concurrency is configurable per run within the plan's limit.