|
|
# 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
|
