14 KiB
geckodriver 
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 clients
Selenium users must update to version 3.3.1 or later to use geckodriver. Other clients that follow the W3C WebDriver specification are also supported.
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 52.0.3 and onwards, although generally the more recent the Firefox version, the better the experience as they have more bug fixes and features. Some features will only be available in the most recent Firefox versions, and we strongly advise using the latest Firefox Nightly with geckodriver. 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:
{
"capabilities": {
"alwaysMatch": {
"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 how you invoke geckodriver largely depends on your use case.
Selenium
If you are using geckodriver through Selenium, you must ensure that you have version 3.3.1 or greater. Because geckodriver implements the W3C WebDriver standard and not the same Selenium wire protocol older drivers are using, you may experience incompatibilities and migration problems when making the switch from FirefoxDriver to geckodriver.
Generally speaking, Selenium 3 enabled geckodriver as the default WebDriver implementation for Firefox. With the release of Firefox 47, FirefoxDriver had to be discontinued for its lack of support for the new multi-processing architecture in Gecko.
Selenium client bindings will pick up the geckodriver binary executable
from your system’s PATH environmental variable
unless you override it by setting the webdriver.gecko.driver
Java VM system property:
System.setProperty("webdriver.gecko.driver", "/home/user/bin");
Or by passing it as a flag to the java(1) launcher:
% java -Dwebdriver.gecko.driver=/home/user/bin YourApplication
Your milage with this approach may vary
based on which programming language bindings you are using.
It is in any case generally the case that geckodriver will be picked up
if it is available on the system path.
In a bash compatible shell,
you can make other programs aware of its location
by exporting or setting the PATH variable:
% export PATH=$PATH:/home/user/bin
% whereis geckodriver
geckodriver: /home/user/bin/geckodriver
On Window systems you can change the system path by right-clicking My Computer and choosing Properties. In the dialogue that appears, navigate Advanced → Environmental Variables → Path.
Or in the Windows console window:
$ set PATH=%PATH%;C:\bin\geckodriver
Standalone
Since geckodriver is a separate HTTP server that is a complete remote end implementation of WebDriver, it is possible to avoid using the Selenium remote server if you have no requirements to distribute processes across a matrix of systems.
Given a W3C WebDriver conforming client library (or local end) you may interact with the geckodriver HTTP server as if you were speaking to any Selenium server.
Using curl(1):
% geckodriver &
[1] 16010
% 1491834109194 geckodriver INFO Listening on 127.0.0.1:4444
% curl -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
{"sessionId":"d4605710-5a4e-4d64-a52a-778bb0c31e00","value":{"XULappId":"{ec8030f7-c20a-464f-9b0e-13a3a9e97384}","acceptSslCerts":false,"appBuildId":"20160913030425","browserName":"firefox","browserVersion":"51.0a1","command_id":1,"platform":"LINUX","platformName":"linux","platformVersion":"4.9.0-1-amd64","processId":17474,"proxy":{},"raisesAccessibilityExceptions":false,"rotatable":false,"specificationLevel":0,"takesElementScreenshot":true,"takesScreenshot":true,"version":"51.0a1"}}
% curl -d '{"url": "https://mozilla.org"}' http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
{}
% curl http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
{"value":"https://www.mozilla.org/en-US/"
% curl -X DELETE http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00
{}
% fg
geckodriver
^C
%
Using the Python wdclient library:
import webdriver
with webdriver.Session("127.0.0.1", 4444) as session:
session.url = "https://mozilla.org"
print "The current URL is %s" % session.url
And to run:
% geckodriver &
[1] 16054
% python example.py
1491835308354 geckodriver INFO Listening on 127.0.0.1:4444
The current URL is https://www.mozilla.org/en-US/
% fg
geckodriver
^C
%
You may also see all flags and options available in geckodriver by viewing the help message:
% geckodriver -h
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, a systems programming language from Mozilla. In order to build this program, you will need the Rust compiler toolchain.
To build the project for release, ensure you compile with optimisations to get the best performance:
% cargo build --release
Or if you want a non-optimised binary for debugging:
% cargo build