Heuristic:Puppeteer Puppeteer Firefox Single Process Workaround
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Cross_Browser |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
Puppeteer forces Firefox to use a single content process (`fission.webContentIsolationStrategy: 0`) because Firefox does not yet support mouse event dispatch from the main frame context with process isolation.
Description
Firefox Fission (site isolation) splits web content into separate processes per site. However, Puppeteer requires the ability to dispatch mouse events from the main frame context to child frames. With Fission enabled, mouse events dispatched via the protocol cannot reach cross-process frames. This is a known Firefox limitation tracked at bugzilla.mozilla.org/show_bug.cgi?id=1773393. The workaround forces all web content into a single content process by setting `fission.webContentIsolationStrategy` to `0`.
Usage
This heuristic is applied automatically by Puppeteer whenever Firefox is launched. No user action is required. However, users should be aware that:
- Firefox automation runs with reduced process isolation compared to normal Firefox
- Mouse event interactions with cross-origin iframes may not work even with this workaround in some edge cases
- This preference will be removed once Firefox fixes the upstream bug
The Insight (Rule of Thumb)
- Action: Puppeteer automatically sets `fission.webContentIsolationStrategy: 0` in Firefox preferences. Do not override this unless you are not using mouse events.
- Value: Enables mouse click, hover, and drag operations across all frames in Firefox.
- Trade-off: Reduced process isolation reduces security boundaries between sites. This is acceptable for testing but means Firefox automation does not perfectly replicate production Firefox behavior.
- Temporary: This workaround is marked with a TODO to remove once Firefox bug 1773393 is resolved.
Reasoning
Firefox Fission creates separate content processes for different sites to improve security. When content is in a different process, the main browser process cannot directly dispatch input events to it via the WebDriver protocol. Puppeteer needs to synthesize mouse events at precise coordinates, which requires direct access to the content process handling that frame.
From `packages/puppeteer-core/src/node/FirefoxLauncher.ts:30-40`:
static getPreferences(
extraPrefsFirefox?: Record<string, unknown>,
): Record<string, unknown> {
return {
...extraPrefsFirefox,
// Force all web content to use a single content process. TODO: remove
// this once Firefox supports mouse event dispatch from the main frame
// context. See https://bugzilla.mozilla.org/show_bug.cgi?id=1773393.
'fission.webContentIsolationStrategy': 0,
};
}
Note: User-provided `extraPrefsFirefox` are spread first, but the fission preference is set afterward and will override any user attempt to enable Fission.
Platform-specific default arguments from `packages/puppeteer-core/src/node/FirefoxLauncher.ts:189-196`:
switch (os.platform()) {
case 'darwin':
firefoxArguments.push('--foreground'); // Required on macOS
break;
case 'win32':
firefoxArguments.push('--wait-for-browser'); // Required on Windows
break;
}