gecko-dev/testing/geckodriver
James Graham d4e2dbee64 Bug 1373216 - Add mach command for starting geckodriver, r=ato
MozReview-Commit-ID: 8hNAjT5db44

--HG--
extra : rebase_source : 7e97893526c238b7ee466a3f609cb41e76d2a690
2017-06-15 12:47:20 +01:00
..
i686-trusty geckodriver: ci: build i686-pc-windows-gnu in ubuntu trusty container 2016-10-03 22:45:44 +01:00
src Bug 1370510: Implement Fullscreen Window command r=jgraham 2017-06-07 12:42:30 +01:00
.gitignore geckodriver: Add flag parsing and address parsing 2014-10-22 11:30:20 +01:00
.travis.yml Bug 1371707 - Fix Linux x86 packages on Travis for geckodriver; r=whimboo 2017-06-09 16:46:57 +01:00
build.sh geckodriver: ci: log cc compiler when building 2017-04-10 21:23:14 +01:00
Cargo.lock Bug 1369709 - Release geckodriver 0.17.0. r=ato 2017-06-07 20:45:18 +02:00
Cargo.toml Bug 1369709 - Release geckodriver 0.17.0. r=ato 2017-06-07 20:45:18 +02:00
CHANGES.md Bug 1369709 - Release geckodriver 0.17.0. r=ato 2017-06-07 20:45:18 +02:00
ci.sh geckodriver: ci: build i686-pc-windows-gnu in ubuntu trusty container 2016-10-03 22:45:44 +01:00
CONTRIBUTING.md geckodriver: Add Contributing documentation (#368) 2016-12-19 14:59:33 +00:00
ISSUE_TEMPLATE.md geckodriver: Fix typo in issue template (#441) 2017-01-19 21:51:44 +00:00
LICENSE geckodriver: Create LICENSE 2016-01-15 00:00:42 +00:00
mach_commands.py Bug 1373216 - Add mach command for starting geckodriver, r=ato 2017-06-15 12:47:20 +01:00
moz.build Bug 1340637 - Provide build rules for geckodriver; r=jgraham,ted 2017-05-23 14:55:54 +01:00
README.md Bug 1371718 - Recommend Firefox 53 or greater for geckodriver; r=whimboo 2017-06-09 17:24:11 +01:00

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 clients

Selenium users must update to version 3.4 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 53 and greater, 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 was dropped with Firefox 53, geckodriver is not supported on 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. By default, a new profile will be created in the systems temporary folder. The effective profile in use by the WebDriver session is returned to the user in the `moz:profile` capability.
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 systems 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 AdvancedEnvironmental VariablesPath.

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
%

Flags

-b BINARY/--binary BINARY

Path to the Firefox binary to use. By default geckodriver tries to find and use the system installation of Firefox, but that behaviour can be changed by using this option. Note that the binary capability of the moz:firefoxOptions object that is passed when creating a new session will override this option.

On Linux systems it will use the first firefox binary found by searching the PATH environmental variable, which is roughly equivalent to calling whereis(1) and extracting the second column:

% whereis firefox
firefox: /usr/bin/firefox /usr/local/firefox

On macOS, the binary is found by looking for the first firefox-bin binary in the same fashion as on Linux systems. This means it is possible to also use PATH to control where geckodriver should find Firefox on macOS. It will then look for /Applications/Firefox.app.

On Windows systems, geckodriver looks for the system Firefox by scanning the Windows registry.

--connect-existing

Connecting to an existing Firefox instance. The instance must have Marionette enabled.

To enable the Marionette remote protocol you can pass the --marionette flag to Firefox, or (in Firefox 54 or greater) flip the marionette.enabled preference in about:config at runtime.

--host HOST

Host to use for the WebDriver server. Defaults to 127.0.0.1.

--log LEVEL

Set the Gecko and geckodriver log level. Possible values are fatal, error, warn, info, config, debug, and trace.

--marionette-port PORT

Port to use for connecting to the Marionette remote protocol. By default it will pick a free port assigned by the system.

-p PORT/--port PORT

Port to use for the WebDriver server. Defaults to 4444.

A helpful trick is that it is possible to bind to 0 to get the system to assign a free port.

-v[v]

Increases the logging verbosity by to debug level when passing a single -v, or to trace level if -vv is passed. This is analogous to passing --log debug and --log trace, respectively.

Building

geckodriver is written in Rust, a systems programming language from Mozilla. Crucially, it relies on the webdriver crate to provide the HTTPD and do most of the heavy lifting of marshalling the WebDriver protocol. geckodriver translates WebDriver commands, responses, and errors to the Marionette protocol, and acts as a proxy between WebDriver and Marionette.

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