HOW TO TEST SAFARI WITH PLAYWRIGHT
2026 Student Guide

Symptom: Your web project passes its usual browser check, but you still need to know whether Safari will behave the same.

Fastest fix: Run Playwright tests with WebKit first. If your course or project requires proof of real Safari behavior, review the important flows in Safari on macOS. Playwright’s WebKit is not Safari itself.

This route is for you if you’re building a front-end course project on Windows, want to add an automated browser check, or need to report cross-browser results without overstating what you tested.

The key distinction is simple: a WebKit test is a useful first screen, while a Safari check means running Safari on macOS. Choose the level of testing that matches what you need to hand in.

Choose the result you need before installing anything

Start by writing down what the test must prove. “The site works” is too broad to guide a useful check. Your course may only require the page to load, or it may require evidence that a menu, form, or other interaction works. A request for Safari compatibility calls for a separate question: does the page behave correctly in Safari itself?

Playwright is a browser automation tool. Think of it as an automatic checker that opens a page and repeats steps you specify. WebKit is the browser engine Playwright uses for its WebKit runs. Safari is Apple’s browser, which also uses WebKit but is not launched by Playwright’s WebKit project.

The difference matters when you write your results. A screenshot or passing test from Playwright WebKit does not count as a screenshot or passing test from Safari. Use the exact browser name in your course submission, issue report, or project notes.

Compare the testing routes

Playwright supports Chromium, Firefox, and WebKit as browser engines. That is a choice of test environments, not a promise that every branded browser on those engines has been tested. Playwright’s browser documentation explains the supported engines and the WebKit-to-Safari boundary.

<

Route	What you test	Fit for a Windows student	Evidence you can claim
Playwright with WebKit on Windows	Your test flows in Playwright’s WebKit build	High for an early automated check	“Passed in Playwright WebKit”
Playwright with WebKit on macOS	The same kind of automated check, running on macOS	Useful if you can run the project there	“Passed in Playwright WebKit on macOS”
Safari on macOS	Your page in the Safari browser	Necessary when the requirement names Safari itself	“Checked in Safari on macOS”

These are editorial fit ratings, not performance scores. The first route is usually the quickest way to catch common problems in a Windows project. The last route is the one to choose when your assignment asks for Safari evidence, or when you are investigating a difference that only appears in Safari.

Running WebKit on macOS can bring the automated check closer to the Safari environment. It still does not turn Playwright’s WebKit into the Safari app. Playwright recommends running WebKit on macOS when you need a closer experience to Safari.

Set up a focused WebKit check

Keep the first test small. Pick a page that represents a real part of your project, then choose one interaction a student or teacher can verify without guessing. For example, test that the home page opens and that a navigation link leads to the expected page.

Install the project’s browsers

If Playwright is already set up in your project, install the WebKit browser using the project’s package tooling:

npx playwright install webkit

If you have not added Playwright yet, follow the official installation guide. It provides the current setup steps and platform requirements. Follow those instructions rather than copying a command from an old tutorial; installation details can change with Playwright releases.

Add a named WebKit project

In your Playwright configuration, define a project whose name is webkit and whose browser is WebKit. A small example looks like this:

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

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

Project names let you select a particular test setup from the command line. If your project already has a configuration, add or adjust the WebKit project instead of replacing settings you still need. See the official guide to configuring test projects if you use multiple browsers or different test settings.

Write a test that checks one result

A test should say what success looks like. For example, you could open your local project and check that its main heading appears:

import { test, expect } from '@playwright/test';

test('home page shows its heading', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await expect(
    page.getByRole('heading', { name: 'Course Project' })
  ).toBeVisible();
});

Replace the address and heading with values from your own project. Start your development server before running the test, or the page may fail to load even though the test itself is written correctly.

The test uses a locator to find the heading and an assertion to check the result. In plain terms, the locator tells Playwright what page element to look for, while the assertion checks whether the expected result appears. The locator guide recommends ways to find elements, and the assertion guide explains how to check outcomes.

Run only the WebKit project

Use the project name from your configuration to run just that test environment:

npx playwright test --project=webkit

The command is useful when you want a quick WebKit result without running every configured browser project. If it reports that no matching project exists, compare the spelling in the command with the name in your configuration. For more ways to select and run tests, use the official test-running guide.

Read the result before making a claim

A passing result means that the test’s stated checks passed in the selected environment. It does not mean that you tested every page, every interaction, or Safari itself. A failed result also does not automatically mean you found a browser bug; first find out whether the project started, the page loaded, and the test looked for the right thing.

Playwright’s locators and assertions can wait for expected conditions instead of requiring you to add a fixed pause to every test. That helps avoid some timing mistakes, but it cannot correct a broken selector or a missing page element. Check the actionability guide to understand what Playwright waits for before acting on a page.

Sort failures before calling them Safari bugs

When WebKit fails, compare what happened rather than jumping to a cause. Run the same test against Chromium and WebKit with the same project data. Keep the page address, steps, expected result, and error message together. This gives you a fair comparison and makes it easier for a teacher or teammate to reproduce the issue.

Use this sequence:

• Confirm the server is running. Open the project’s local address and check that the page appears. A stopped server can look like a browser failure.
• Check the failing page and action. Verify that the test navigates to the expected address and that the element it uses still exists.
• Review the locator. Prefer a locator that describes the element’s role or visible label when that fits your page. A selector for an element that changed during a redesign can fail in any browser.
• Read the assertion and log. Confirm that the test expects something your page actually displays. Note whether the failure is a timeout, a missing element, or an unexpected value.
• Compare the same test in both engines. If Chromium passes and WebKit fails, you have a browser-engine difference to investigate. If both fail at the same step, check the project or test before attributing the issue to Safari.
• Save evidence for later review. A Playwright trace can help you inspect what happened during a run. The Trace Viewer guide explains how to open and examine a trace.

A useful report names the browser that actually ran. Write “WebKit test failed” until you have reproduced the issue in Safari; do not relabel an automated WebKit result as a Safari bug.

If the failure is visual, record the exact page and what looks different: for example, whether a heading wraps onto another line or a button overlaps nearby text. If it concerns media, record which control you used and what you observed. These notes help you check the same behavior in Safari instead of relying on a vague description such as “the page looks wrong.”

Decide whether real Safari verification is required

Not every student project needs a real Safari review. Use the course requirements as the deciding factor. If the assignment asks for an automated WebKit run, a correctly reported WebKit result may be enough. If it asks for Safari compatibility or a Safari screenshot, arrange access to Safari on macOS.

Consider a separate review when you see a difference in font rendering, layout, or media playback that matters to your project. These are visible areas where a student can compare the same page and operation across environments. A WebKit pass is still valuable, but it cannot settle a question about a Safari-specific result.

Use this decision branch:

• If the deliverable asks only for a browser automation check, run the WebKit project and report the browser and result.
• If it asks for Safari by name, run the required page and actions in Safari on macOS and record that environment accurately.
• If WebKit fails but you do not know why, compare the same flow in Chromium, inspect the test, and reproduce the failure before assigning a cause.
• If WebKit passes but a Safari-specific concern remains, verify that page and behavior in real Safari rather than treating the pass as proof.
• If you cannot access a Mac before the deadline, submit the WebKit evidence only if your course allows it, state the limitation, and arrange an acceptable Mac review if Safari evidence is mandatory.

For a useful Safari review, write down the page, the action you took, and the result you saw. Add the browser name and operating system to your notes. If you take screenshots, make sure each one shows the relevant state rather than only the page before the interaction. This gives your reviewer enough context to understand what you actually tested.

FAQ

Is Playwright’s WebKit the same browser as Safari?

No. Playwright uses its own WebKit build, which is based on the WebKit project but is not the Safari app. A passing test shows that the checked flow worked in that WebKit environment. It does not prove that Safari on macOS will render every font, layout, or media feature identically.

Can I check Safari compatibility with Playwright on Windows?

Yes. Install Playwright’s WebKit browser and run the WebKit project from your Windows development environment. That gives you an automated first check for page loading and interactions. It cannot launch real Safari on Windows, so label the result as a WebKit test in your coursework or bug report.

When should I verify a page in real Safari?

Use Safari on macOS when your assignment explicitly asks for Safari evidence, or when you still need to investigate a visible layout, font, or media difference after the WebKit run. If your course requires real Safari results, a WebKit screenshot is not a substitute. Record the browser, page, action, and observed result.

How do I run only WebKit tests in Playwright?

Name the WebKit project webkit in your Playwright configuration, then run npx playwright test --project=webkit. The project name in the command must match the configured name. If your project uses another name or more complex settings, check the official Playwright guides for test projects and running tests.

Choose access based on the work you need to finish

For a class project, WebKit is a sensible first check when you are working on Windows and need to catch basic compatibility issues without claiming more than you tested. A real Safari review is the right next step when the rubric requires it or when a specific behavior remains uncertain.

If you need repeated, uninterrupted access to a Mac or need physical ports and direct device connections, evaluate whether a local Mac is a better fit; renting is not the right answer for every long-running workload. If you only need a temporary macOS environment to complete a Safari review, compare MACGPU’s remote Mac options with the requirements of your course, and check available Mac access before choosing. A remote Mac can provide the environment for a real Safari check, but your report should still say what browser, page, and actions you actually verified.