Heuristic:Microsoft Playwright Browser Specific Workarounds
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Debugging |
| Last Updated | 2026-02-11 22:00 GMT |
Overview
Browser-specific workarounds for Firefox (SNAP env vars, sandbox eval, contenteditable focus) and WebKit (missing checkVisibility API, animation sync) that prevent test failures and automation bugs.
Description
Each browser engine has unique quirks that require targeted workarounds in Playwright's implementation. Firefox has issues with Linux SNAP environment variables that break the browser when they are present but the Firefox build did not come from SNAP. Firefox also has a sandbox isolation bug where `self.eval` fails but `globalThis.eval` works. WebKit lacks the `checkVisibility` API and requires special handling for `details/summary` elements and animation synchronization during screenshots.
Usage
Be aware of these workarounds when debugging browser-specific test failures, implementing custom browser automation scripts, or contributing to Playwright's browser automation layer. If a test passes in Chromium but fails in Firefox or WebKit, these known issues should be the first things to investigate.
The Insight (Rule of Thumb)
- Firefox — SNAP Variables: Playwright always removes `SNAP_NAME` and `SNAP_INSTANCE_NAME` environment variables on Linux before launching Firefox. If you set custom Firefox env vars, be aware they may be modified.
- Firefox — Eval in Sandbox: Use `globalThis.eval()` instead of `self.eval()` when evaluating expressions in Firefox browser contexts. The sandbox isolation bug (Bugzilla #1814898) causes `self.eval` to fail silently.
- Firefox — Contenteditable Focus: When switching focus between contenteditable elements in Firefox, the previous element must be explicitly blurred first. Chromium handles this automatically.
- WebKit — checkVisibility: WebKit does not implement `Element.checkVisibility()`. Playwright falls back to manual visibility detection for `details/summary` elements.
- WebKit — Animation Sync: WebKit requires special synchronization before capturing screenshots to ensure animations are in a stable state.
- Trade-off: These workarounds add complexity but are necessary for cross-browser compatibility. Tests should be written browser-agnostically; the framework handles the differences internally.
Reasoning
These workarounds exist because browser engines implement web standards differently, and some features have bugs in specific engines. The SNAP variable issue affects Linux users who have SNAP installed (common on Ubuntu) — the environment variables confuse non-SNAP Firefox builds into looking for resources in wrong locations. The eval sandbox bug in Firefox is a known Mozilla issue that has not been fixed upstream, so Playwright must work around it. WebKit's missing `checkVisibility` is because the feature is not yet implemented in the engine (tracked in WebKit bug #264733).
Code Evidence
Firefox SNAP variable removal from `packages/playwright-core/src/server/firefox/firefox.ts:72-76`:
if (os.platform() === 'linux') {
// Always remove SNAP_NAME and SNAP_INSTANCE_NAME env variables since they
// confuse Firefox: in our case, builds never come from SNAP.
// See https://github.com/microsoft/playwright/issues/20555
return { ...env, SNAP_NAME: undefined, SNAP_INSTANCE_NAME: undefined };
}
Firefox eval sandbox workaround from `packages/playwright-core/src/server/frames.ts:1502-1505`:
// NOTE: make sure to use `globalThis.eval` instead of `self.eval` due to a bug with sandbox isolation
// in firefox.
// See https://bugzilla.mozilla.org/show_bug.cgi?id=1814898
let result = evaledExpression ?? globalThis.eval(expression);
Firefox home directory validation from `packages/playwright-core/src/server/firefox/firefox.ts:70-71`:
if (!path.isAbsolute(os.homedir()))
throw new Error(`Cannot launch Firefox with relative home directory. Did you set ${os.platform() === 'win32' ? 'USERPROFILE' : 'HOME'} to a relative path?`);