2017-09-09 15:50:57 +00:00
|
|
|
|
geckodriver
|
|
|
|
|
===========
|
2016-01-06 17:43:06 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Proxy for using W3C WebDriver-compatible clients to interact with
|
|
|
|
|
Gecko-based browsers.
|
2015-08-12 14:44:28 +00:00
|
|
|
|
|
2017-07-10 12:41:46 +00:00
|
|
|
|
This program provides the HTTP API described by the [WebDriver protocol]
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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.
|
2015-08-12 14:44:28 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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].
|
2017-07-10 12:41:46 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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.
|
2017-07-10 12:41:46 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[WebDriver protocol]: http://w3c.github.io/webdriver/#protocol
|
|
|
|
|
[Firefox remote protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
|
|
|
|
|
[change log]: https://github.com/mozilla/geckodriver/releases
|
2017-07-10 12:41:46 +00:00
|
|
|
|
[Releases]: https://github.com/mozilla/geckodriver/releases
|
|
|
|
|
[supported platforms]: #supported-firefoxen
|
|
|
|
|
[mozilla-central]: https://hg.mozilla.org/mozilla-central/
|
|
|
|
|
[testing/geckodriver]: https://hg.mozilla.org/mozilla-central/file/tip/testing/geckodriver
|
|
|
|
|
[working with Mozilla source code]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code
|
|
|
|
|
[Testing :: geckodriver]: https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=geckodriver&resolution=---&list_id=13613952
|
2016-06-24 10:41:35 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
Supported clients
|
|
|
|
|
=================
|
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[Selenium] users must update to version 3.11 or later to
|
2017-10-31 21:12:58 +00:00
|
|
|
|
use geckodriver. Other clients that follow the [W3C WebDriver
|
2018-07-20 16:15:00 +00:00
|
|
|
|
specification][WebDriver] are also supported.
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Supported Firefoxen
|
|
|
|
|
===================
|
|
|
|
|
|
2018-06-14 20:11:46 +00:00
|
|
|
|
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 57 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.
|
|
|
|
|
|
|
|
|
|
[implementation status]: https://bugzilla.mozilla.org/showdependencytree.cgi?id=721859&hide_resolved=1
|
|
|
|
|
[Firefox Nightly]: https://whattrainisitnow.com/
|
2017-09-09 15:50:57 +00:00
|
|
|
|
[selenium]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Aselenium
|
|
|
|
|
[remote protocol]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Amarionette
|
|
|
|
|
[specification]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Aspec
|
|
|
|
|
[issue tracker]: https://github.com/mozilla/geckodriver/issues
|
|
|
|
|
[Firefox Nightly]: https://nightly.mozilla.org/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
WebDriver capabilities
|
|
|
|
|
======================
|
|
|
|
|
|
|
|
|
|
geckodriver supports a number of [capabilities]:
|
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[capabilities]: https://w3c.github.io/webdriver/#capabilities
|
2016-12-19 15:00:26 +00:00
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Name
|
|
|
|
|
<th>Type
|
2017-08-04 19:40:58 +00:00
|
|
|
|
<th>Default
|
2016-12-19 15:00:26 +00:00
|
|
|
|
<th>Description
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>acceptInsecureCerts</code>
|
|
|
|
|
<td>boolean
|
2018-06-14 20:13:34 +00:00
|
|
|
|
<td>false
|
|
|
|
|
<td>Indicates the session will not implicitly trust untrusted
|
2016-12-19 15:00:26 +00:00
|
|
|
|
or self-signed TLS certificates on navigation.
|
2018-01-24 20:39:24 +00:00
|
|
|
|
<td>
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</tr>
|
2017-08-04 19:36:24 +00:00
|
|
|
|
|
2017-08-04 19:40:58 +00:00
|
|
|
|
<tr>
|
|
|
|
|
<td><code>pageLoadStrategy</code>
|
|
|
|
|
<td>string
|
2018-07-21 13:29:43 +00:00
|
|
|
|
<td><code>normal</code>
|
2017-08-04 19:40:58 +00:00
|
|
|
|
<td>Defines the page load strategy
|
|
|
|
|
to use for the duration of the session.
|
|
|
|
|
Setting a page load strategy will cause navigation
|
|
|
|
|
to be "<code>eager</code>",
|
|
|
|
|
waiting for the <code>interactive</code> document ready state;
|
|
|
|
|
"<code>normal</code>" (the default),
|
|
|
|
|
waiting for the <code>complete</code> ready state;
|
|
|
|
|
or "<code>none</code>",
|
|
|
|
|
which will return immediately after starting navigation.
|
2018-01-24 20:39:24 +00:00
|
|
|
|
<td>
|
2017-08-04 19:40:58 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
2017-08-04 19:36:24 +00:00
|
|
|
|
<tr>
|
|
|
|
|
<td><code>proxy</code>
|
|
|
|
|
<td><a href=#proxy-object><code>proxy</code></a> object
|
2017-09-09 15:50:57 +00:00
|
|
|
|
<td>
|
2017-08-04 19:36:24 +00:00
|
|
|
|
<td>Sets browser proxy settings.
|
|
|
|
|
</tr>
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</table>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
`proxy` object
|
|
|
|
|
--------------
|
2016-12-19 15:00:26 +00:00
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Name
|
|
|
|
|
<th>Type
|
|
|
|
|
<th>Description
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>proxyType</code>
|
|
|
|
|
<td>string
|
|
|
|
|
<td>Indicates the type of proxy configuration.
|
|
|
|
|
This value must be one of
|
|
|
|
|
<code>pac</code>,
|
2017-08-15 17:28:53 +00:00
|
|
|
|
<code>direct</code>,
|
2016-12-19 15:00:26 +00:00
|
|
|
|
<code>autodetect</code>,
|
|
|
|
|
<code>system</code>,
|
|
|
|
|
or <code>manual</code>.
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>proxyAutoconfigUrl</code>
|
|
|
|
|
<td>string
|
|
|
|
|
<td>Defines the URL for a proxy auto-config file.
|
|
|
|
|
This property should only be set
|
|
|
|
|
when <code>proxyType</code> is <code>pac</code>.
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>ftpProxy</code>
|
|
|
|
|
<td>string
|
2017-08-18 12:55:07 +00:00
|
|
|
|
<td>Defines the proxy hostname with an optional port for FTP traffic.
|
|
|
|
|
This property should only be set when <code>proxyType</code>
|
2016-12-19 15:00:26 +00:00
|
|
|
|
is set to <code>manual</code>.
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>httpProxy</code>
|
|
|
|
|
<td>string
|
2017-08-18 12:55:07 +00:00
|
|
|
|
<td>Defines the proxy hostname with an optional port for HTTP traffic.
|
|
|
|
|
This property should only be set when <code>proxyType</code>
|
2017-10-02 21:16:07 +00:00
|
|
|
|
is set to <code>manual</code>.
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>noProxy</code>
|
|
|
|
|
<td>list
|
|
|
|
|
<td>Lists the addresses for which the proxy should be bypassed.
|
|
|
|
|
This property should only be set when <code>proxyType</code>
|
2017-08-18 12:55:07 +00:00
|
|
|
|
is set to <code>manual</code>.
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>sslProxy</code>
|
|
|
|
|
<td>string
|
2017-08-18 12:55:07 +00:00
|
|
|
|
<td>Defines the proxy hostname with an optional port for encrypted TLS traffic.
|
|
|
|
|
This property should only be set when <code>proxyType</code>
|
|
|
|
|
is set to <code>manual</code>.
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>socksProxy</code>
|
|
|
|
|
<td>string
|
2017-08-18 12:55:07 +00:00
|
|
|
|
<td>Defines the hostname with on optional port for a SOCKS proxy.
|
|
|
|
|
This property should only be set when <code>proxyType</code>
|
|
|
|
|
is set to <code>manual</code>.
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>socksVersion</code>
|
|
|
|
|
<td>number
|
2017-08-18 12:55:07 +00:00
|
|
|
|
<td>Defines the SOCKS proxy version. This property has only to be set
|
|
|
|
|
when <code>proxyType</code> is set to <code>manual</code>.
|
2016-12-19 15:00:26 +00:00
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
Firefox capabilities
|
|
|
|
|
====================
|
2016-08-04 15:51:51 +00:00
|
|
|
|
|
2018-01-24 20:43:27 +00:00
|
|
|
|
geckodriver has a few capabilities that are specific to Firefox.
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-06-14 20:16:34 +00:00
|
|
|
|
|
|
|
|
|
`moz:firefoxOptions`
|
|
|
|
|
--------------------
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
A dictionary used to define options which control how Firefox gets
|
|
|
|
|
started and run. It may contain any of the following fields:
|
2016-08-22 16:18:05 +00:00
|
|
|
|
|
|
|
|
|
<table>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Name
|
|
|
|
|
<th>Type
|
|
|
|
|
<th>Description
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<tr id=capability-binary>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td><code>binary</code>
|
|
|
|
|
<td>string
|
|
|
|
|
<td>Absolute path of the Firefox binary,
|
|
|
|
|
e.g. <code>/usr/bin/firefox</code>
|
|
|
|
|
or <code>/Applications/Firefox.app/Contents/MacOS/firefox</code>,
|
|
|
|
|
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.
|
|
|
|
|
</tr>
|
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<tr id=capability-args>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td><code>args</code>
|
2016-10-05 16:07:01 +00:00
|
|
|
|
<td>array of strings
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<td><p>Command line arguments to pass to the Firefox binary.
|
|
|
|
|
These must include the leading dash (<code>-</code>) where required,
|
|
|
|
|
e.g. <code>["-devtools"]</code>.
|
|
|
|
|
|
|
|
|
|
<p>To have geckodriver pick up an existing profile on the filesystem,
|
|
|
|
|
you may pass <code>["-profile", "/path/to/profile"]</code>.
|
2016-10-05 16:14:31 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<tr id=capability-profile>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td><code>profile</code>
|
|
|
|
|
<td>string
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<td><p>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 <a href=#capability-prefs><code>prefs</code></a> entry
|
|
|
|
|
instead of passing a profile.
|
|
|
|
|
|
|
|
|
|
<p>Profiles are created in the system’s temporary folder.
|
|
|
|
|
This is also where the encoded profile is extracted
|
|
|
|
|
when <code>profile</code> is provided.
|
|
|
|
|
By default, geckodriver will create a new profile in this location.
|
|
|
|
|
|
|
|
|
|
<p>The effective profile in use by the WebDriver session
|
|
|
|
|
is returned to the user in the <code>moz:profile</code> capability
|
|
|
|
|
in the new session response.
|
|
|
|
|
|
|
|
|
|
<p>To have geckodriver pick up an <em>existing profile</em> on the filesystem,
|
|
|
|
|
please set the <a href=#capability-args><code>args</code></a> field
|
|
|
|
|
to <code>{"args": ["-profile", "/path/to/your/profile"]}</code>.
|
2016-10-05 16:14:31 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<tr id=capability-log>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td><code>log</code>
|
2016-10-05 16:06:18 +00:00
|
|
|
|
<td><a href=#log-object><code>log</code></a> object
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<td>To increase the logging verbosity of geckodriver and Firefox,
|
|
|
|
|
you may pass a <a href=#log-object><code>log</code> object</a>
|
|
|
|
|
that may look like <code>{"log": {"level": "trace"}}</code>
|
|
|
|
|
to include all trace-level logs and above.
|
2016-10-05 16:14:31 +00:00
|
|
|
|
</tr>
|
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<tr id=capability-prefs>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td><code>prefs</code>
|
2016-10-05 16:06:18 +00:00
|
|
|
|
<td><a href=#prefs-object><code>prefs</code></a> object
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td>Map of preference name to preference value, which can be a
|
|
|
|
|
string, a boolean or an integer.
|
|
|
|
|
</tr>
|
2016-08-22 16:18:05 +00:00
|
|
|
|
</table>
|
2016-08-04 15:51:51 +00:00
|
|
|
|
|
2018-06-14 20:16:34 +00:00
|
|
|
|
|
|
|
|
|
`moz:useNonSpecCompliantPointerOrigin`
|
|
|
|
|
--------------------------------------
|
2018-01-18 10:22:15 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
A boolean value to indicate how the pointer origin for an action
|
|
|
|
|
command will be calculated.
|
2018-01-18 10:22:15 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
With Firefox 59 the calculation will be based on the requirements by
|
|
|
|
|
the [WebDriver] specification. This means that the pointer origin
|
|
|
|
|
is no longer computed based on the top and left position of the
|
|
|
|
|
referenced element, but on the in-view center point.
|
2018-01-18 10:22:15 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
To temporarily disable the WebDriver conformant behavior use `false`
|
|
|
|
|
as value for this capability.
|
2018-01-18 10:22:15 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
Please note that this capability exists only temporarily, and that
|
|
|
|
|
it will be removed once all Selenium bindings can handle the new behavior.
|
2018-01-18 10:22:15 +00:00
|
|
|
|
|
2018-06-14 20:16:34 +00:00
|
|
|
|
|
|
|
|
|
`moz:webdriverClick`
|
|
|
|
|
--------------------
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
A boolean value to indicate which kind of interactability checks
|
|
|
|
|
to run when performing a click or sending keys to an elements. For
|
|
|
|
|
Firefoxen prior to version 58.0 some legacy code as imported from
|
|
|
|
|
an older version of FirefoxDriver was in use.
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
With Firefox 58 the interactability checks as required by the
|
|
|
|
|
[WebDriver] specification are enabled by default. This means
|
|
|
|
|
geckodriver will additionally check if an element is obscured by
|
|
|
|
|
another when clicking, and if an element is focusable for sending keys.
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
Because of this change in behaviour, we are aware that some extra
|
|
|
|
|
errors could be returned. In most cases the test in question might
|
|
|
|
|
have to be updated so it's conform with the new checks. But if the
|
|
|
|
|
problem is located in geckodriver, then please raise an issue in the
|
|
|
|
|
[issue tracker].
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
To temporarily disable the WebDriver conformant checks use `false`
|
|
|
|
|
as value for this capability.
|
2017-11-03 10:25:21 +00:00
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
Please note that this capability exists only temporarily, and that
|
|
|
|
|
it will be removed once the interactability checks have been stabilized.
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
2018-06-14 20:16:34 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
`log` object
|
|
|
|
|
------------
|
2016-09-07 15:27:59 +00:00
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Name
|
|
|
|
|
<th>Type
|
|
|
|
|
<th>Description
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>level</code>
|
2016-10-05 16:14:31 +00:00
|
|
|
|
<td>string
|
2017-07-10 13:32:36 +00:00
|
|
|
|
<td>Set the level of verbosity of geckodriver and Firefox.
|
2016-09-07 15:27:59 +00:00
|
|
|
|
Available levels are <code>trace</code>,
|
|
|
|
|
<code>debug</code>, <code>config</code>,
|
|
|
|
|
<code>info</code>, <code>warn</code>,
|
|
|
|
|
<code>error</code>, and <code>fatal</code>.
|
2016-11-21 14:01:22 +00:00
|
|
|
|
If left undefined the default is <code>info</code>.
|
2018-05-03 00:18:51 +00:00
|
|
|
|
The value is treated case-insensitively.
|
2016-10-05 16:14:31 +00:00
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
`prefs` object
|
|
|
|
|
--------------
|
2016-10-05 16:14:31 +00:00
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Name
|
|
|
|
|
<th>Type
|
|
|
|
|
<th>Description
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
|
<td><var>preference name</var>
|
|
|
|
|
<td>string, number, boolean
|
|
|
|
|
<td>One entry per preference to override.
|
2016-09-07 15:27:59 +00:00
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
Capabilities example
|
|
|
|
|
====================
|
|
|
|
|
|
|
|
|
|
The following example selects a specific Firefox binary to run with
|
|
|
|
|
a prepared profile from the filesystem in headless mode (available on
|
2018-07-20 15:53:23 +00:00
|
|
|
|
certain systems and recent Firefoxen). It also increases the number
|
|
|
|
|
of IPC processes through a preference and enables more verbose logging.
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"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"
|
|
|
|
|
}
|
2017-04-10 15:29:27 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
2016-12-19 15:00:26 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Usage
|
|
|
|
|
=====
|
|
|
|
|
|
2018-07-20 16:15:00 +00:00
|
|
|
|
geckodriver is an implementation of WebDriver, and WebDriver can
|
|
|
|
|
be used for widely different purposes. How you invoke geckodriver
|
|
|
|
|
largely depends on your use case.
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Selenium
|
|
|
|
|
--------
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
If you are using geckodriver through [Selenium], you must ensure that
|
2018-07-20 15:54:08 +00:00
|
|
|
|
you have version 3.11 or greater. Because geckodriver implements the
|
2017-09-09 15:50:57 +00:00
|
|
|
|
[W3C WebDriver standard][WebDriver] 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][e10s].
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2017-04-10 15:29:27 +00:00
|
|
|
|
Selenium client bindings will pick up the _geckodriver_ binary executable
|
2017-09-09 15:50:57 +00:00
|
|
|
|
from your [system’s `PATH` environmental variable][PATH] unless you
|
|
|
|
|
override it by setting the `webdriver.gecko.driver` [Java VM system
|
|
|
|
|
property]:
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
System.setProperty("webdriver.gecko.driver", "/home/user/bin");
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Or by passing it as a flag to the [java(1)] launcher:
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
|
|
|
|
% java -Dwebdriver.gecko.driver=/home/user/bin YourApplication
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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:
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
|
|
|
|
% export PATH=$PATH:/home/user/bin
|
|
|
|
|
% whereis geckodriver
|
|
|
|
|
geckodriver: /home/user/bin/geckodriver
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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**.
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
|
|
|
|
Or in the Windows console window:
|
|
|
|
|
|
|
|
|
|
$ set PATH=%PATH%;C:\bin\geckodriver
|
|
|
|
|
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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.
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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.
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Using [curl(1)]:
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
|
|
|
|
% geckodriver &
|
|
|
|
|
[1] 16010
|
|
|
|
|
% 1491834109194 geckodriver INFO Listening on 127.0.0.1:4444
|
|
|
|
|
% curl -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
|
2017-04-10 15:33:57 +00:00
|
|
|
|
{"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"}}
|
2017-04-10 15:29:27 +00:00
|
|
|
|
% 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
|
|
|
|
|
%
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Using the Python [wdclient] library:
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
import webdriver
|
2017-04-10 15:29:27 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
with webdriver.Session("127.0.0.1", 4444) as session:
|
|
|
|
|
session.url = "https://mozilla.org"
|
|
|
|
|
print "The current URL is %s" % session.url
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2017-04-10 15:29:27 +00:00
|
|
|
|
And to run:
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2017-04-10 15:29:27 +00:00
|
|
|
|
% 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
|
|
|
|
|
%
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
[Selenium]: http://seleniumhq.org/
|
|
|
|
|
[e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
|
|
|
|
|
[PATH]: https://en.wikipedia.org/wiki/PATH_(variable)
|
|
|
|
|
[Java VM system property]: http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html
|
|
|
|
|
[java(1)]: http://www.manpagez.com/man/1/java/
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[WebDriver]: https://w3c.github.io/webdriver/
|
2017-09-09 15:50:57 +00:00
|
|
|
|
[curl(1)]: http://www.manpagez.com/man/1/curl/
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[wdclient]: https://github.com/web-platform-tests/wpt/tree/master/tools/webdriver
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Flags
|
|
|
|
|
=====
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
#### <code>-b <var>BINARY</var></code>/<code>--binary <var>BINARY</var></code>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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]
|
2017-04-19 20:55:20 +00:00
|
|
|
|
will override this option.
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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:
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
% whereis firefox
|
|
|
|
|
firefox: /usr/bin/firefox /usr/local/firefox
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[creating a new session]: https://w3c.github.io/webdriver/#new-session
|
2017-09-09 15:50:57 +00:00
|
|
|
|
[whereis(1)]: http://www.manpagez.com/man/1/whereis/
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### `--connect-existing`
|
|
|
|
|
|
2018-03-06 13:06:14 +00:00
|
|
|
|
Connect geckodriver to an existing Firefox instance. This means
|
|
|
|
|
geckodriver will abstain from the default of starting a new Firefox
|
|
|
|
|
session.
|
|
|
|
|
|
|
|
|
|
The existing Firefox instance must have [Marionette] enabled.
|
|
|
|
|
To enable the remote protocol in Firefox, you can pass the
|
|
|
|
|
`-marionette` flag. Unless the `marionette.port` preference
|
|
|
|
|
has been user-set, Marionette will listen on port 2828. So when
|
|
|
|
|
using `--connect-existing` it is likely you will also have to use
|
|
|
|
|
[`--marionette-port`] to set the correct port.
|
|
|
|
|
|
|
|
|
|
[`--marionette-port`]: #marionette-port
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### <code>--host <var>HOST</var></code>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Host to use for the WebDriver server. Defaults to 127.0.0.1.
|
|
|
|
|
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
#### <code>--log <var>LEVEL</var></code>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Set the Gecko and geckodriver log level. Possible values are `fatal`,
|
|
|
|
|
`error`, `warn`, `info`, `config`, `debug`, and `trace`.
|
|
|
|
|
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
#### <code>--marionette-port <var>PORT</var></code>
|
|
|
|
|
|
2018-03-06 13:00:37 +00:00
|
|
|
|
Selects the port for geckodriver’s connection to the [Marionette]
|
|
|
|
|
remote protocol.
|
|
|
|
|
|
|
|
|
|
In the default mode where geckodriver starts and manages the Firefox
|
|
|
|
|
process, it will pick a free port assigned by the system and set the
|
|
|
|
|
`marionette.port` preference in the profile.
|
|
|
|
|
|
|
|
|
|
When [`--connect-existing`] is used and the Firefox process is not
|
|
|
|
|
under geckodriver’s control, it will simply connect to <var>PORT</var>.
|
|
|
|
|
|
|
|
|
|
[`--connect-existing`]: #connect-existing
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
#### <code>-p <var>PORT</var></code>/<code>--port <var>PORT</var></code>
|
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Port to use for the WebDriver server. Defaults to 4444.
|
|
|
|
|
|
2018-03-06 13:00:37 +00:00
|
|
|
|
A helpful trick is that it is possible to bind to 0 to get the
|
|
|
|
|
system to atomically assign a free port.
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
|
|
|
|
|
2018-01-24 01:24:51 +00:00
|
|
|
|
#### <code>--jsdebugger</code>
|
|
|
|
|
|
|
|
|
|
Attach [browser toolbox] debugger when Firefox starts. This is
|
|
|
|
|
useful for debugging [Marionette] internals.
|
|
|
|
|
|
|
|
|
|
[browser toolbox]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox
|
|
|
|
|
|
2018-03-06 13:00:37 +00:00
|
|
|
|
|
2017-04-19 20:55:20 +00:00
|
|
|
|
#### <code>-v<var>[v]</var></code>
|
|
|
|
|
|
2018-03-06 13:00:37 +00:00
|
|
|
|
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.
|
2016-12-19 16:30:42 +00:00
|
|
|
|
|
2015-08-12 14:44:28 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
Building
|
|
|
|
|
========
|
2017-04-19 20:55:20 +00:00
|
|
|
|
|
2017-09-09 15:50:57 +00:00
|
|
|
|
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,
|
2017-07-10 13:32:36 +00:00
|
|
|
|
ensure you put this in your [mozconfig]:
|
2015-08-12 14:44:28 +00:00
|
|
|
|
|
2017-07-10 13:32:36 +00:00
|
|
|
|
ac_add_options --enable-geckodriver
|
2016-01-06 17:43:06 +00:00
|
|
|
|
|
2017-12-15 23:27:52 +00:00
|
|
|
|
You build geckodriver with the `./mach build testing/geckodriver`
|
|
|
|
|
command, run tests with `./mach test testing/geckodriver`, and run
|
|
|
|
|
the built executable with `./mach geckodriver -- --other --flags`.
|
2017-12-13 16:11:56 +00:00
|
|
|
|
|
2017-04-19 20:55:20 +00:00
|
|
|
|
[Rust]: https://www.rust-lang.org/
|
|
|
|
|
[Mozilla]: https://www.mozilla.org/en-US/
|
2018-01-24 20:40:06 +00:00
|
|
|
|
[webdriver crate]: https://crates.io/crates/webdriver
|
2018-07-03 16:32:03 +00:00
|
|
|
|
[commands]: https://docs.rs/webdriver/newest/webdriver/command/
|
|
|
|
|
[responses]: https://docs.rs/webdriver/newest/webdriver/response/
|
2018-01-24 20:40:56 +00:00
|
|
|
|
[errors]: https://docs.rs/webdriver/newest/webdriver/error/enum.ErrorStatus.html
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[Marionette protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
|
2018-07-03 16:32:03 +00:00
|
|
|
|
[WebDriver]: https://w3c.github.io/webdriver/
|
2018-07-20 15:53:23 +00:00
|
|
|
|
[Marionette]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/
|
2017-07-10 13:32:36 +00:00
|
|
|
|
[Firefox CI]: https://treeherder.mozilla.org/
|
|
|
|
|
[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
|
2017-09-09 15:50:57 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
[subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
|
2017-12-04 13:33:58 +00:00
|
|
|
|
[archive]: https://groups.google.com/group/mozilla.tools.marionette
|