How to Test Website Screenshots on Safari Using Playwright
Use Playwright’s WebKit project to capture and compare website screenshots, keep visual baselines stable, and understand what the results say about Safari.
Use Playwright Test’s WebKit project to capture website screenshots and compare them with visual baselines. Playwright does not automate the branded Safari application: its WebKit build is a patched browser engine. A passing test is useful evidence about WebKit rendering, but it does not prove that a particular Safari release renders the page identically.
For the closest Playwright approximation to Safari, run WebKit on macOS. Linux WebKit is often a lower-cost CI option. When a release depends on Safari-specific behavior, add a check in actual Safari on the supported operating systems and devices. See Playwright’s [browser documentation](https://playwright.dev/docs/browsers).
1. Install Playwright and its WebKit browser
In an existing Node.js project, install Playwright Test and the browser binaries that match that package version:
npm install --save-dev @playwright/test
npx playwright install webkitOn Linux CI, the browser may also need operating-system dependencies. Install them with Playwright’s documented dependency command for your environment:
npx playwright install --with-deps webkitKeep the installed Playwright package and browser binaries in sync. When you upgrade the package, rerun the browser installation step in local and CI environments.
2. Configure a WebKit project
Projects let one Playwright configuration run tests with different browser, device, or environment settings. The Desktop Safari device profile supplies a useful set of Safari-like defaults. You can also specify the viewport explicitly when consistent dimensions matter more than the device profile’s defaults.
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
projects: [
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
],
});Run just this project with:
npx playwright test --project=webkitThe project name in the command must match the name in your configuration. For a mobile-oriented WebKit run, use an appropriate iPhone device profile available in your installed Playwright version, and give that project its own name. Project setup and selection are covered in [Playwright Projects](https://playwright.dev/docs/test-projects).
3. Capture and compare a page screenshot
For visual regression checks, use Playwright Test’s toHaveScreenshot() assertion. The first run creates a reference image; later runs capture the page and compare it with that reference.
// tests/homepage.spec.ts
import { test, expect } from '@playwright/test';
test('homepage matches its visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('homepage.png');
});Generate the initial baseline by running the test, then inspect the resulting image before committing it. A generated snapshot is not automatically a correct snapshot: verify that the page loaded successfully and represents the intended state. Keep the baseline with the code so CI compares against a reviewed reference.
To capture a one-off image without a visual assertion, use the Page API:
import { test } from '@playwright/test';
test('save a WebKit screenshot', async ({ page }) => {
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png', fullPage: true });
});The fullPage option captures the full scrollable page; omit it for the visible viewport. See the [Page API](https://playwright.dev/docs/api/class-page) and [visual comparisons guide](https://playwright.dev/docs/test-snapshots) for assertion and screenshot options, including named screenshots and image formats such as PNG and WebP.
4. Review baselines and control sources of drift
Screenshot output can vary with the host operating system, browser version, settings, hardware, power source, headless mode, fonts, and page state. Playwright recommends generating and comparing references in the same environment. Use separate project-specific references when you deliberately compare different environments; a Linux image and a macOS image are not interchangeable baselines.
- Pin and record the Playwright version and install its matching WebKit binaries.
- Use the same CI image, operating system, viewport, device profile, and headed or headless mode for baseline generation and comparisons.
- Make the page state repeatable: use stable test data and wait for the relevant content before capturing.
- Review baseline changes as code changes. Refresh snapshots only when the visual change is intentional.
When a deliberate change requires new references, use:
npx playwright test --project=webkit --update-snapshotsDo not accept every generated difference without review. A broad pixel tolerance can conceal a real layout regression. If you set maxDiffPixels or another threshold, base it on the image and the variation you actually intend to allow. The assertion also supports a stylesheet option for hiding dynamic elements. Use it only when the hidden content is not part of what the test should validate.
When a comparison fails, inspect the expected, actual, and diff images. The [Trace Viewer](https://playwright.dev/docs/trace-viewer) can show image comparisons alongside test context and help identify whether the page changed or the run environment drifted.
5. Choose the right Safari fidelity for the check
Playwright’s WebKit is derived from recent WebKit source and uses Playwright patches. Its version may include changes before they reach Apple Safari. Playwright states that it does not work with branded Safari. macOS WebKit offers the closest-to-Safari Playwright experience; Linux may be more affordable for CI. Neither result is identical to running the Safari application.
| Goal | Useful setup | What the result establishes |
|---|---|---|
| Catch broad WebKit rendering regressions in CI | WebKit project on Linux | The page rendered in that Playwright WebKit and CI environment. |
| Get closer to Apple platform behavior within Playwright | WebKit project on macOS | The page rendered in Playwright WebKit on macOS; it is still not branded Safari. |
| Validate a specific Safari release or Safari-only behavior | Run an additional check in actual Safari on the supported OS/device | The tested page behavior in that actual Safari environment. |
A passing Playwright WebKit screenshot test gives useful coverage of WebKit rendering. It does not certify the page in every Safari version or on every Apple device. This distinction matters especially for platform-dependent behavior such as video playback.
6. Troubleshooting common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| WebKit executable is missing | The browser binary was not installed for the current Playwright package version. | Run npx playwright install webkit after installing or upgrading Playwright. |
| Linux reports missing shared libraries | The runner lacks WebKit’s operating-system dependencies. | Install dependencies with npx playwright install --with-deps webkit, or use the matching setup for the CI image. |
| The project selector finds no tests | The CLI project name does not match the configured project, or the test is excluded by configuration. | Check the project’s name, test directory, and filters; run the configured project name with --project. |
| Many pixels differ only in CI | The baseline and CI may differ in OS, browser build, fonts, headless mode, hardware, viewport, or page state. | Reproduce in the baseline environment and compare those settings before updating references. |
| The page screenshot is blank or incomplete | Navigation may have failed, or the capture may happen before the relevant content is ready. | Check navigation and page errors, wait for the page content the test needs, and inspect the actual image before creating a baseline. |
| Every run produces a different diff | The page may contain animation, timestamps, rotating content, or other dynamic state. | Stabilize test data and state. Hide dynamic content with the assertion stylesheet option only when that content is intentionally outside the test. |
| Snapshot update changes many files | The rendering environment or browser version may have changed, or the page underwent a broad visual change. | Review diffs individually, check version and runner changes, and keep only intentional new references. |
| A passing result is being treated as Safari certification | Playwright is running its WebKit build, not branded Safari. | Run actual Safari as a separate release check when a specific Safari version or platform behavior matters. |
7. Performance, reliability, and maintenance
For repeated CI comparisons, keep the browser installation in the CI image or cache it according to your CI provider’s rules. Avoid reinstalling browsers unnecessarily on every test run. Run the WebKit project alone when investigating a WebKit-specific failure; run the broader project matrix when you need cross-browser coverage.
Reliability depends on controlling both the browser environment and the page. Pin versions intentionally, install matching binaries, use consistent fonts and runner images, and make the application state predictable. When a test fails, first compare the runner OS/image, Playwright and WebKit versions, viewport or device profile, headless setting, fonts, and page state. This checklist follows from Playwright’s documented sources of rendering variation.
There is no universal pixel threshold or speed figure that makes a visual test reliable. Choose tolerances based on the page and review the diffs. The ongoing cost is mostly the maintenance of stable test environments and reviewed baselines; Linux can be a lower-cost WebKit CI choice, while macOS is closer to Safari for platform-specific checks.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a screenshot or PDF, and the [API documentation](https://screenshotneo.com/docs/) describes its options. This is useful when you need a captured website image without installing or maintaining a local browser project; it does not replace a Playwright visual regression test or a check in actual Safari.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Start with 1,000 free screenshots a month, no card required.
FAQ
Can Playwright test Safari?
It can test with Playwright’s WebKit browser, but it does not automate the branded Safari application. Use actual Safari separately when that distinction matters.
Should I use Linux or macOS for WebKit screenshots?
Linux is often a lower-cost CI option. macOS provides Playwright’s closest-to-Safari WebKit experience, but does not turn the test into a branded Safari run.
When should I update a screenshot baseline?
After confirming that the page change is intentional and reviewing the new image. If the diff is unexpected, investigate environment and page-state changes first.
Can a screenshot test catch every Safari issue?
No. It checks rendered pixels in the configured Playwright WebKit environment. It cannot establish behavior across all Safari releases, devices, or platform-specific features.
