Allscreenshots
Sign inGet an API key
Blog

Guide

Playwright Cross-Browser Testing: Config + CI Examples

Alex ChenUpdated 11 min read

Run the same tests in Chromium, Firefox and WebKit by defining a Playwright project for each engine. Start with this working example, then choose a smaller test matrix for your application.

Quickstart: run a complete cross-browser example

Download the example ZIP, extract it, and open the playwright-cross-browser-example directory. The source repository includes the fixture, tests, lockfile and CI workflow.

bash
npm ci npx playwright install --with-deps npm test # Debug one engine or inspect the HTML report: npm test -- --project=webkit npx playwright show-report

No API key is needed. The test runner starts a local server for a responsive page with a form and a marker below the fold.

Working playwright.config.ts

typescript
import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: [['list'], ['html', { open: 'never' }], ['json', { outputFile: 'results.json' }]], use: { baseURL: 'http://127.0.0.1:4199', trace: 'retain-on-failure' }, webServer: { command: 'npm run serve', url: 'http://127.0.0.1:4199', reuseExistingServer: !process.env.CI, }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, { name: 'webkit', use: { ...devices['Desktop Safari'] } }, { name: 'mobile-chromium', use: { ...devices['Pixel 7'] } }, { name: 'mobile-webkit', use: { ...devices['iPhone 13'] } }, ], });

The config uses three desktop engines and two mobile profiles. webServer starts the example automatically; for your own app, change its command and baseURL together. The pinned Playwright version and lockfile keep the browser tooling reproducible.

A test with user-visible assertions

typescript
import { test, expect } from '@playwright/test'; test('valid form submission and responsive layout', async ({ page }) => { await page.goto('/'); await expect(page.getByRole('heading', { name: 'Website screenshots across browsers' })).toBeVisible(); await page.getByLabel('Email', { exact: true }).fill('[email protected]'); await page.getByRole('button', { name: 'Continue' }).click(); await expect(page.getByRole('status')).toHaveText('Ready to continue'); expect(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true); });

The second test in the repository verifies native required-field validation and captures a full-page PNG after checking the end marker. Keep different engines' visual baselines separate.

Evidence from an actual run

On October 8, 2026, Node 24.8.0 and Playwright 1.64.0 on macOS arm64 ran 10 tests: 10 passed, 0 failed, 0 skipped, in 17.8 seconds. Both tests passed in all five projects. Download the recorded results.

ProjectTests passedWhat it covers
Chromium2 / 2Desktop Chromium engine
Firefox2 / 2Playwright's patched Firefox
WebKit2 / 2Desktop WebKit build
Mobile Chromium2 / 2Pixel 7 device profile
Mobile WebKit2 / 2iPhone 13 device profile

Full-page WebKit output showing the form, two-column layout and end-of-capture marker
Full-page WebKit output showing the form, two-column layout and end-of-capture marker

Reading the capture: the form near the top tests native validation; the two cards expose layout overflow; the END OF CAPTURE marker verifies the image extends below the viewport. Chromium output, Firefox output, and mobile WebKit output are available for comparison.

These results validate this fixture on one machine. Mobile profiles are emulation, and Playwright WebKit is not the Safari application or a real iPhone. They do not prove your production checkout works.

GitHub Actions for this example

Use the included workflow when placing the example at the root of its own repository:

yaml
name: Cross-browser tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 cache: npm - run: npm ci - run: npx playwright install --with-deps - run: npm test - uses: actions/upload-artifact@v4 if: ${{ !cancelled() }} with: name: playwright-report path: playwright-report/ retention-days: 14

The public example repository runs this workflow directly. The local result above is measured; the matching five-project suite also passed in the website’s CI on October 8, 2026. New runs are available in the public example’s GitHub Actions.

Plan the coverage for your app

Playwright provides browser projects and CI installation guidance. Once the configuration runs, choose which user journeys need every engine and which can run only in Chromium.

What Cross-Browser Testing Should Prove

Start by deciding what risk you are trying to reduce. A good cross-browser suite usually answers these questions:

  • Can users sign up, log in, search, buy, save, export, or complete the core workflow?
  • Does the app render usable layouts in Chromium, Firefox, and WebKit?
  • Do mobile navigation, dialogs, sticky headers, and forms work at phone-sized viewports?
  • Do browser APIs such as downloads, clipboard access, file uploads, media playback, or date inputs behave as expected?
  • Do important pages still look sane after CSS, dependency, or design system changes?

It should not try to duplicate every unit test in every browser. That creates more runtime than signal. Use Playwright for browser behavior and real user flows. Keep business logic, pure functions, and edge-case permutations in cheaper test layers.

Browser Engines Playwright Can Cover

Playwright's core browser projects map to three engines:

ProjectEngineUseful coverage
ChromiumBlink/V8Chrome, Edge, many desktop users, most Android browser behavior
FirefoxGecko/SpiderMonkeyFirefox-specific layout, event, storage, and media behavior
WebKitWebKit/JavaScriptCoreSafari-like rendering, iOS-style issues, WebKit-specific layout behavior

Playwright can also run against branded Google Chrome and Microsoft Edge through browser channels, and it can emulate selected desktop, tablet, and mobile device profiles.

There are two important caveats:

  • Playwright's WebKit is not the branded Safari app. It is a WebKit build that gives strong Safari-like coverage, but the closest Safari signal still comes from running WebKit on macOS when platform-specific behavior matters.
  • Playwright's Firefox support uses its own patched Firefox build. Do not assume it is the same as launching a user's installed Firefox binary.

Those caveats do not make the coverage weak. They just mean you should treat Playwright as a practical automation layer, not as a perfect substitute for every physical device and browser combination.

Configure a Browser Matrix

Most teams should start with one Playwright config that defines browser projects. The project names become the handles you use locally and in CI.

typescript
import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests/e2e', timeout: 30_000, expect: { timeout: 5_000 }, use: { baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3000', trace: 'on-first-retry', screenshot: 'only-on-failure', video: 'retain-on-failure' }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, { name: 'webkit', use: { ...devices['Desktop Safari'] } }, { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } }, { name: 'mobile-safari', use: { ...devices['iPhone 12'] } } ] });

Run everything:

bash
npx playwright test

Run one browser project:

bash
npx playwright test --project=webkit

Run one test file in one browser:

bash
npx playwright test tests/e2e/checkout.spec.ts --project=firefox

That last command is the one developers use most often when debugging a browser-specific failure.

Choose the Right Test Matrix

Running every test in every browser sounds thorough, but it usually becomes expensive quickly. A better matrix separates critical coverage from broad coverage.

SuiteBrowser coverageWhen to run
Smoke flowsChromium, Firefox, WebKit, mobile Chrome, mobile SafariEvery pull request
Full functional suiteChromiumEvery pull request
High-risk browser suiteFirefox and WebKitPull requests touching CSS, browser APIs, auth, checkout, uploads, downloads, or navigation
Full matrixAll configured projectsNightly, before releases, or on demand

You can express this by splitting tests into folders:

text
tests/ e2e/ smoke/ login.spec.ts checkout.spec.ts dashboard.spec.ts full/ billing-settings.spec.ts team-management.spec.ts exports.spec.ts

Then run the smoke folder across every project and the full suite in Chromium:

bash
npx playwright test tests/e2e/smoke npx playwright test tests/e2e/full --project=chromium

This gives you browser breadth where it matters most and keeps routine CI practical.

Write Tests That Survive Browser Differences

Cross-browser tests are less forgiving than single-browser tests. Small assumptions that pass in Chromium can fail in Firefox or WebKit.

Prefer user-facing locators

Role, label, placeholder, and text locators are usually more resilient than CSS selectors.

typescript
import { test, expect } from '@playwright/test'; test('visitor can request a product demo', async ({ page }) => { await page.goto('/pricing'); await page.getByRole('link', { name: /book a demo/i }).click(); await expect(page.getByRole('heading', { name: /schedule a demo/i })).toBeVisible(); });

CSS selectors often depend on implementation details that vary after refactors:

typescript
// Fragile await page.locator('.pricing-card:nth-child(2) .button.primary').click(); // Better await page.getByRole('link', { name: /start pro trial/i }).click();

Avoid timing assumptions

Hard waits hide real readiness problems and behave differently across engines and CI machines.

typescript
// Avoid await page.waitForTimeout(2000); // Prefer a user-visible signal await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible(); await expect(page.getByText('Project created')).toBeVisible();

Be careful with hover-only interactions

Hover behavior differs across desktop and touch-style projects. If a menu is essential on mobile, the product should expose a touch-friendly path. Your test should reflect the real control for that viewport.

typescript
test('navigation opens product links', async ({ page }) => { await page.goto('/'); const viewport = page.viewportSize(); const isMobileViewport = viewport ? viewport.width < 768 : false; if (isMobileViewport) { await page.getByRole('button', { name: /open navigation/i }).click(); } else { await page.getByRole('button', { name: /products/i }).hover(); } await expect(page.getByRole('link', { name: /integrations/i })).toBeVisible(); });

Expect rendering differences

Fonts, antialiasing, form controls, scrollbars, focus rings, and media codecs can differ between engines and operating systems. Functional tests should assert user outcomes, not exact CSS internals.

For visual checks, compare screenshots inside a stable environment and keep browser-specific baselines separate. A WebKit screenshot should not usually be compared against a Chromium baseline.

Use Project-Specific Settings

Some browser projects need different settings. For example, you may want a stricter reduced-motion environment for visual tests, or a branded Chrome channel for codec-heavy workflows.

typescript
import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'chrome-stable', use: { ...devices['Desktop Chrome'], channel: 'chrome' } }, { name: 'webkit-reduced-motion', use: { ...devices['Desktop Safari'], reducedMotion: 'reduce' } } ] });

Use branded Chrome or Edge when you specifically need the installed browser channel, media codecs, enterprise browser policy behavior, or parity with a customer support environment. For normal regression testing, the bundled browser projects are simpler and more reproducible.

Run Cross-Browser Tests in CI

For CI, install the Playwright browsers and operating system dependencies before running the suite.

yaml
name: Playwright cross-browser tests on: pull_request: push: branches: [main] jobs: smoke: runs-on: ubuntu-latest timeout-minutes: 30 steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v6 with: node-version: lts/* - run: npm ci - run: npx playwright install --with-deps - run: npx playwright test tests/e2e/smoke - uses: actions/upload-artifact@v5 if: failure() with: name: playwright-report path: playwright-report/ retention-days: 30 chromium-full: runs-on: ubuntu-latest timeout-minutes: 30 steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v6 with: node-version: lts/* - run: npm ci - run: npx playwright install --with-deps chromium - run: npx playwright test tests/e2e/full --project=chromium - uses: actions/upload-artifact@v5 if: failure() with: name: playwright-report-chromium-full path: playwright-report/ retention-days: 30

If the suite grows, split it with sharding:

bash
npx playwright test --shard=1/4 npx playwright test --shard=2/4 npx playwright test --shard=3/4 npx playwright test --shard=4/4

For a large matrix, run each project as a separate job. That makes failures easier to read and lets CI parallelize the slowest work.

yaml
strategy: fail-fast: false matrix: project: [chromium, firefox, webkit, mobile-chrome, mobile-safari] steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v6 with: node-version: lts/* - run: npm ci - run: npx playwright install --with-deps - run: npx playwright test tests/e2e/smoke --project=${{ matrix.project }}

Debug Browser-Specific Failures

When a test fails in only one browser, resist the urge to guess. Capture the browser's view of the page.

Start with the failing project:

bash
npx playwright test tests/e2e/checkout.spec.ts --project=webkit --headed

Then use traces:

bash
npx playwright show-trace trace.zip

A trace helps you inspect:

  • DOM snapshots before and after each action
  • Console errors
  • Network requests
  • Screenshots
  • The exact locator Playwright tried to resolve
  • Timing around navigations and assertions

Useful failure patterns include:

SymptomCommon cause
Works in Chromium, fails in WebKitSafari/WebKit layout difference, unsupported API, focus behavior, date input, sticky positioning
Works locally, fails in CIMissing OS dependency, font difference, slower hardware, hidden race condition
Works on desktop, fails on mobile projectDifferent navigation pattern, covered button, viewport-specific layout, touch target issue
Fails only in FirefoxCSS support difference, event handling difference, storage or download behavior

When a test exposes a real browser bug in your app, keep the regression test. Narrow it to the behavior that failed so the next person understands why it exists.

Add Screenshots Where They Help

Playwright can capture screenshots during tests:

typescript
await page.screenshot({ path: 'artifacts/pricing-webkit.png', fullPage: true });

Screenshots are useful for debugging and for visual checks around high-value pages. But screenshot-heavy workflows become expensive when every browser, route, state, and viewport runs inside the same end-to-end suite.

A practical split is:

  • Use Playwright to prove that flows work across browsers.
  • Use screenshots on failure so developers can debug quickly.
  • Use a dedicated screenshot workflow for broad page coverage, production monitoring, documentation snapshots, and visual baselines.

For broad visual coverage, pair Playwright with Allscreenshots screenshot automation:

typescript
const response = await fetch('https://api.allscreenshots.com/v1/screenshots', { method: 'POST', headers: { 'X-API-Key': process.env.SCREENSHOT_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://example.com/pricing', fullPage: true, viewport: { width: 1440, height: 900 }, format: 'png' }) }); if (!response.ok) { throw new Error(`Screenshot failed: ${response.status}`); }

That keeps the Playwright suite focused on behavior while screenshot automation handles repeatable capture, visual regression testing, and scheduled page monitoring.

A Practical Rollout Plan

If you are adding cross-browser testing to an existing app, do it in stages:

  1. Add Playwright with Chromium only.
  2. Write three to five smoke tests for critical workflows.
  3. Add Firefox and WebKit projects for those smoke tests.
  4. Add mobile Chrome and mobile Safari projects for responsive workflows.
  5. Capture traces, screenshots, and videos on retry or failure.
  6. Move the full suite to Chromium and keep the broad matrix focused.
  7. Add nightly or release-gated full-matrix runs if the app needs it.

This sequence gives you useful coverage early and avoids making browser testing feel like a tax on every change.

Conclusion

Playwright makes cross-browser testing approachable, but the value comes from the matrix you choose. Run your most important flows across Chromium, Firefox, WebKit, and mobile projects. Keep the full suite concentrated where it gives the best signal. Use traces to debug browser-only failures, and use screenshot automation when the job is broad visual coverage rather than interaction testing.

Done well, cross-browser testing becomes a focused release safety net instead of an expensive checklist.

Find out how easy it is to capture and share pixel-perfect screenshots at scale using Allscreenshots. Sign up for a free account and start integrating your first screenshot API call today.

Start with one request

Free plan: 100 screenshots. No credit card.

Get an API key
  • Full-page captures
  • Popups and repeated sticky bars removed
  • Markdown, JSON and PDF output
  • Crawl a site from one URL
  • Desktop, tablet and phone in one image
  • Works in n8n, Make and Zapier
  • MCP server for AI assistants