From c25de6081e85fdf91cd44b9487677f19e2abd223 Mon Sep 17 00:00:00 2001 From: Andreas Tolfsen Date: Wed, 12 Sep 2018 14:15:03 +0100 Subject: [PATCH] bug 1490628: geckodriver: move docs to firefox-source-docs.m.o; r=me This moves large parts of the geckodriver README to firefox-source-docs.m.o so that we avoid duplicating content. This move also makes sense in the context that we will not continue to release from GitHub for ever. --- testing/geckodriver/README.md | 643 ++---------------------- testing/geckodriver/doc/Capabilities.md | 199 ++++++++ testing/geckodriver/doc/Flags.md | 93 ++++ testing/geckodriver/doc/Support.md | 38 ++ testing/geckodriver/doc/Usage.md | 111 ++++ testing/geckodriver/doc/index.rst | 25 +- 6 files changed, 491 insertions(+), 618 deletions(-) create mode 100644 testing/geckodriver/doc/Capabilities.md create mode 100644 testing/geckodriver/doc/Flags.md create mode 100644 testing/geckodriver/doc/Support.md create mode 100644 testing/geckodriver/doc/Usage.md diff --git a/testing/geckodriver/README.md b/testing/geckodriver/README.md index 11add2fddf86..4c23aa18876a 100644 --- a/testing/geckodriver/README.md +++ b/testing/geckodriver/README.md @@ -1,7 +1,7 @@ geckodriver =========== -Proxy for using W3C WebDriver-compatible clients to interact with +Proxy for using W3C [WebDriver] compatible clients to interact with Gecko-based browsers. This program provides the HTTP API described by the [WebDriver protocol] @@ -9,632 +9,51 @@ 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]. +geckodriver’s [source code] is made available under the [Mozilla +Public License]. -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. - -[WebDriver protocol]: http://w3c.github.io/webdriver/#protocol +[WebDriver protocol]: https://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 -[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 +[source code]: https://hg.mozilla.org/mozilla-unified/file/tip/testing/geckodriver +[Mozilla Public License]: https://www.mozilla.org/en-US/MPL/2.0/ +[WebDriver]: https://developer.mozilla.org/en-US/docs/Web/WebDriver -Supported clients -================= +Downloads +--------- -[Selenium] users must update to version 3.11 or later to -use geckodriver. Other clients that follow the [W3C WebDriver -specification][WebDriver] are also supported. +* [Releases](https://github.com/mozilla/geckodriver/releases/latest) +* [Change log](https://searchfox.org/mozilla-central/source/testing/geckodriver/CHANGES.md) -Supported Firefoxen -=================== +Documentation +------------- -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]. +* [WebDriver] (work in progress) + * [Commands](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Commands) + * [Errors](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Errors) + * [Types](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Types) -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. +* [Cross browser testing](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing) -[implementation status]: https://bugzilla.mozilla.org/showdependencytree.cgi?id=721859&hide_resolved=1 -[Firefox Nightly]: https://whattrainisitnow.com/ -[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/ +* [Selenium](https://seleniumhq.github.io/docs/) (work in progress) + * [C# API](https://seleniumhq.github.io/selenium/docs/api/dotnet/) + * [JavaScript API](https://seleniumhq.github.io/selenium/docs/api/javascript/) + * [Java API](https://seleniumhq.github.io/selenium/docs/api/java/) + * [Python API](https://seleniumhq.github.io/selenium/docs/api/py/) + * [Ruby API](https://seleniumhq.github.io/selenium/docs/api/rb/) +* [geckodriver usage](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Usage.html) + * [Firefox capabilities](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Capabilities.html) + * [Capabilities example](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Capabilities.html#capabilities-example) + * [Enabling trace logs](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/TraceLogs.html) + * [Analyzing crash data from Firefox](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/CrashReports.html) -WebDriver capabilities -====================== - -geckodriver supports a number of [capabilities]: - -[capabilities]: https://w3c.github.io/webdriver/#capabilities - - - - - - - - - - - - - - - -
Name - Type - Default - Description -
acceptInsecureCerts - boolean - false - Indicates the session will not implicitly trust untrusted - or self-signed TLS certificates on navigation. - -
pageLoadStrategy - string - normal - 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 has a few capabilities that are specific to Firefox. - - -`moz:firefoxOptions` --------------------- - -A dictionary used to define options which control how Firefox gets -started and run. It 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 (-) where required, - e.g. ["-devtools"]. - -

To have geckodriver pick up an existing profile on the filesystem, - you may pass ["-profile", "/path/to/profile"]. -

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 prefs entry - instead of passing a profile. - -

Profiles are created in the system’s temporary folder. - This is also where the encoded profile is extracted - when profile is provided. - By default, geckodriver will create a new profile in this location. - -

The effective profile in use by the WebDriver session - is returned to the user in the moz:profile capability - in the new session response. - -

To have geckodriver pick up an existing profile on the filesystem, - please set the args field - to {"args": ["-profile", "/path/to/your/profile"]}. -

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. -
- - -`moz:useNonSpecCompliantPointerOrigin` --------------------------------------- - -A boolean value to indicate how the pointer origin for an action -command will be calculated. - -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. - -To temporarily disable the WebDriver conformant behavior use `false` -as value for this capability. - -Please note that this capability exists only temporarily, and that -it will be removed once all Selenium bindings can handle the new behavior. - - -`moz:webdriverClick` --------------------- - -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. - -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. - -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]. - -To temporarily disable the WebDriver conformant checks use `false` -as value for this capability. - -Please note that this capability exists only temporarily, and that -it will be removed once the interactability checks have been stabilized. - - -`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. - The value is case-insensitive. -
- - -`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 -===== - -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. - - -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]: - - 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 - % - -[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 - - -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. - -[creating a new session]: https://w3c.github.io/webdriver/#new-session -[whereis(1)]: http://www.manpagez.com/man/1/whereis/ - - -#### `--connect-existing` - -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 - - -#### --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 - -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 PORT. - -[`--connect-existing`]: #connect-existing - - -#### -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. - - -#### --jsdebugger - -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 - - -#### -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]. - -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`. - -[Rust]: https://www.rust-lang.org/ -[Mozilla]: https://www.mozilla.org/en-US/ -[webdriver crate]: https://crates.io/crates/webdriver -[commands]: https://docs.rs/webdriver/newest/webdriver/command/ -[responses]: https://docs.rs/webdriver/newest/webdriver/response/ -[errors]: https://docs.rs/webdriver/newest/webdriver/error/enum.ErrorStatus.html -[Marionette protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html -[WebDriver]: https://w3c.github.io/webdriver/ -[Marionette]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/ -[Firefox CI]: https://treeherder.mozilla.org/ -[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options +* [Contributing](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/index.html#for-developers) Contact -======= +------- The mailing list for geckodriver discussion is tools-marionette@lists.mozilla.org ([subscribe], [archive]). diff --git a/testing/geckodriver/doc/Capabilities.md b/testing/geckodriver/doc/Capabilities.md new file mode 100644 index 000000000000..dd1354d8e8d3 --- /dev/null +++ b/testing/geckodriver/doc/Capabilities.md @@ -0,0 +1,199 @@ +Firefox capabilities +==================== + +geckodriver has a few capabilities that are specific to Firefox. + + +`moz:firefoxOptions` +-------------------- + +A dictionary used to define options which control how Firefox gets +started and run. It 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 (-) where required, + e.g. ["-devtools"]. + +

To have geckodriver pick up an existing profile on the filesystem, + you may pass ["-profile", "/path/to/profile"]. +

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 prefs entry + instead of passing a profile. + +

Profiles are created in the system’s temporary folder. + This is also where the encoded profile is extracted + when profile is provided. + By default, geckodriver will create a new profile in this location. + +

The effective profile in use by the WebDriver session + is returned to the user in the moz:profile capability + in the new session response. + +

To have geckodriver pick up an existing profile on the filesystem, + please set the args field + to {"args": ["-profile", "/path/to/your/profile"]}. +

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. +
+ + +`moz:useNonSpecCompliantPointerOrigin` +-------------------------------------- + +A boolean value to indicate how the pointer origin for an action +command will be calculated. + +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. + +To temporarily disable the WebDriver conformant behavior use `false` +as value for this capability. + +Please note that this capability exists only temporarily, and that +it will be removed once all Selenium bindings can handle the new behavior. + + +`moz:webdriverClick` +-------------------- + +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. + +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. + +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]. + +To temporarily disable the WebDriver conformant checks use `false` +as value for this capability. + +Please note that this capability exists only temporarily, and that +it will be removed once the interactability checks have been stabilized. + + +`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. + The value is treated case-insensitively. +
+ + +`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" + } + } + } + } + } \ No newline at end of file diff --git a/testing/geckodriver/doc/Flags.md b/testing/geckodriver/doc/Flags.md new file mode 100644 index 000000000000..209acf195b4f --- /dev/null +++ b/testing/geckodriver/doc/Flags.md @@ -0,0 +1,93 @@ +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. + +[creating a new session]: https://w3c.github.io/webdriver/#new-session +[whereis(1)]: http://www.manpagez.com/man/1/whereis/ + + +#### `--connect-existing` + +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 + + +#### --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 + +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 PORT. + +[`--connect-existing`]: #connect-existing + + +#### -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. + + +#### --jsdebugger + +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 + + +#### -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. diff --git a/testing/geckodriver/doc/Support.md b/testing/geckodriver/doc/Support.md new file mode 100644 index 000000000000..99b3f4f5a02d --- /dev/null +++ b/testing/geckodriver/doc/Support.md @@ -0,0 +1,38 @@ +Supported platforms +=================== + + +Clients +------- + +[Selenium] users must update to version 3.11 or later to use geckodriver. +Other clients that follow the [W3C WebDriver specification][WebDriver] +are also 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 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. + + +[Selenium]: https://github.com/seleniumhq/selenium +[WebDriver]: https://w3c.github.io/webdriver/ +[implementation status]: https://bugzilla.mozilla.org/showdependencytree.cgi?id=721859&hide_resolved=1 +[Firefox Nightly]: https://whattrainisitnow.com/ +[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/ diff --git a/testing/geckodriver/doc/Usage.md b/testing/geckodriver/doc/Usage.md new file mode 100644 index 000000000000..67b88def0424 --- /dev/null +++ b/testing/geckodriver/doc/Usage.md @@ -0,0 +1,111 @@ +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. + + +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]: + + 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 + % + +[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 diff --git a/testing/geckodriver/doc/index.rst b/testing/geckodriver/doc/index.rst index 0deb2ecade01..4b2c6fdfbff3 100644 --- a/testing/geckodriver/doc/index.rst +++ b/testing/geckodriver/doc/index.rst @@ -2,13 +2,21 @@ geckodriver =========== -geckodriver is a proxy for using W3C WebDriver-compatible clients -to interact with Gecko-based browsers. +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 Marionette remote protocol by acting -as a proxy between the local- and remote ends. +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. + +.. _WebDriver protocol: https://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 +.. _Releases: https://github.com/mozilla/geckodriver/releases For users @@ -16,6 +24,11 @@ For users .. toctree:: :maxdepth: 1 + Support.md + WebDriver capabilities + Capabilities.md + Usage.md + Flags.md TraceLogs.md CrashReports.md