firefoxOptions

The moz:firefoxOptions capability is a namespaced set of capabilities specific to Firefox. It is used to control the behaviour of Firefox and can be used as a member of alwaysMatch or as a member of one of the firstMatch entries.

It is used to define options which control how Firefox gets started and run.

moz:firefoxOptions is a JSON Object which may contain any of the following fields:

binary (string)
Absolute path to the custom Firefox binary to use.
On macOS you may either give the path to the application bundle, i.e. /Applications/Firefox.app, or the absolute path to the executable binary inside this bundle, for example /Applications/Firefox.app/Contents/MacOS/firefox-bin.
geckodriver will attempt to deduce the default location of Firefox on the current system if left undefined. The default locations of Firefox are:
System Default location
macOS
  1. /Applications/Firefox.app/Contents/MacOS/firefox-bin
  2. $HOME/Applications/Firefox.app/Contents/MacOS/firefox-bin
Linux
BSD

First firefox found on the system path. This is equivalent to the output of running which(1):

% which firefox
/usr/bin/firefox
Windows

From the Window system registry:

  1. HKEY_LOCAL_MACHINE\SOFTWARE WOW6432Node\Mozilla\Mozilla Firefox\[VERSION]\Main\PathToExe
  2. HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox\[VERSION]\Main\PathToExe
args (array of strings)

Command line arguments to pass to the Firefox binary. These must include the leading dash (-) where required, e.g. ["-headless"].

To have geckodriver pick up an existing profile on the filesystem, you may pass ["-profile", "/path/to/profile"].

profile (string)

Path to the profile directory to use for the Firefox instance. This may be used to e.g. install extensions or custom certificates, but for setting custom preferences we recommend using the prefs entry instead of passing a profile.

The profile will be packaged and sent across to the target machine, where they will be recreated in the target system’s temporary folder. If profile is undefined, geckodriver will create a new, fresh profile in this location.

The effective profile in use by the WebDriver session is returned to the user in the moz:profile capability in the new session response.

To have geckodriver pick up an existing profile on the filesystem, please set the args field to {"args": ["-profile", "/path/to/your/profile"]}. Note that if you use a remote client targetting a server on a different system, the profile must already exist on the target system.

log (Log object)
To increase the logging verbosity of geckodriver and Firefox, you may pass a log object that may look like {"log": {"level": "trace"}} to include all trace-level logs and above
prefs (Preferences object)
Map of preference name to preference value, which can be a string, a boolean or an integer.

Android

Starting with geckodriver 0.26.0 additional capabilities exist if Firefox or an application embedding GeckoView has to be controlled on Android:

androidPackage (string, required)
The package name of Firefox, e.g. org.mozilla.firefox, org.mozilla.firefox_beta, or org.mozilla.fennec depending on the release channel, or the package name of the application embedding GeckoView, e.g. org.mozilla.geckoview_example.
androidActivity (string, optional)
The fully qualified class name of the activity to be launched, e.g. .GeckoViewActivity. If not specified, the package’s default activity will be used.
androidDeviceSerial (string, optional)
The serial number of the device on which to launch the application. If not specified and multiple devices are attached, an error will be returned.
androidIntentArguments (array of strings, optional)
Arguments to launch the intent with.  Under the hood, geckodriver uses Android am to start the Android application under test.  The given intent arguments are appended to the am start command.  See Android's specification for intent arguments for details.  This allows to control how the application is launched and to include optional extras for enabling and disabling features.  For example, to launch with the view action and a specified URL before navigating as part of a test, include:
{
  "androidIntentArguments": [
    "-a", "android.intent.action.VIEW",
    "-d", "https://example.com"
  ]
}
For example, to specify a boolean extra that can be processed with android.content.Intent.getBooleanExtra, include:
{
  "androidIntentArguments": [
    "--ez", "customBooleanFlagName", "true"
  ]
}

Log object

A JSON Object that may have any of these fields:

level (string)
Set the level of verbosity of geckodriver and Firefox. Available levels are trace, debug, config, info, warn, error, and fatal. If left undefined the default is info. The value is treated case-insensitively.

Preferences object

A JSON Object with one entry per preference to set. The preference will be written to the profile before starting Firefox. A full list of available preferences is available from visiting "about:config" in your Firefox browser. Some of these are documented on the preference reference page.

An example of a preference object:

{
  "dom.ipc.processCount": 8,
  "javascript.options.showInConsole": false
}

Example

The following is an example of a full capabilities object that selects a specific Firefox binary to run with a prepared profile from the filesystem in headless mode. It also increases the number of IPC processes through a preference, turns off chrome errors/warnings in the console, and enables more verbose logging:

{
  "capabilities": {
    "alwaysMatch": {
      "moz:firefoxOptions": {
        "binary": "/usr/local/firefox/bin/firefox",
        "args": ["-headless", "-profile", "/path/to/my/profile"],
        "prefs": {
          "dom.ipc.processCount": 8,
          "javascript.options.showInConsole": false
        },
        "log": {"level": "trace"}
      }
    }
  }
}

The moz:firefoxOptions must be placed—as above—inside alwaysMatch, or in one of the firstMatch capabilities objects as seen here:

{
  "capabilities": {
    "firstMatch": [
      {"moz:firefoxOptions": …}
    ]
  }
}

Android

This runs the GeckoView example application as installed on the first Android emulator running on the host machine:

{
  "capabilities": {
    "alwaysMatch": {
      "moz:firefoxOptions": {
        "androidPackage": "org.mozilla.geckoview_example",
        "androidActivity": "org.mozilla.geckoview_example.GeckoView",
        "androidDeviceSerial": "emulator-5554",
        "androidIntentArguments": [
          "-d", "http://example.org"
        ]
      }
    }
  }
}

See also