* readme: expand usage instructions

Expands the usage instructions section of the README to contain actual,
useful information on how to use geckodriver with Selenium and as a
standalone WebDriver server.
This commit is contained in:
Andreas Tolfsen 2017-04-10 16:29:27 +01:00 коммит произвёл David Burns
Родитель 05edecf389
Коммит d322bcfb14
1 изменённых файлов: 123 добавлений и 20 удалений

123
README.md
Просмотреть файл

@ -16,10 +16,11 @@ for a record of all notable changes to the program.
are made available on GitHub are made available on GitHub
on [supported platforms](#supported-firefoxen). on [supported platforms](#supported-firefoxen).
## Supported Clients ## Supported clients
[Selenium](http://docs.seleniumhq.org/) users must update to [version 3.3.1](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-3.3.1) or later to use geckodriver.
[Selenium](http://docs.seleniumhq.org/) users
must update to [version 3.3.1](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-3.3.1)
or later to use geckodriver.
Other clients that follow the [W3C WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) are also supported. Other clients that follow the [W3C WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) are also supported.
## Supported Firefoxen ## Supported Firefoxen
@ -307,6 +308,8 @@ and enable verbose logging:
```js ```js
{ {
"capabilities": {
"alwaysMatch": {
"moz:firefoxOptions": { "moz:firefoxOptions": {
"binary": "/usr/local/firefox/bin/firefox", "binary": "/usr/local/firefox/bin/firefox",
"args": ["--no-remote"], "args": ["--no-remote"],
@ -317,19 +320,116 @@ and enable verbose logging:
"level": "trace" "level": "trace"
} }
} }
}
}
} }
``` ```
## Usage ## Usage
Usage steps are [documented on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver), Usage steps are [documented on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver),
but the gist of it is this: but how you invoke geckodriver largely depends on your use case.
% geckodriver -b /usr/bin/firefox ### Selenium
Or if youre on Mac: If you are using geckodriver through [Selenium](http://seleniumhq.org/),
you must ensure that you have version 3.3.1 or 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.
% geckodriver -b /Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin 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](https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox).
Selenium client bindings will pick up the _geckodriver_ binary executable
from your [systems `PATH` environmental variable](https://en.wikipedia.org/wiki/PATH_(variable))
unless you override it by setting the `webdriver.gecko.driver`
[Java VM system property](http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html):
```java
System.setProperty("webdriver.gecko.driver", "/home/user/bin");
```
Or by passing it as a flag to the [java(1)](http://www.manpagez.com/man/1/java/) 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](https://w3c.github.io/webdriver/webdriver-spec.html),
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)](http://www.manpagez.com/man/1/curl/):
% geckodriver &
[1] 16010
% 1491834109194 geckodriver INFO Listening on 127.0.0.1:4444
% curl -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
{"sessionId":"ad1e71a4-aad8-4c75-b7e6-8d57a7133161","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](https://github.com/w3c/wpt-tools/tree/master/webdriver) library:
```py
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 You may also see all flags and options
available in geckodriver by viewing the help message: available in geckodriver by viewing the help message:
@ -361,11 +461,14 @@ available in geckodriver by viewing the help message:
## Building ## Building
geckodriver is written in [Rust](https://www.rust-lang.org/) geckodriver is written in [Rust](https://www.rust-lang.org/),
and you need the [Rust toolchain](https://rustup.rs/) to compile it. a systems programming language from [Mozilla](https://www.mozilla.org/en-US/).
In order to build this program,
you will need the [Rust compiler toolchain](https://rustup.rs/).
To build the project for release, To build the project for release,
ensure you do a compilation with optimisations: ensure you compile with optimisations
to get the best performance:
% cargo build --release % cargo build --release