Environment:DevExpress Testcafe Firefox Marionette
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Browser_Automation |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
Firefox browser environment using the Marionette remote automation protocol for TestCafe test execution, screenshots, and window management.
Description
TestCafe communicates with Firefox via the Marionette protocol, a TCP-based remote automation interface built into Firefox. The `MarionetteClient` connects on a configurable port (default 2828) with a 30-second connection timeout. TestCafe creates a temporary Firefox profile with automation-optimized preferences that disable telemetry, updates, crash recovery, download prompts, and timeout throttling. The profile also configures Marionette port and enables the Marionette service. Firefox supports headless mode via the `-headless` flag, multiprocessing control, and user profile mode.
Usage
Required for any test execution targeting Firefox browsers. Use this when you need to test Firefox-specific behavior, cross-browser compatibility, or when Chrome is not available. Firefox headless mode is suitable for CI environments.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | All major platforms supported |
| Browser | Mozilla Firefox | Recent version with Marionette support |
| Network | Local TCP port for Marionette | Default 2828, or dynamically allocated |
| Display | X11 display or headless mode | Linux requires DISPLAY env var or `-headless` flag |
Dependencies
System Packages
- `firefox` (browser binary)
- `xvfb` (virtual framebuffer, Linux headless without `-headless` flag)
NPM Packages
- `testcafe-browser-tools` = 2.0.26 (window management utilities)
Credentials
No credentials required for Firefox browser operation.
Quick Install
# Linux (Ubuntu/Debian)
apt-get install -y firefox
# macOS (Homebrew)
brew install --cask firefox
# Alpine (Docker)
apk add firefox
Code Evidence
Marionette client connection setup from `src/browser/provider/built-in/dedicated/firefox/marionette-client/index.js:9-14`:
const CONNECTION_TIMEOUT = 30000;
export default class MarionetteClient {
constructor (port = 2828, host = '127.0.0.1') {
this.port = port;
this.host = host;
Firefox temp profile Marionette configuration from `src/browser/provider/built-in/dedicated/firefox/create-temp-profile.ts:61-66`:
if (marionettePort) {
prefs = prefs.concat([
`user_pref("marionette.port", ${marionettePort});`,
'user_pref("marionette.enabled", true);',
]);
}
Firefox timeout throttling configuration from `src/browser/provider/built-in/dedicated/firefox/create-temp-profile.ts:51-57`:
// NOTE: dom.min_background_timeout_value should be equal to dom.min_timeout_value
'user_pref("dom.min_background_timeout_value", 4);',
'user_pref("dom.timeout.throttling_delay", 0);',
'user_pref("dom.timeout.budget_throttling_max_delay", 0);',
// NOTE: We set the foreground configuration for the background budget throttling parameters
'user_pref("dom.timeout.background_throttling_max_budget", -1);',
'user_pref("dom.timeout.background_budget_regeneration_rate", 1);',
macOS-specific Firefox lifecycle handling from `src/browser/provider/built-in/dedicated/firefox/index.js:62-63`:
if (OS.mac && !config.headless)
await stopLocalFirefox(runtimeInfo);
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| Marionette connection timeout | Firefox did not start Marionette within 30s | Check Firefox is installed and Marionette is enabled in profile |
| Browser connection timeout | Firefox failed to initialize | Increase `browserInitTimeout`; verify DISPLAY is set on Linux |
| Profile lock error | Previous Firefox instance using same profile | Close stale Firefox processes; TestCafe uses temp profiles by default |
Compatibility Notes
- macOS: Firefox requires explicit `stopLocalFirefox()` cleanup in non-headless mode. Browser launch is serialized on macOS (cannot start multiple instances concurrently).
- Headless mode: Uses `-headless` Firefox flag. No window manager or X11 display required.
- Multiprocessing: Can be disabled via Firefox config option `disableMultiprocessing`, which sets `browser.tabs.remote.autostart` to false.
- Marionette port: Defaults to 2828 but can be configured; dynamically allocated when not using user profile.