How to Run Cypress Tests in WebKit

Cypress can run tests in WebKit, the browser engine used by Safari, through an experimental feature. To enable it, set experimentalWebKitSupport: true in your Cypress configuration, install playwright-webkit, install WebKit’s Linux system dependencies when applicable, and run npx cypress run --browser webkit. This exercises WebKit; it does not launch Apple Safari itself, and Cypress documents limitations that make it important to check whether your test suite depends on unsupported behavior.

1. Before you start

You need a Cypress project with Cypress installed as a development dependency, Node.js and a package manager supported by your project, and permission to install packages. On Linux, you also need the operating system libraries required by Cypress and WebKit. Follow Cypress’s current installation requirements for your distribution and CI image; installing WebKit’s dependencies alone does not satisfy Cypress’s own Linux prerequisites.

WebKit support is experimental and disabled by default. Cypress builds this integration on the Playwright WebKit browser. Check the current Cypress browser documentation and your project’s package compatibility before pinning versions; there is no version matrix established here to copy.

2. Enable WebKit support

Open the Cypress configuration file your project already uses: commonly cypress.config.js, cypress.config.ts, or the corresponding module-format variant. Add the experiment flag inside the existing configuration object. Do not replace your other project settings.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  experimentalWebKitSupport: true,
  e2e: {
    // Keep your existing e2e configuration here.
  },
})

If your project uses TypeScript or ES modules, preserve its current export syntax and add the same option to the object passed to defineConfig. The key is the configuration option experimentalWebKitSupport: true.

Cypress’s configuration reference also says injectDocumentDomain must be true when using experimental WebKit because cy.origin() is not supported. This setting has compatibility caveats, especially for cross-subdomain behavior. Review the current configuration documentation and validate your application’s behavior before adopting it as a workaround.

3. Install the WebKit browser package

From your project root, install Cypress’s WebKit browser package as a development dependency:

npm install playwright-webkit --save-dev

The package provides the WebKit browser Cypress detects for this experimental integration. Keep the resulting dependency manifest and lockfile in version control so local machines and CI install the same dependency graph.

4. Install Linux dependencies when needed

On Linux, install WebKit’s system dependencies using the documented Playwright command:

npx playwright install-deps webkit

This command addresses WebKit system libraries. It does not replace Cypress’s own Linux prerequisites. For containers and CI runners, make sure both Cypress and WebKit dependencies are installed in the environment that runs the tests. Use the instructions relevant to your distribution and image.

5. Run the test suite in WebKit

Run Cypress from the project root and choose WebKit explicitly:

npx cypress run --browser webkit

cypress run runs headlessly by default. To watch a local run in a visible browser window, add --headed:

npx cypress run --browser webkit --headed

For interactive test development, open Cypress and select WebKit from the browser picker after Cypress detects it:

npx cypress open

To record a run to Cypress Cloud, use the documented recording workflow only if it is configured for your project:

npx cypress run --browser webkit --record

The --record flag is not required to run WebKit tests.

6. Add WebKit to CI

Cypress requires the selected browser to be installed in the local or CI environment. Add the package and operating-system setup to the CI job before the test command, then invoke Cypress with --browser webkit. A generic shell sequence is:

npm ci
npx playwright install-deps webkit
npx cypress run --browser webkit

Use that Linux dependency command on Linux runners, and satisfy Cypress’s separate platform prerequisites as well. On other operating systems, follow the Cypress and Playwright installation steps for that platform. Make sure the job runs from the project root and uses the committed lockfile. If your CI provider uses a Cypress-provided image, confirm which browsers and system dependencies it includes instead of assuming WebKit is already present.

For a quick local check, run the suite in the browser already used by your team and then run the WebKit command. A green run in another browser does not establish that WebKit has been installed or that WebKit-specific behavior passes.

7. What WebKit coverage does—and does not—mean

Cypress describes WebKit as Safari’s browser engine and positions the experiment as a way to exercise that engine from platforms where Apple’s Safari automation is unavailable. This is useful for catching engine-specific rendering and behavior issues without claiming that the run is Apple Safari. WebKit support remains experimental, so treat its results as one part of browser coverage and check the known issues against your suite.

Question	Practical answer
Does this run Apple Safari?	No. It runs WebKit, Safari’s browser engine, through Cypress’s experimental integration.
Is the feature stable and enabled by default?	No. It is experimental and must be enabled in Cypress configuration.
Can it run in CI?	Yes, provided WebKit and the required system dependencies are installed in the runner and Cypress is invoked with `--browser webkit`.
Can every Cypress suite run unchanged?	Not necessarily. Review Cypress’s documented unsupported features and behavioral differences before relying on the run.

8. Known limitations to check before adopting it

cy.origin() is not supported in WebKit. Cross-origin or cross-subdomain flows that rely on it need special review.
Test Replay is not supported.
cy.intercept()’s forceNetworkError option is disabled.
Some cy.type() event properties differ: textInput events may lack data, and beforeinput events may lack inputType.
Typing {uparrow} or {downarrow} into input[type=number] does not round to the nearest configured step as it does in other contexts.
With experimentalSingleTabRunMode and video recording, only the first spec’s video is recorded.
Stack traces may omit function names or location information.

These limitations can affect assertions, test diagnostics, and cross-origin flows. If a test depends on one of the listed behaviors, isolate that test’s requirement before making WebKit a required CI gate. Cypress’s live browser guide may list further experiment issues.

9. Troubleshooting common failures

Symptom	Likely cause	What to check or change
WebKit does not appear in Cypress or the CLI reports it cannot find the browser	The experiment is disabled, `playwright-webkit` is missing, or dependencies were installed in a different project/environment.	Confirm `experimentalWebKitSupport: true` is in the active Cypress configuration, install the package from the project root, and rerun in that same environment.
WebKit launches locally but fails in Linux CI	The runner is missing WebKit system libraries or Cypress’s own Linux prerequisites.	Install WebKit dependencies with `npx playwright install-deps webkit` and follow Cypress’s Linux prerequisites for the runner’s distribution.
`cy.origin()` fails in WebKit	The command is unsupported by experimental WebKit.	Review the flow and Cypress’s configuration guidance for `injectDocumentDomain`; it must be true with this experiment, but may have compatibility caveats. Test cross-subdomain behavior explicitly.
An assertion on `cy.intercept()` network failure does not behave as expected	`forceNetworkError` is disabled in WebKit.	Do not use this option as a WebKit test premise; adjust the test strategy or run that particular behavior in another supported browser.
Typing assertions differ for number inputs or input events	Cypress documents WebKit differences in arrow-key rounding and event properties.	Check whether the assertion assumes the documented non-WebKit behavior. Test the user-visible result separately from browser-specific event details.
A later spec has no recorded video in single-tab mode	With `experimentalSingleTabRunMode`, WebKit records video only for the first spec.	Account for this limitation in diagnostics; do not interpret missing later videos as proof that those specs were skipped.
Failure stack trace lacks a useful source location	WebKit’s experimental stack trace output may omit names or location information.	Use the failing assertion and Cypress command log as additional context, and reproduce in another browser if needed to compare diagnostics.

If the issue is not in Cypress’s known list, reduce it to a small reproducible test and consult the current Cypress WebKit browser guide and issue tracker. Experimental behavior can change, so confirm against the documentation matching your installed Cypress version.

10. Performance, reliability, and maintenance

Headless execution is the default for cypress run, which suits CI and avoids requiring a visible desktop. No reliable performance comparison between WebKit and other Cypress browsers is established here; measure your own suite in the target runner rather than assuming WebKit will be faster or slower.

For repeatable CI runs, install dependencies from the lockfile, pin the CI image or operating system according to your team’s normal maintenance policy, and install the browser dependencies in the same job environment that launches Cypress. Keep the WebKit job visible as experimental in CI policy, particularly if it exercises unsupported features or produces incomplete diagnostics. Recheck the current Cypress documentation when upgrading Cypress or the browser package.

Cypress, Playwright WebKit, and system libraries are software dependencies; this setup has no special hardware purchase requirement. CI execution costs depend on your runner and suite duration, and this research does not establish a cost benchmark.

Or skip the browser setup

If your goal is to capture a page image or PDF rather than run interactive Cypress assertions, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. This does not replace Cypress browser testing; it is a simpler route when you need a page capture.

For API options and response details, see the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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}`);

Cookie banners are accepted and removed before the shot; newsletter popups and chat widgets are removed too.
Bot checks, blank pages, and failed loads are never billed. Response headers identify the page verdict and billing status.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots.

Frequently asked questions

Can Cypress WebKit tests run on Windows or Linux?

Cypress presents WebKit as a way to test the Safari engine on Windows, Linux, or CI. Linux requires WebKit system dependencies as well as Cypress’s own prerequisites.

Do I need to rewrite my Cypress tests for WebKit?

Many tests can use the same Cypress commands, but check the documented unsupported features and differences. In particular, do not assume cy.origin(), Test Replay, or forceNetworkError are available.

Is WebKit support enabled as soon as I install Cypress?

No. Set experimentalWebKitSupport: true and install playwright-webkit.

Should a WebKit run be my only Safari compatibility check?

No single experimental run establishes complete Safari equivalence. Use it as WebKit engine coverage and validate important behavior in the environments your application supports.