Cross-Browser Automation

1 The Hook — Why This Matters

A Palmerston North SaaS company runs their Playwright suite on Chromium only. Tests pass 100% of the time in CI. The test lead is proud of that green dashboard.

A sales rep takes the product to a large enterprise customer and demos it on their corporate MacBook. The file upload component — built with a custom drag-and-drop implementation — does nothing. Completely broken in Safari. The drag events fire differently in WebKit. The engineering team later find the bug has been in production for six months.

The reasoning that led here: "our users are mostly on Chrome." The problem: the customer's IT policy mandates Safari for all web applications. Deal lost. The irony is that the fix was a six-line change to the event handler. The tests would have caught it in two minutes if anyone had run them on WebKit.

2 The Rule — The One-Sentence Version

Browser engines are not interchangeable. Chromium and Firefox share a lot of ground, but WebKit — the engine powering Safari on Mac and iOS — diverges meaningfully on drag-and-drop, clipboard, file inputs, CSS features, and media APIs. Any app that may be used in Safari needs WebKit coverage in the test suite.

3 The Analogy — Think Of It Like...

4 Watch Me Do It — Step by Step

Playwright's multi-browser support lives entirely in playwright.config.ts. One file, five project configs — desktop and mobile across all three engines.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,

  projects: [
    // Desktop browsers
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    // Mobile viewports
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 7'] },
    },
    {
      name: 'mobile-safari',
      use: { ...devices['iPhone 14'] },
    },
  ],
});

Running all five projects locally is slow. In CI you want a matrix that parallelises across runners so each browser gets its own job. This GitHub Actions workflow does that:

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        browser: [chromium, firefox, webkit]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps ${{ matrix.browser }}
      - run: npx playwright test --project=${{ matrix.browser }}
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report-${{ matrix.browser }}
          path: playwright-report/

The matrix gives you three parallel jobs instead of one sequential job. Total CI time stays close to a single-browser run while giving you three-browser coverage.

When Playwright WebKit emulation is not enough — for example, when you need to test on a real iPhone or verify macOS-specific font rendering — wire up BrowserStack. The integration is a one-line config change:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  // Point Playwright at BrowserStack's remote WebDriver grid
  use: {
    connectOptions: {
      wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${
        encodeURIComponent(JSON.stringify({
          browser: 'safari',
          browser_version: 'latest',
          os: 'OS X',
          os_version: 'Ventura',
          'browserstack.username': process.env.BS_USERNAME,
          'browserstack.accessKey': process.env.BS_ACCESS_KEY,
        }))
      }`,
    },
  },
});

BrowserStack is paid but invaluable for validating on real Safari/iOS before a major release. Use it for smoke tests on real devices, not as a substitute for your local Playwright WebKit coverage.

5 When to Use It — Decision Framework

The decision to run Chromium-only should be explicit and documented, not a default that nobody questioned. Add a comment to playwright.config.ts if you deliberately restrict browsers.

6 Common Mistakes — Don't Do This

7 Now You Try — Prompt Lab

Write your answer in the box below and the AI coach will review it.

8 Self-Check — Can You Actually Do This?

Click each question to reveal the answer.

9 ISTQB Mapping

10 Next Steps

Cross-browser coverage tells you features work. Now learn how to surface failures clearly to the people who need to act on them.