f9e18f3217
DONTBUILD MozReview-Commit-ID: L2uZuPjA2ig --HG-- extra : rebase_source : 4d1099d2999f619ceea7b96d58d3ec0731d978e5 |
||
---|---|---|
.. | ||
doc | ||
i686-trusty | ||
src | ||
.gitignore | ||
.hgignore | ||
.travis.yml | ||
build.rs | ||
build.sh | ||
Cargo.lock | ||
Cargo.toml | ||
CHANGES.md | ||
ci.sh | ||
CONTRIBUTING.md | ||
ISSUE_TEMPLATE.md | ||
mach_commands.py | ||
moz.build | ||
README.md |
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 Firefox remote 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.
The canonical source code repository for geckodriver now lives in mozilla-central under testing/geckodriver. You can read more about working with Mozilla source code on MDN. This means we do no longer accept pull requests on GitHub. Patches should be uploaded to a bug in the Testing :: GeckoDriver component.
Supported clients
Selenium users must update to version 3.5 or later to use geckodriver. Other clients that follow the W3C WebDriver specification are also supported.
Supported Firefoxen
geckodriver is not yet feature complete. This means that it does 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 Selenium, remote protocol, and specification problems in our issue tracker.
Support is best in Firefox 55 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 in Firefox was dropped with Firefox 53, we do not support this platform.
WebDriver capabilities
geckodriver supports a number of capabilities:
Name | Type | Default | Description |
---|---|---|---|
acceptInsecureCerts
| boolean | Boolean initially set to false, indicating the session will not implicitly trust untrusted or self-signed TLS certificates on navigation. | |
pageLoadStrategy
| string | Defines the page load strategy
to use for the duration of the session.
Setting a page load strategy will cause navigation
to be "eager ",
waiting for the interactive document ready state;
"normal " (the default),
waiting for the complete ready state;
or "none ",
which will return immediately after starting navigation.
| |
proxy
| proxy object
| Sets browser proxy settings. |
proxy
object
Name | Type | Description |
---|---|---|
proxyType
| string | Indicates the type of proxy configuration.
This value must be one of
pac ,
direct ,
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 with an optional port for FTP traffic.
This property should only be set when proxyType
is set to manual .
|
httpProxy
| string | Defines the proxy hostname with an optional port for HTTP traffic.
This property should only be set when proxyType
is set to manual .
|
noProxy
| list | Lists the addresses for which the proxy should be bypassed.
This property should only be set when proxyType
is set to manual .
|
sslProxy
| string | Defines the proxy hostname with an optional port for encrypted TLS traffic.
This property should only be set when proxyType
is set to manual .
|
socksProxy
| string | Defines the hostname with on optional port for a SOCKS proxy.
This property should only be set when proxyType
is set to manual .
|
socksVersion
| number | Defines the SOCKS proxy version. This property has only to be set
when proxyType is set to 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 dash ( To have geckodriver pick up an existing profile on the filesystem,
you may pass |
profile
| string | Base64-encoded ZIP of a 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 Profiles are created in the system’s temporary folder.
This is also where the encoded profile is extracted
when The effective profile in use by the WebDriver session
is returned to the user in the To have geckodriver pick up an existing profile on the filesystem,
please set the |
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
| 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 of geckodriver and Firefox.
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 example
The following example selects a specific Firefox binary to run with a prepared profile from the filesystem in headless mode (available on certain systems and recent Firefoxen). It also increases the number of IPC processes through a preference 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
},
"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.5 and 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
%
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.
--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 atomically 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.
geckodriver is built in the Firefox CI by default but not if you build Firefox locally. To enable building of geckodriver locally, ensure you put this in your mozconfig:
ac_add_options --enable-geckodriver
The geckodriver binary will appear in ${objdir}/dist/bin/geckodriver
alongside firefox-bin.
Contact
The mailing list for geckodriver discussion is tools-marionette@lists.mozilla.org (subscribe, archive).
There is also an IRC channel to talk about using and developing geckodriver in #ateam on irc.mozilla.org.