103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# Profiles
|
||
|
||
geckodriver uses [profiles] to instrument IceCat’ 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 IceCat 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-icecat-stores-user-data
|
||
[_Automation preferences_]: #automation-preferences
|
||
[`args` capability]: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/icecatOptions#args_array_of_strings
|
||
[`profile` capability]: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/icecatOptions#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 IceCat
|
||
so it is well-behaved in automation environments. It uses a
|
||
combination of preferences written to the profile prior to launching
|
||
IceCat (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 IceCat
|
||
91. For older versions of IceCat, 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 IceCat 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/icecatOptions#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
|