skip to content

Why is WebKit missing from Cypress 16's browser list despite experimentalWebKitSupport?

level: middleimportance: should knowfreq 37%

answer

  1. A configuration flag on its own is not enough
  2. Cypress resolves a package from your project
  3. The engine comes from Playwright, not Cypress
  4. Linux needs extra system libraries too
  5. Some Cypress features are disabled there

basics

~20 s

Because the configuration flag is only half of the opt-in. Cypress finds WebKit by resolving Playwright's playwright-webkit package from the project directory, so with the flag set but that package missing there is no WebKit build to list.

solid answer

~40 s

As of Cypress 16, experimental WebKit needs two independent things. First, `experimentalWebKitSupport: true` in `cypress.config.js`. Second, the `playwright-webkit` npm package installed in the project - Cypress does not bundle a WebKit build, it resolves that package from the project directory and reads the browser out of it. Miss the package and WebKit never appears, flag or no flag. Miss the flag and WebKit is detected but carries a warning saying the experiment is not enabled; launching it anyway throws an error telling you to add the option. On Linux you also need the engine's system libraries, installed with Playwright's `playwright install-deps webkit`. Once both halves are in place, `cypress run --browser webkit` works like any other browser, and `Cypress.browser.family` reports `'webkit'`.

code

javascript · 11 lines
javascript
// cypress.config.js  -- also run: npm install --save-dev playwright-webkit
import { defineConfig } from 'cypress'

export default defineConfig({
  experimentalWebKitSupport: true,
  defaultBrowser: 'chrome',
  e2e: {
    baseUrl: 'http://localhost:4300',
    specPattern: 'cypress/e2e/statements/**/*.cy.js',
  },
})

go deeper

for a junior

Know that Safari cannot be launched by Cypress and that WebKit, its engine, is an opt-in experiment rather than something available out of the box.

for a middle

Explain both halves of the opt-in and what each one alone produces: a browser that never appears, versus a detected browser that refuses to launch with an explicit error.

for a senior

Be ready to say how you would introduce a WebKit job to an existing suite without making it a source of noise, and which known gaps you would exclude specs around.

for a principal

Decide what claim the organisation is allowed to make from an experimental engine, and where the residual Safari risk is carried instead of pretending the experiment closed it.

WebKit is the only way a Cypress suite gets near Safari's engine, and it is the browser teams most often fail to switch on. The reason is that the opt-in has **two independent halves**, and having one without the other produces two different, confusingly quiet failures. ## The two halves of the opt-in 1. **The experiment flag.** `experimentalWebKitSupport: true` at the root of `cypress.config.js`. This is what tells Cypress the experiment is permitted. 2. **The browser binary.** Cypress ships no WebKit build. It obtains one by resolving Playwright's **`playwright-webkit`** npm package from the project's working directory and reading the executable path out of it. If that package is not a dependency of the project, there is nothing for Cypress to detect. Both are required. The flag is permission; the package is the browser. ## The failure modes you will actually hit - **Flag set, package missing.** WebKit simply never appears in the browser list and `--browser webkit` fails to find it. Nothing points at the missing package, which is why this one wastes the most time. - **Package installed, flag missing.** Cypress *does* detect WebKit, but attaches a warning that `playwright-webkit` is installed and WebKit detected while `experimentalWebKitSupport` is not enabled. Launching it regardless throws: WebKit was launched but the experimental feature was not enabled. - **Both present, Linux system libraries missing.** The browser is listed but will not start. Playwright ships the installer for its dependencies - run `npx playwright install-deps webkit` in the image or job that launches Cypress. ## What experimental WebKit buys you Safari's automation is not shipped on every platform, so WebKit is the practical way to see how a bank statement app behaves in Safari's engine **from Linux, Windows or CI, without a Mac**. That is genuine coverage: layout of the statement table, CSS support, and how the embedded third-party PDF viewer is laid out are all engine-level behaviours WebKit exercises. Once enabled it behaves like any other browser: `cypress run --browser webkit`, `Cypress.browser.name === 'webkit'`, `Cypress.isBrowser('webkit')`, and `family` reporting `'webkit'`. Note where the version comes from - Cypress reads the WebKit version out of Playwright's own browser metadata rather than asking the binary, so the engine you are testing is whatever version of `playwright-webkit` your lockfile carries. Upgrading that package is how you move to a newer WebKit; nothing in Cypress does it for you. ## What it does not cover It is an **experiment**, and Cypress documents the gaps rather than hiding them. As of Cypress 16: - `cy.origin()` is not supported in WebKit. - Test Replay is not supported. - `cy.intercept()`'s `forceNetworkError` option is disabled. - With `experimentalSingleTabRunMode` and video recording, only the first spec's video is recorded. - `cy.type()` differs in detail: `textInput` events lack the `data` property, `beforeinput` events lack `inputType`, and up/down arrow typing on an `input[type=number]` does not round to the nearest `step`. - Stack traces may be missing function names and location information. And the larger caveat: **WebKit is Safari's engine, not Safari.** Safari-specific UI behaviour, extensions, and platform integration are outside what this experiment reproduces. Treat a green WebKit run as evidence the engine is happy, not as a Safari sign-off. ## How to use it without destabilising a suite - Enable it, run the suite once, and read the failures before deciding anything - a first WebKit run on a suite written against Chrome will find real differences and also a few WebKit gaps from the list above. - Exclude what the experiment cannot run using Cypress's test configuration `browser` option, for example `describe('cross-origin statement export', { browser: '!webkit' }, ...)`, rather than leaving a permanently red spec. - Keep the WebKit job separate from the job that blocks a merge until you trust it. An experiment gating a deploy is a bad trade, and the documented gaps mean some failures will be the experiment's rather than the application's. - Expect the diagnosis to be harder there. Stack traces from WebKit may be missing function names and locations, and Test Replay is unavailable, so a failure you cannot reproduce locally is genuinely more expensive to chase than the same failure in Chrome. - Pin `playwright-webkit` like any other dependency; the WebKit version you test against is the version that package carries, and Cypress reads it from Playwright's own metadata to report the browser version. The honest summary for an interview: Cypress covers Chromium browsers and Firefox properly, and offers Safari's engine as an opt-in experiment assembled from two parts - a configuration flag and a Playwright package - with a documented list of features that do not work there.

  • How do you tell from inside a Cypress test that it is running under WebKit?
    `Cypress.isBrowser('webkit')` answers it directly, and `Cypress.browser.family` reports `'webkit'` with `name` also `'webkit'`. For a whole suite the cleaner move is Cypress's test configuration `browser` option - `describe('statement export', { browser: '!webkit' }, ...)` - so a spec the experiment cannot run is excluded rather than left failing.
  • What extra setup does experimental WebKit need on Linux?
    WebKit needs system libraries a bare Linux image does not carry. Playwright ships the installer: run `npx playwright install-deps webkit` in the image or CI job that launches Cypress. Without it the browser is detected but fails to start. That is on top of installing `playwright-webkit` and setting `experimentalWebKitSupport: true` - three steps on Linux, two elsewhere.

saying these in an interview costs you the question

  • Thinks --browser webkit works with the flag alone
  • Believes Cypress bundles a WebKit build like Electron
  • Says a green WebKit run is a Safari sign-off
  • Assumes every Cypress feature behaves the same in WebKit
  • Treats experimental WebKit as a supported production browser