Playwright Projects and Branded Browsers
On this page
Playwright approaches cross-browser testing differently from Selenium. Instead of talking to each vendor's driver, it ships its own builds of three engines, Chromium, Firefox and WebKit, and drives them all through one protocol. That makes the first step very easy: three engines on your laptop with one command. It also means you need to know exactly what those builds are, and when to switch to real branded browsers.
Engines, channels and devices#
Three settings in a Playwright project decide which browser runs:
-
browserName: the engine,chromium,firefoxorwebkit. Thedevicespresets set it for you:Desktop Chromeis Chromium,Desktop Firefoxis Firefox,Desktop Safariis WebKit. -
channel: for Chromium only, a branded browser instead of Playwright's own build:chrome,chrome-beta,msedge,msedge-betaand so on. These are the real Google Chrome and Microsoft Edge, installed on the machine (npx playwright install chromeinstalls Chrome if it is missing). -
Device presets such as
iPhone 15orPixel 7: a viewport, device scale factor, user agent and touch support on top of an engine.iPhone 15is WebKit pretending to be a phone, not a phone.
Here is the local config from the course project, with all three engines, branded Chrome and an emulated iPhone:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
use: { trace: 'on-first-retry' },
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
{ name: 'google-chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' } },
{ name: 'mobile-safari', use: { ...devices['iPhone 15'] } },
],
});
$ npx playwright test
Running 15 tests using 5 workers
15 passed (8.2s)
The three tests from chapter 3 times five projects, in eight seconds. For a fast feedback loop during development, this is hard to beat. Run one project with --project=webkit while you fix something WebKit-specific.
Your mobile-safari project (the iPhone 15 preset) passes. What has that proven?
Device presets are emulation on top of an engine on your machine. They catch most responsive layout problems, but not iOS Safari's own behaviour (its toolbars, keyboard, viewport resizing and gesture handling). Chapter 6 runs on real devices for that.
What the bundled engines are, and are not#
Playwright's Firefox and WebKit are builds that the Playwright team patches so they can be automated. They track the upstream projects closely, but they are not the Firefox or Safari your users install, and on Windows or Linux the WebKit build renders with that OS's fonts and form controls. Chromium is the open-source base of Chrome, without some of Chrome's proprietary parts, such as certain media codecs.
So the local run answers "does it work in each engine?" It does not answer "does it work in Edge on Windows" or "in Safari on a Mac". For those you need the real browser on the real operating system. If you develop on a Mac, branded Edge on Windows is out of reach locally; if you develop on Windows or Linux, macOS is.
One more limit: Playwright cannot drive Apple's Safari application at all. Safari is automated through safaridriver, which speaks WebDriver. Playwright's webkit on a Mac is the closest Playwright gets; for real Safari, use Selenium as in chapter 4.
The same projects on a remote grid#
Playwright can connect to a browser running elsewhere instead of launching one. When a project sets connectOptions.wsEndpoint, each worker connects to that URL, and everything else (locators, assertions, traces, the HTML report) works as before.
On TestingBot the endpoint is wss://cloud.testingbot.com/playwright, with the browser described in a capabilities query parameter. A small helper keeps it readable. Put this in testingbot.ts:
type GridBrowser = {
browserName: 'chrome' | 'edge' | 'firefox' | 'safari';
browserVersion?: string;
platform: string;
};
export function testingbotEndpoint(browser: GridBrowser): string {
const capabilities = {
browserVersion: 'latest',
...browser,
'tb:options': {
key: process.env.TB_KEY,
secret: process.env.TB_SECRET,
build: process.env.TB_BUILD ?? 'local',
},
};
return `wss://cloud.testingbot.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`;
}
And a second config, playwright.testingbot.config.ts, with one project per remote browser:
import { defineConfig } from '@playwright/test';
import { testingbotEndpoint } from './testingbot';
export default defineConfig({
testDir: './tests',
workers: 2,
projects: [
{
name: 'chrome-win11',
use: {
browserName: 'chromium',
connectOptions: { wsEndpoint: testingbotEndpoint({ browserName: 'chrome', platform: 'WIN11' }) },
},
},
{
name: 'edge-win11',
use: {
browserName: 'chromium',
connectOptions: { wsEndpoint: testingbotEndpoint({ browserName: 'edge', platform: 'WIN11' }) },
},
},
{
name: 'firefox-win11',
use: {
browserName: 'firefox',
connectOptions: { wsEndpoint: testingbotEndpoint({ browserName: 'firefox', platform: 'WIN11' }) },
},
},
{
name: 'safari-tahoe',
use: {
browserName: 'webkit',
connectOptions: { wsEndpoint: testingbotEndpoint({ browserName: 'safari', platform: 'TAHOE' }) },
},
},
],
});
The important detail is the pairing. The project's browserName is the Playwright engine on your side of the connection; the grid's browserName is what runs remotely. They must match: chrome and edge connect with chromium, firefox with firefox, and safari with webkit. On the grid, safari means the WebKit build that matches your Playwright version, running on a real Mac with macOS fonts and form controls. The Playwright browser list has the versions and platforms, and the capabilities generator builds the object for you.
Reporting results#
As with Selenium, the grid cannot see your assertions. Playwright sessions report through a special page.evaluate call. An automatic fixture in tests/fixtures.ts does it for every test, and does nothing for local projects:
import { test as base } from '@playwright/test';
function executor(action: string, args: Record<string, unknown>): string {
return `testingbot_executor: ${JSON.stringify({ action, arguments: args })}`;
}
export const test = base.extend<{ testingbotStatus: void }>({
testingbotStatus: [async ({ page }, use, testInfo) => {
const remote = !!testInfo.project.use.connectOptions;
if (remote) {
await page.evaluate(() => {}, executor('setSessionName', { name: testInfo.title }));
}
await use();
if (remote) {
await page.evaluate(() => {}, executor('setSessionStatus', {
passed: testInfo.status === testInfo.expectedStatus,
reason: testInfo.error?.message?.slice(0, 200) ?? '',
}));
}
}, { auto: true }],
});
export { expect } from '@playwright/test';
The test files import test and expect from ./fixtures instead of @playwright/test. The Playwright Test guide documents both actions.
Run it, one session at a time while you set it up:
export TB_KEY=your-key TB_SECRET=your-secret TB_BUILD=cross-browser-ch5
npx playwright test -c playwright.testingbot.config.ts --workers=1
Running 12 tests using 1 worker
[1/12] [chrome-win11] › tests/forms.spec.ts:3:1 › fills a native date input
...
[12/12] [safari-tahoe] › tests/todo.spec.ts:17:1 › edits a todo with select-all
12 passed (1.6m)
Chrome 156, Edge 156 and Firefox 158 on Windows 11 and WebKit on macOS Tahoe, from one config file.
A project connects to the grid with browserName: 'edge' in the capabilities and browserName: 'firefox' in the project's use. What happens?
The project's browserName picks the protocol client in your test process, and the capabilities pick the remote browser. Edge needs the chromium client; a mismatch cannot connect.
One session per worker, not per test#
With a remote browser, each Playwright worker opens one session per project and reuses that browser for every test it runs, with a fresh context per test. With one worker, the twelve tests above were four sessions on TestingBot, one per project, each named after the last test that ran in it. That is efficient, and isolation between tests is unchanged, but it means the number of sessions follows your worker count. Chapter 7 uses that to control parallelism.
Summary#
-
browserNamepicks the engine,channelpicks branded Chrome or Edge, and device presets add a phone-sized viewport on top of an engine. - Playwright's Firefox and WebKit are patched builds; real Safari cannot be driven by Playwright at all.
- Remote projects connect with
connectOptions.wsEndpoint; the local engine must match the remote browser. - Report status with the
testingbot_executorcall; sessions follow workers, not tests.