diff options
Diffstat (limited to 'testing/geckodriver/doc/Profiles.md')
| -rw-r--r-- | testing/geckodriver/doc/Profiles.md | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/testing/geckodriver/doc/Profiles.md b/testing/geckodriver/doc/Profiles.md new file mode 100644 index 0000000000..abad9af730 --- /dev/null +++ b/testing/geckodriver/doc/Profiles.md @@ -0,0 +1,103 @@ +# Profiles + +geckodriver uses [profiles] to instrument Firefox’ behaviour. The +user will usually rely on geckodriver to generate a temporary, +throwaway profile. These profiles are deleted when the WebDriver +session expires. + +In cases where the user needs to use custom, prepared profiles, +geckodriver will make modifications to the profile that ensures +correct behaviour. See [_Automation preferences_] below on the +precedence of user-defined preferences in this case. + +Custom profiles can be provided two different ways: + + 1. by appending `--profile /some/location` to the [`args` capability], + which will instruct geckodriver to use the profile _in-place_; + + 2. or by setting the [`profile` capability] to a Base64-encoded + ZIP of the profile directory. + +Note that geckodriver has a [known bug concerning `--profile`] that +prevents the randomised Marionette port from being passed to +geckodriver. To circumvent this issue, make sure you specify the +port manually using `--marionette-port <port>`. + +The second way is compatible with shipping Firefox profiles across +a network, when for example the geckodriver instance is running on +a remote system. This is the case when using Selenium’s `RemoteWebDriver` +concept, where the WebDriver client and the server are running on +two distinct systems. + +[profiles]: https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data +[_Automation preferences_]: #automation-preferences +[`args` capability]: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions#args_array_of_strings +[`profile` capability]: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions#profile_string +[known bug concerning `--profile`]: https://github.com/mozilla/geckodriver/issues/1058 + +## Default locations for temporary profiles + +When a custom user profile is not provided with the `-profile` +command-line argument geckodriver generates a temporary, throwaway +profile. This is written to the default system temporary folder +and subsequently removed when the WebDriver session expires. + +The default location for temporary profiles depends on the system. +On Unix systems it uses /tmp, and on Windows it uses the Windows +directory. + +The default location can be overridden. On Unix you set the `TMPDIR` +environment variable. On Windows, the following environment variables +are respected, in order: + + 1. `TMP` + 2. `TEMP` + 3. `USERPROFILE` + +It is not necessary to change the temporary directory system-wide. +All you have to do is make sure it gets set for the environment of +the geckodriver process: + + TMPDIR=/some/location ./geckodriver + +## Automation preferences + +As indicated in the introduction, geckodriver configures Firefox +so it is well-behaved in automation environments. It uses a +combination of preferences written to the profile prior to launching +Firefox (1), and a set of recommended preferences set on startup (2). + +These can be perused here: + + 1. [testing/geckodriver/src/prefs.rs](https://searchfox.org/mozilla-central/source/testing/geckodriver/src/prefs.rs) + 2. [remote/components/marionette.js](https://searchfox.org/mozilla-central/source/remote/components/marionette.js) + +As mentioned, these are _recommended_ preferences, and any user-defined +preferences in the [user.js file] or as part of the [`prefs` capability] +take precedence. This means for example that the user can tweak +`browser.startup.page` to override the recommended preference for +starting the browser with a blank page. + +The recommended preferences set at runtime (see 2 above) may also +be disabled entirely by setting `remote.prefs.recommended` starting with Firefox +91. For older versions of Firefox, the preference to use was +`marionette.prefs.recommended`. +This may however cause geckodriver to not behave correctly according +to the WebDriver standard, so it should be used with caution. + +Users should take note that the `marionette.port` preference is +special, and will always be overridden when using geckodriver unless +the `--marionette-port <port>` flag is used specifically to instruct +the Marionette server in Firefox which port to use. + +[user.js file]: http://kb.mozillazine.org/User.js_file +[`prefs` capability]: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions#prefs_preferences_object + +## Temporary profiles not being removed + +It is a known bug that geckodriver in some instances fails to remove +the temporary profile, particularly when the session is not explicitly +deleted or the process gets interrupted. See [geckodriver issue +299] for more information. + +[geckodriver issue 299]: https://github.com/mozilla/geckodriver/issues/299 |