WebDriver <-> Marionette proxy
Rust Shell

README.md

geckodriver Build Status

Proxy for using W3C WebDriver-compatible clients to interact with Gecko-based browsers.

This program provides the HTTP API described by the WebDriver protocol to communicate with Gecko browsers, such as Firefox. It translates calls into the Marionette automation protocol by acting as a proxy between the local- and remote ends.

You can consult the change log for a record of all notable changes to the program. Releases are made available on GitHub on supported platforms.

Supported Firefoxen

Marionette and geckodriver are not yet feature complete. This means that they do not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. You can track the implementation status of the latest Firefox Nightly on MDN. We also keep track of known Marionette, Selenium, and specification problems in our issue tracker.

Support is best in Firefox 48 and onwards, although generally the more recent the Firefox version, the better the experience as they have more bug fixes and features. We strongly advise using the latest Firefox Nightly with geckodriver, and want to make it clear that Firefox 47 and earlier is explicitly not supported. Since Windows XP support in Firefox will be dropped with Firefox 53, we do not support this platform.

WebDriver capabilities

geckodriver supports a number of WebDriver capabilities:

Name Type Description
proxy proxy object Sets browser proxy settings.
acceptInsecureCerts boolean Boolean initially set to false, indicating the session will not implicitly trust untrusted or self-signed TLS certificates on navigation.

proxy object

Name Type Description
proxyType string Indicates the type of proxy configuration. This value must be one of pac, noproxy, autodetect, system, or manual.
proxyAutoconfigUrl string Defines the URL for a proxy auto-config file. This property should only be set when proxyType is pac.
ftpProxy string Defines the proxy hostname for FTP traffic. Should only be set then the proxyType is set to manual.
ftpProxyPort number Defines the proxy port for FTP traffic. This property should only be set when proxyType is manual.
httpProxy string Defines the hostname for HTTP traffic. This property should only be set when proxyType is manual.
httpProxyPort number Defines the proxy port for HTTP traffic. This property should only be set when proxyType is manual.
sslProxy string Defines the proxy hostname for encrypted TLS traffic. This property should only be set when proxyType is manual.
sslProxyPort number Defines the proxy port for SSL traffic. This property should only be set when proxyType is manual.
socksProxy string Defines the proxy hostname for a SOCKS proxy. This property should only be set when proxyType is manual.
socksProxyPort number Defines the proxy port for a SOCKS proxy. This property should only be set when proxyType is manual.
socksVersion number Defines the SOCKS proxy version. This property should only be set when proxyType is manual.
socksUsername string Defines the username used when authenticating with a SOCKS proxy. This property should only be set when proxyType is manual.
socksPassword string Defines the password used when authenticating with a SOCKS proxy. This property should only be set when proxyType is manual.

Firefox capabilities

geckodriver also supports a capability named moz:firefoxOptions which takes Firefox-specific options. This must be a dictionary and may contain any of the following fields:

Name Type Description
binary string Absolute path of the Firefox binary, e.g. /usr/bin/firefox or /Applications/Firefox.app/Contents/MacOS/firefox, to select which custom browser binary to use. If left undefined geckodriver will attempt to deduce the default location of Firefox on the current system.
args array of strings Command line arguments to pass to the Firefox binary. These must include the leading -- where required e.g. ["--devtools"].
profile string Base64-encoded zip of a profile directory to use as the profile for the Firefox instance. This may be used to e.g. install extensions or custom certificates.
log log object Logging options for Gecko.
prefs prefs object Map of preference name to preference value, which can be a string, a boolean or an integer.

log object

Name Type Description
level string Set the level of verbosity in Gecko. Available levels are trace, debug, config, info, warn, error, and fatal. If left undefined the default is info.

prefs object

Name Type Description
preference name string, number, boolean One entry per preference to override.

Capabilities examples

To select a specific Firefox binary and run it with a specific command-line flag, set a preference, and enable verbose logging:

{
    "moz:firefoxOptions": {
        "binary": "/usr/local/firefox/bin/firefox",
        "args": ["--no-remote"],
        "prefs": {
            "dom.ipc.processCount": 8
        },
        "log": {
            "level": "trace"
        }
    }
}

Usage

Usage steps are documented on MDN, but the gist of it is this:

% geckodriver -b /usr/bin/firefox

Or if you’re on Mac:

% geckodriver -b /Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

You may also see all flags and options available in geckodriver by viewing the help message:

% geckodriver -h
geckodriver 0.11.1
WebDriver implementation for Firefox.

USAGE:
    geckodriver [FLAGS] [OPTIONS]

FLAGS:
        --connect-existing    Connect to an existing Firefox instance
    -h, --help                Prints help information
    -v                        Log level verbosity (-v for debug and -vv for
                              trace level)
    -V, --version             Prints version and copying information

OPTIONS:
    -b, --binary <BINARY>           Path to the Firefox binary
        --log <LEVEL>
            Set Gecko log level [values: fatal, error, warn, info, config,
            debug, trace]
        --marionette-port <PORT>
            Port to use to connect to Gecko (default: random free port)
        --host <HOST>
            Host ip to use for WebDriver server (default: 127.0.0.1)
    -p, --port <PORT>
            Port to use for WebDriver server (default: 4444)

Building

geckodriver is written in Rust and you need the Rust toolchain to compile it.

To build the project for release, ensure you do a compilation with optimisations:

% cargo build --release

Or if you want a non-optimised binary for debugging:

% cargo build