--- a/testing/geckodriver/README.md
+++ b/testing/geckodriver/README.md
@@ -32,36 +32,36 @@ in the [Testing :: GeckoDriver] componen
[Selenium](http://docs.seleniumhq.org/) users
must update to [version 3.4](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-3.4.0)
or later to use geckodriver.
Other clients that follow the [W3C WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) are also supported.
## Supported Firefoxen
-Marionette and geckodriver are not yet feature complete.
-This means that they do not yet offer full conformance
+geckodriver is not yet feature complete.
+This means that it does not yet offer full conformance
with the [WebDriver standard](https://w3c.github.io/webdriver/webdriver-spec.html)
or complete compatibility with [Selenium](http://www.seleniumhq.org/).
You can track the [implementation status](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status)
of the latest [Firefox Nightly](http://whattrainisitnow.com/) on
[MDN](https://developer.mozilla.org/).
We also keep track of known
-[Marionette](https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Amarionette),
[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),
and [specification](https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Aspec)
problems in our
[issue tracker](https://github.com/mozilla/geckodriver/issues).
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](https://nightly.mozilla.org/) with geckodriver.
-Since Windows XP support in Firefox will be dropped with Firefox 53,
+Since Windows XP support in Firefox was dropped with Firefox 53,
we do not support this platform.
## WebDriver capabilities
geckodriver supports a number of
[WebDriver capabilities](https://w3c.github.io/webdriver/webdriver-spec.html#capabilities):
<table>
@@ -70,17 +70,17 @@ geckodriver supports a number of
<th>Name
<th>Type
<th>Description
</tr>
</thead>
<tr>
<td><code>proxy</code>
- <td><a href=#proxy-object><code>proxy</code></a> object
+ <td><a href=#proxy-object><code>proxy</code></a> object
<td>Sets browser proxy settings.
</tr>
<tr>
<td><code>acceptInsecureCerts</code>
<td>boolean
<td>Boolean initially set to false,
indicating the session will not implicitly trust untrusted
@@ -222,55 +222,72 @@ and may contain any of the following fie
<thead>
<tr>
<th>Name
<th>Type
<th>Description
</tr>
</thead>
- <tr>
+ <tr id=capability-binary>
<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>
- <tr>
+ <tr id=capability-args>
<td><code>args</code>
<td>array of strings
- <td>Command line arguments to pass to the Firefox binary.
- These must include the leading <code>--</code> where required
- e.g. <code>["--devtools"]</code>.
+ <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>.
</tr>
- <tr>
+ <tr id=capability-profile>
<td><code>profile</code>
<td>string
- <td>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 system’s temporary folder.
- The effective profile in use by the WebDriver session
- is returned to the user in the `moz:profile` capability.
+ <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>.
</tr>
- <tr>
+ <tr id=capability-log>
<td><code>log</code>
<td><a href=#log-object><code>log</code></a> object
- <td>Logging options for Gecko.
+ <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.
</tr>
- <tr>
+ <tr id=capability-prefs>
<td><code>prefs</code>
<td><a href=#prefs-object><code>prefs</code></a> object
<td>Map of preference name to preference value, which can be a
string, a boolean or an integer.
</tr>
</table>
### `log` object
@@ -282,17 +299,17 @@ and may contain any of the following fie
<th>Type
<th>Description
</tr>
</thead>
<tr>
<td><code>level</code>
<td>string
- <td>Set the level of verbosity in Gecko.
+ <td>Set the level of verbosity of geckodriver and Firefox.
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>.
If left undefined the default is <code>info</code>.
</tr>
</table>
@@ -309,30 +326,31 @@ and may contain any of the following fie
<tr>
<td><var>preference name</var>
<td>string, number, boolean
<td>One entry per preference to override.
</tr>
</table>
-## Capabilities examples
+## Capabilities example
-To select a specific Firefox binary
-and run it with a specific command-line flag,
-set a preference,
-and enable verbose logging:
+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.
```js
{
"capabilities": {
"alwaysMatch": {
"moz:firefoxOptions": {
"binary": "/usr/local/firefox/bin/firefox",
- "args": ["--no-remote"],
+ "args": ["-headless", "-profile", "/path/to/my/profile"],
"prefs": {
"dom.ipc.processCount": 8
},
"log": {
"level": "trace"
}
}
}
@@ -343,17 +361,17 @@ and enable verbose logging:
## Usage
Usage steps are [documented on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver),
but how you invoke geckodriver largely depends on your use case.
### Selenium
If you are using geckodriver through [Selenium](http://seleniumhq.org/),
-you must ensure that you have version 3.3.1 or greater.
+you must ensure that you have version 3.4 and greater.
Because geckodriver implements the [W3C WebDriver standard](https://w3c.github.io/webdriver/webdriver-spec.html)
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
@@ -501,48 +519,46 @@ Port to use for connecting to the Marion
By default it will pick a free port assigned by the system.
#### <code>-p <var>PORT</var></code>/<code>--port <var>PORT</var></code>
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.
+to get the system to atomically assign a free port.
#### <code>-v<var>[v]</var></code>
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:
+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]:
- % cargo build --release
+ ac_add_options --enable-geckodriver
-Or if you want a non-optimised binary for debugging:
-
- % cargo build
+The _geckodriver_ binary will appear in `${objdir}/dist/bin/geckodriver`
+alongside _firefox-bin_.
[Rust]: https://www.rust-lang.org/
[Mozilla]: https://www.mozilla.org/en-US/
[webdriver crate]: https://github.com/mozilla/webdriver-rust
[commands]: https://docs.rs/webdriver/0.25.0/webdriver/command/index.html
[responses]: https://docs.rs/webdriver/0.25.0/webdriver/response/index.html
[errors]: https://docs.rs/webdriver/0.25.0/webdriver/error/enum.ErrorStatus.html
[Marionette protocol]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
[WebDriver]: https://w3c.github.io/webdriver/webdriver-spec.html
[Marionette]: http://searchfox.org/mozilla-central/source/testing/marionette/README
-[Rust compiler toolchain]: https://rustup.rs/
-
+[Firefox CI]: https://treeherder.mozilla.org/
+[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options