Running Selenium tests on Safari sounds straightforward until you try to do it on real infrastructure. Chrome and Firefox are easy to containerize, parallelize, and wire into CI. Safari is different. It is tied to macOS, it uses Apple’s WebDriver support, and it brings platform-specific constraints that can surprise teams that are used to Linux-based test farms.

If your product needs to support Safari users, you need more than a checkbox in a test matrix. You need a reliable way to run real Safari sessions, understand what macOS allows and blocks, and decide whether to maintain your own Mac infrastructure or use a platform that already runs on real macOS machines. For many teams, a service like Endtest is the simpler route because it runs tests on real macOS machines with real Safari, without requiring your team to operate Mac hardware, manage browser versions, or keep flaky local farms alive.

This tutorial walks through how Selenium Safari testing actually works, how to configure it correctly, what macOS constraints matter, and where teams usually get stuck.

Why Safari is different from Chrome and Firefox

Safari is not just another browser in your Selenium grid. The important difference is the operating system requirement. Safari WebDriver is supported by Apple on macOS, and Safari automation depends on Apple’s implementation rather than a general-purpose Linux container. Apple’s docs for testing with WebDriver in Safari describe the browser-side setup, and Selenium’s own documentation covers the broader WebDriver model at selenium.dev.

That means three practical things:

  1. You need macOS to run real Safari.
  2. You need to enable Safari’s remote automation support.
  3. You need to account for differences in Safari behavior, rendering, and WebDriver feature support.

If your current test infrastructure assumes Docker, headless Linux, or ephemeral browser containers, Safari will break that mental model quickly.

Safari testing is less about writing a special test and more about accepting a different execution environment.

What “real Safari” actually means

People often say “Safari testing” when they mean one of three things:

  • Real Safari on macOS
  • Safari Technology Preview
  • A WebKit-based approximation running somewhere else

For Selenium test coverage, those are not interchangeable.

Real Safari on macOS is what end users actually run. Safari Technology Preview is useful for early validation, but it is not a substitute for release-browser testing. And WebKit-based approximations are not Safari. They may help catch some layout or scripting issues, but they do not give you the same browser engine, browser policies, or platform interactions.

If your goal is to verify login flows, file uploads, JavaScript behavior, cookie handling, or responsive issues in the browser your customers use, you want actual Safari on actual macOS hardware.

This is also why some teams move away from maintaining their own Mac mini farm and use a service that already handles the browser and OS layer. Endtest’s model is attractive here because it runs on real browsers on Windows and macOS machines, including real Safari, rather than approximations or Linux containers.

The basic prerequisites for Selenium on Safari

Before you run a single test, the machine must be prepared correctly.

1. Use a Mac with a supported version of Safari

Your test host must be macOS, and Safari should be installed through the normal OS update path. In practice, that means you need to track both macOS and Safari versions as part of your test environment. Upgrading Safari can change behavior, and upgrading macOS can change permissions or available automation features.

2. Enable Remote Automation in Safari

Safari’s automation support is not enabled by default. On the target Mac, you need to open Safari, go to the Develop menu, and enable remote automation. If the Develop menu is not visible, Safari’s developer features usually need to be enabled first.

Once enabled, Selenium can control the browser via WebDriver.

3. Use the Safari driver that ships with Safari

Unlike some browser automation setups where you separately manage a browser driver binary, Safari uses the built-in safaridriver provided by Apple. You generally do not download a third-party driver for Safari in the same way you might manage chromedriver.

4. Understand security and permissions

macOS automation can be blocked by privacy settings, accessibility permissions, or OS-level restrictions. On managed corporate Macs, security tooling may also interfere with browser automation or keyboard and mouse simulation.

A minimal Selenium example for Safari

The simplest test is a sanity check that verifies your automation can launch Safari, open a page, and inspect the title.

from selenium import webdriver
from selenium.webdriver.safari.options import Options

options = Options() options.set_capability(“browserName”, “safari”)

driver = webdriver.Safari(options=options) try: driver.get(“https://example.com”) print(driver.title) finally: driver.quit()

This is intentionally simple. If this does not work, your problem is probably environment setup, not your test logic.

A few practical notes:

  • Make sure Safari remote automation is enabled.
  • Run the test locally on the Mac first before involving CI.
  • If you are using a remote Selenium Grid, remember that Safari cannot be run from a Linux node pretending to be a Mac.

Common setup problems on macOS

Most Safari automation failures are not caused by the test script. They are caused by environment mismatch.

Remote automation was not enabled

This is the most common issue. Selenium can connect to Safari only if Safari’s automation setting is on. If you are getting connection failures or browser launch problems, confirm the Develop menu setting first.

You are trying to run Safari in Docker or Linux

That will not work for real Safari. You can run Chrome and Firefox in containers, but Safari requires macOS.

The Mac is locked or asleep

A sleeping or locked machine can interrupt browser sessions. If your Mac host is acting as a test runner, disable sleep, screen lock, and power-saving behaviors that interfere with long-running tests.

Permissions changed after an OS upgrade

macOS updates can alter accessibility, automation, or browser behavior. If Safari tests start failing after a system update, review OS settings before blaming the test suite.

Tests assume Chrome-like behavior

Safari is usually standards-based, but there are still edge cases around file uploads, focus management, scroll behavior, date inputs, and async timing. Tests that depend on exact event timing can become brittle across browsers.

Writing Selenium tests that are more stable in Safari

Safari-specific flakiness often comes from the same causes as other browser flakiness, just more visibly.

Prefer explicit waits over sleep calls

If a page renders content asynchronously, wait for the actual condition you need instead of waiting an arbitrary amount of time.

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, 10) login_button = wait.until( EC.element_to_be_clickable((By.CSS_SELECTOR, “button[type=’submit’]”)) ) login_button.click()

Avoid brittle selectors

Safari is not the problem when selectors are fragile, but Safari is often where these problems surface first because timing and rendering differ enough to expose bad assumptions.

Prefer stable selectors such as:

  • data-testid
  • ARIA labels when appropriate
  • CSS selectors tied to test hooks, not layout structure

Be careful with native dialogs and downloads

Browser downloads, file pickers, and permission dialogs often need special handling. If your test relies on OS-native dialogs, confirm that your approach works on macOS and not just in Chrome on Linux.

Do not assume headless behavior

Safari automation is typically not a headless-first story like Chromium-based browsers in CI. If your test architecture depends heavily on headless execution, Safari may force a redesign.

Local Safari testing vs CI

There are two very different workflows here.

Local development on a Mac

Local execution is useful for debugging. You can step through the test, inspect the page state, and reproduce a suspected browser bug. For frontend developers, this is the fastest way to validate Safari-specific behavior.

Continuous integration

CI introduces the real challenge. If your pipeline runs on Linux-based runners, Safari is out. You need macOS runners or a browser testing service that already provides macOS infrastructure.

A rough decision rule:

  • If you only need occasional Safari validation, local Mac testing may be enough.
  • If Safari is part of your release gate, you need repeatable macOS infrastructure.
  • If your team does not want to own Macs, use a hosted solution that already does.

Running Selenium on a macOS CI runner

If you decide to self-host, your CI job needs to run on macOS, not Linux.

name: safari-tests

on: push: branches: [main]

jobs: safari: runs-on: macos-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: “3.11” - run: pip install selenium - run: python tests/test_safari.py

This gets you a macOS runner, but it does not solve everything. You still need to confirm Safari automation settings, manage browser state, and understand whether the runner persists between jobs. For real-world suites, the operational burden is usually higher than teams expect.

The hidden costs of self-hosted macOS

Maintaining your own Macs means dealing with:

  • OS and Safari updates
  • machine availability
  • screen locking and sleep settings
  • provisioning and access control
  • test isolation between runs
  • parallelization limits
  • hardware failures and reimaging

This is why many teams start with local Safari tests, then outgrow them quickly once the suite becomes part of CI.

Safari-specific failure patterns worth watching

When tests pass in Chrome and fail in Safari, the cause is often one of these patterns.

Timing-sensitive UI transitions

Animations, overlays, and delayed rendering can expose race conditions. If your test clicks something before Safari considers it actionable, the test will fail even if the same script passes elsewhere.

Focus and keyboard interactions

Keyboard navigation, tab order, and focus management can differ. Accessibility issues often appear first in Safari because the browser is stricter about some interaction patterns.

Login, session persistence, and third-party cookie behavior can vary depending on browser privacy settings. If your app uses embedded authentication or cross-site redirects, verify those flows directly in Safari.

Viewport and scroll behavior

Sticky headers, scroll positioning, and intersection-based lazy loading can behave differently enough to cause click interception or missing elements.

File upload paths

If your tests rely on local file paths, remember that your test host, browser session, and automation permissions all matter on macOS.

If a test only fails in Safari, treat that as a product signal first, not just a test issue. Safari is often telling you something about real user experience.

When Selenium is the right tool for Safari

Selenium is still a good choice when you need:

  • language-agnostic WebDriver control
  • legacy test suites in Java, Python, C#, or JavaScript
  • a unified automation model across multiple browsers
  • direct control over page interactions and browser state

If your team already has a mature Selenium suite, adding Safari can be pragmatic. The downside is not Selenium itself, it is the infrastructure and browser-management overhead around Safari.

When a simpler approach is better

If your real problem is “we need Safari coverage without building a Mac lab,” then Selenium plus self-managed Macs may be the wrong amount of work.

That is where a platform like Endtest becomes compelling. Endtest is built as an agentic AI Test automation platform, and its cross-browser testing product runs tests across real browsers on real Windows and macOS machines. For Safari specifically, that matters because the browser is not simulated or approximated, it is actual Safari on macOS.

For teams migrating from Selenium, Endtest also offers documentation for importing existing Selenium tests, which can reduce the cost of switching from a code-heavy workflow to a more maintainable one.

This does not mean every team should abandon Selenium. It means you should be honest about what you are paying for. If your engineers are spending time on Mac provisioning, driver troubleshooting, and environment drift instead of product quality, a managed platform may be the better tradeoff.

Practical decision matrix

Use this rough guide:

Stay with Selenium on Safari if:

  • you already have Selenium expertise in-house
  • you need code-level control for complex browser workflows
  • you have a stable macOS test environment already
  • Safari coverage is important, but not your biggest scaling problem

Consider a managed platform if:

  • you need real Safari but do not want to maintain Macs
  • your suite is flaky because of infrastructure, not test logic
  • you need faster onboarding for QA and engineering
  • you want cross-browser coverage without building separate browser farms

Consider Endtest specifically if:

  • you want real Safari on real macOS machines
  • you want browser coverage without local browser farms
  • you prefer a platform-native, lower-maintenance workflow over hand-rolled Selenium infrastructure

A realistic test strategy for Safari

A good browser strategy does not try to run every test everywhere. Instead, it defines where each layer belongs.

  • Unit tests cover business logic.
  • Component tests cover UI behavior in isolation.
  • A smaller end-to-end suite covers critical user journeys.
  • Safari coverage focuses on revenue-critical or high-risk flows.

That keeps your Safari suite valuable without making it enormous. For example, you might run login, checkout, and account management in Safari, while leaving lower-risk internal workflows to Chrome-only coverage.

Final thoughts

Running Selenium tests on real Safari is absolutely doable, but it is not a drop-in extension of a Chrome or Firefox setup. Safari lives on macOS, depends on Apple’s WebDriver support, and introduces operational constraints that affect CI design, parallelization, and maintenance.

If you only need to validate a few workflows, local macOS testing can be enough. If Safari is part of your release confidence, you need reliable macOS automation, strong waits, and disciplined test design. And if the real pain point is infrastructure ownership rather than the test code itself, a hosted platform like Endtest is often the simpler and more sustainable way to get real Safari coverage without maintaining a Mac fleet.

For teams that care about browser correctness, the key question is not whether Selenium can drive Safari. It can. The better question is whether your team wants to spend time running tests, or running test infrastructure.