Registry / testing / fx-runner

fx-runner

JSON →
library1.4.0jsnpmunverified

fx-runner is a Node.js command-line interface (CLI) tool developed by Mozilla, designed to control and interact with Firefox browsers programmatically from the terminal. It simplifies tasks such as launching Firefox with specific profiles, passing arguments directly to the browser binary, and managing browser instances for testing or automation purposes. The project is actively maintained, with the latest stable version being 1.4.0, released in January 2024. Releases appear to be ad-hoc, driven by bug fixes and minor feature additions rather than a fixed cadence. Unlike full-fledged browser automation libraries (like Puppeteer or Playwright), `fx-runner` focuses purely on direct CLI interaction, making it particularly suitable for scripting environments, shell-based workflows, and scenarios where a lightweight, non-programmatic JavaScript control is preferred. Its primary differentiator is this direct command-line control over the Firefox binary and its associated profiles.

npm install fx-runner
INSTALL
IMPORT
SIG · FX-RUNNER
F
fx-runner
testingjavascriptv1.4.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Demonstrates how to execute the `fx-runner` CLI using Node.js's `child_process.spawn` to launch Firefox with a custom profile and a specific URL.

#!/usr/bin/env node const { spawn } = require('child_process'); // Example: Start Firefox with a specific profile and additional arguments const firefoxBinary = process.env.FIREFOX_BINARY || '/Applications/Firefox.app/Contents/MacOS/firefox'; // Adjust path for your OS const profilePath = process.env.FIREFOX_PROFILE_PATH || './my-test-profile'; // Path to an existing or new profile const urlToOpen = 'https://www.mozilla.org'; const args = [ 'start', '--binary', firefoxBinary, '--profile', profilePath, '--binary-args', `-url ${urlToOpen} -new-window` ]; console.log(`Launching Firefox with: fx-runner ${args.join(' ')}`); const child = spawn('fx-runner', args, { stdio: 'inherit', // Pipe child process stdout/stderr to parent shell: true // Use shell to correctly interpret command and args }); child.on('error', (err) => { console.error('Failed to start fx-runner:', err); }); child.on('exit', (code, signal) => { if (code !== 0) { console.error(`fx-runner exited with code ${code} and signal ${signal}`); } else { console.log('fx-runner exited successfully.'); } });
fx-runner --version
Debug
Known issues
breakingStarting with version 1.4.0, `fx-runner` changed its internal usage from `firefox-bin` to `firefox` as the default binary name. While this was a fix, users with highly customized Firefox installations or environments that explicitly relied on `firefox-bin` might experience launch failures.
fix
Ensure that the `firefox` executable is correctly located in your system's PATH or explicitly specify the full path to the `firefox` binary using the `--binary <path>` option.
affects: >=1.4.0
gotchaVersions prior to 1.0.11 had known vulnerabilities related to the `lodash` dependency, which could pose security risks. While `fx-runner` itself updated `lodash` in patch releases (1.0.9, 1.0.10, 1.0.11), using older versions might expose projects to these issues.
fix
Upgrade to `fx-runner` version 1.0.11 or newer to ensure that `lodash` vulnerabilities (specifically those addressed in lodash versions >=4.17.10) are mitigated.
affects: <1.0.11
gotchaOn Windows and macOS, earlier versions had issues correctly locating installed Firefox binaries and profiles. Specifically, 1.1.0 fixed Windows registry lookups, and 1.0.13 fixed macOS Developer Edition lookup and Beta/Nightly paths. Users on these platforms might encounter issues with `fx-runner` failing to find Firefox if using older versions.
fix
Update to at least `fx-runner` version 1.1.0 (for Windows fixes) or 1.0.13 (for macOS fixes) to benefit from improved Firefox discovery logic. If issues persist, explicitly provide the Firefox binary path and profile path using `--binary` and `--profile` options.
affects: <1.1.0
Errors
Common errors & fixes
Error: Command failed: fx-runner start --binary /path/to/firefox-bin ... (or similar 'command not found' for firefox-bin)
After version 1.4.0, `fx-runner` internally switched from using `firefox-bin` to `firefox`. If your environment or specific Firefox installation only exposed `firefox-bin` or if `firefox` is not in your PATH, the command may fail.
fix
Upgrade `fx-runner` to the latest version. If using a custom Firefox installation, verify that the `firefox` executable is available or explicitly specify its path using the `--binary` option, e.g., `fx-runner start --binary /Applications/Firefox.app/Contents/MacOS/firefox`.
fx-runner: error: option '--profile' requires an argument
The `--profile` option expects a path to a Firefox profile directory or a profile name to be provided immediately after it.
fix
Ensure you provide a valid path or profile name. Example: `fx-runner start --profile /path/to/my/profile` or `fx-runner start --profile default`.
Upgrade
Version history
1.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
fx-runner — npm install fx-runner · libregistry