diff options
Diffstat (limited to '')
| -rw-r--r-- | testing/geckodriver/doc/Usage.md | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/testing/geckodriver/doc/Usage.md b/testing/geckodriver/doc/Usage.md new file mode 100644 index 0000000000..ee4ab86f8d --- /dev/null +++ b/testing/geckodriver/doc/Usage.md @@ -0,0 +1,143 @@ +# Usage + +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. + +## Running Firefox in a container-based package + +When Firefox is packaged inside a container (e.g. [Snap], [Flatpak]), it may +see a different filesystem to the host. This can affect access to the generated +profile directory, which may result in a hang when starting Firefox. + +This is known to affect launching the default Firefox shipped with Ubuntu 22.04+. + +There are several workarounds available for this problem: + +- Do not use container-packaged Firefox builds with geckodriver. Instead +download a Firefox release from <https://download.mozilla.org/?product=firefox-latest&os=linux> +and a geckodriver release from <https://github.com/mozilla/geckodriver/releases>. + +- Use a geckodriver that runs in the same container filesystem as the Firefox +package. For example on Ubuntu `/snap/bin/geckodriver` will work with the +default Firefox. + +- Set the `--profile-root` command line option to write the profile to a +directory accessible to both Firefox and geckodriver, for example a non-hidden +directory under `$HOME`. + +[Flatpak]: https://flatpak.org/ +[Snap]: https://ubuntu.com/core/services/guide/snaps-intro + +## Selenium + +If you are using geckodriver through [Selenium], you must ensure that +you have version 3.11 or greater. Because geckodriver implements the +[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]. + +Selenium client bindings will pick up the _geckodriver_ binary executable +from your [system’s `PATH` environmental variable][PATH] unless you +override it by setting the `webdriver.gecko.driver` [Java VM system +property]: + +```java +System.setProperty("webdriver.gecko.driver", "/home/user/bin"); +``` + +Or by passing it as a flag to the [java(1)] launcher: + +```shell +% java -Dwebdriver.gecko.driver=/home/user/bin YourApplication +``` + +Your mileage 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: + +```shell +% 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: + +```shell +% 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)]: + +```shell +% geckodriver & +[1] 16010 +% 1491834109194 geckodriver INFO Listening on 127.0.0.1:4444 +% curl -H 'Content-Type: application/json' -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session +{"value":{"sessionId":"d4605710-5a4e-4d64-a52a-778bb0c31e00","capabilities":{"acceptInsecureCerts":true,[...]}}} +% curl -H 'Content-Type: application/json' -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: + +```python +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: + +```shell +% 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 +``` + +[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/ +[WebDriver]: https://w3c.github.io/webdriver/ +[curl(1)]: http://www.manpagez.com/man/1/curl/ +[wdclient]: https://github.com/web-platform-tests/wpt/tree/master/tools/webdriver |