Headless Safari Automation with Playwright

Introduction

In the wild world of cross-browser testing, ensuring your web app performs smoothly on Safari is essential. Safari commands a significant portion of the browser market share—around 18% globally (Statcounter Global Stats)—and dominates the Mac and iOS ecosystem. Bugs that surface exclusively in Safari can alienate a large segment of your users, making reliable testing on Safari a necessity.

Unfortunately, Apple’s Safari browser doesn’t natively support a headless mode (Apple Community Discussion). Running Safari without a graphical interface is challenging for CI pipelines or when scaling tests. Enter Playwright: a modern browser automation framework supporting all major browser engines, including WebKit (Safari’s underlying engine).

With Playwright’s cross-browser API (supporting Chromium, Firefox, and WebKit), headless automation is achievable for Safari. Playwright uses a custom WebKit build that runs on Windows, Linux, and macOS, effectively emulating Safari-like behavior across platforms. This capability allows automated headless Safari testing, enabling tests to run swiftly in CI or cloud environments.

Why Headless Safari Automation?

Automating Safari in headless mode is crucial for cross-browser end-to-end (E2E) testing in modern dev workflows. Here’s why developers typically lean on headless Safari:

Regression Testing: Ensures new features work across all browsers.
Responsive Design Validation: Tests layout compatibility on Safari (desktop and mobile emulation).
Web Scraping: Captures Safari-specific rendering for dynamic sites.
Efficient CI/CD Pipelines: Runs Safari in headless mode in Linux containers, catching browser-specific bugs early.

This guide will walk through setting up Playwright for headless Safari automation, from configurations to advanced parallel test execution. Along the way, we’ll showcase how BrowserCat simplifies scaling Safari tests for developers aiming for streamlined workflows.

Getting Started: Playwright & Safari Automation

Playwright’s setup ensures everything needed for Safari automation is included. Let’s dive into the prerequisites and initial setup.

1. Setting Up Playwright (Installation)

Install Playwright as part of your project. For this guide, we’ll use the Node.js version:

# Install Playwright testing library
npm install -D @playwright/test

# Download browser binaries (Chromium, Firefox, WebKit)
npx playwright install --with-deps

This ensures all Playwright-supported engines, including WebKit, are ready to automate Safari-like instances.

If you’re using Python or another language, the commands are similar (e.g., pip install playwright).

Tip: Use npx playwright install webkit if you only need the WebKit browser.

2. WebKit vs. Real Safari

Playwright uses a patched WebKit engine representing the core of Safari, rather than driving your locally installed Safari browser. This WebKit build is kept updated by Playwright and closely mimics Safari, even matching user agent strings and default configurations (like Desktop Safari or Mobile Safari).

While it’s not the “real Safari,” for most web apps and tests, Playwright’s WebKit reproduction is sufficient to detect Safari-specific issues—especially when Safari’s native headless mode isn’t available.

3. Platform Support

Playwright’s WebKit is cross-platform, meaning you can test Safari-like behavior on Windows or Linux without a Mac. While media-related tests (e.g., video playback) might require macOS for codec compatibility, most DOM and CSS validation works across all platforms.

Run this quick WebKit test to ensure everything is set up correctly:

npx playwright wk https://example.com

You’ll see Playwright’s MiniBrowser appear, confirming WebKit is installed and functional.

4. Browser Configurations for Safari

To automate Safari, add configuration presets in your Playwright script or test runner settings. Here’s an example playwright.config.js for Safari:

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

export default defineConfig({
  projects: [
    {
      name: 'Safari',
      use: {
        browserName: 'webkit',
        ...devices['Desktop Safari'],
      },
    },
  ],
});

Browser: The webkit engine emulates Safari.
Device Defaults: Includes viewport, user agent, etc. (e.g., Desktop Safari or iPhone 12).
Headless Mode: Default is headless: true. Set to false to debug.

Run the test suite using npx playwright test. You’re now ready to automate Safari tasks.

Implementing Headless Safari Automation

Here, we’ll walk through building and running a simple Playwright script to automate Safari (via WebKit) in headless mode.

Example Scenario: Navigating Pages and Capturing Screenshots

In this example, we’ll navigate to BrowserCat’s homepage, click the “Pricing” link, verify the page title, and capture a screenshot.

Script Breakdown

Launch WebKit browser in headless mode.
Create a browser context for isolated browsing.
Navigate to the URL and perform interactions.
Capture results like titles and screenshots.
Close the browser to free system resources.

Playwright Code Implementation

const playwright = require('playwright'); // Import Playwright

(async () => {
  // 1. Launch WebKit (Safari) browser in headless mode
  const browser = await playwright.webkit.launch({ headless: true });

  // 2. Create a new browser context (isolated session)
  const context = await browser.newContext();

  // 3. Open a new page in the context
  const page = await context.newPage();

  // 4. Go to BrowserCat homepage
  await page.goto('https://www.browsercat.com');

  // 5. Interact with the page
  await page.click('a:has-text("Pricing")'); // Click "Pricing" link
  await page.waitForLoadState('networkidle'); // Wait for navigation to complete

  // 6. Verify navigation and take a screenshot
  const title = await page.title();
  console.log(`New page title: ${title}`);
  await page.screenshot({ path: 'pricing-page.png', fullPage: true });

  // 7. Close browser
  await browser.close();
})();

Run this script (node script.js) to automate Safari tasks completely headless.

Debugging Made Easy

Playwright supports debugging in both headless and headed modes:

Headed Mode: Set { headless: false } to see browser actions in real-time.
Playwright Inspector: Insert await page.pause() to step through actions via an interactive UI.

Console & Logs: Capture logs via:

page.on('console', msg => console.log(`PAGE LOG: ${msg.text()}`));

These debugging features are invaluable for writing reliable tests.

Scaling with Parallel Execution

For efficiency, Playwright supports running browsers in parallel. This is especially useful for speeding up test suites or tasks like web scraping.

Parallel Example: Launching Multiple Safari Contexts

const browser = await playwright.webkit.launch({ headless: true });

// Launch isolated contexts for parallel tasks
const contextA = await browser.newContext();
const contextB = await browser.newContext();

const pageA = await contextA.newPage();
const pageB = await contextB.newPage();

await Promise.all([
  pageA.goto('https://example1.com'),
  pageB.goto('https://example2.com'),
]);

console.log('Titles:', await pageA.title(), await pageB.title());

await browser.close();

This setup minimizes load times by sharing one WebKit instance across contexts. Playwright’s robust API smoothly handles concurrency.

BrowserCat’s Edge in Safari Testing

BrowserCat provides cloud-hosted Playwright instances, enabling on-demand, scalable Safari automation. Highlights include:

Instant Parallel Testing: Run hundreds of Safari instances with zero infrastructure overhead.

Turnkey Integrations: Replace your local webkit.launch() with:

const browser = await playwright.webkit.connect('wss://api.browsercat.com/connect', {
  headers: { 'Api-Key': '<YOUR_API_KEY>' },
});

Managed Updates: BrowserCat keeps WebKit and Playwright up-to-date on its servers.
Custom Configurations: Leverage region-specific IPs, network interceptions, and enhanced debugging.

Try BrowserCat: Get started for free and see how it reduces complexity in scaling browser tests.

Conclusion

Although Safari lacks a native headless mode, Playwright’s WebKit integration and tools like BrowserCat make headless Safari automation both achievable and scalable. Whether you’re debugging UI quirks, testing responsiveness, or ensuring bug-free deployments, this workflow helps future-proof your apps for Safari users.

Ready to master browser testing? Take Playwright and BrowserCat for a spin and tame Safari automation once and for all 🐾.
Happy Testing!

Mastering Headless Safari Automation with Playwright