1Profiles 2======== 3 4geckodriver uses [profiles] to instrument Firefox’ behaviour. The 5user will usually rely on geckodriver to generate a temporary, 6throwaway profile. These profiles are deleted when the WebDriver 7session expires. 8 9In cases where the user needs to use custom, prepared profiles, 10geckodriver will make modifications to the profile that ensures 11correct behaviour. See [_Automation preferences_] below on the 12precedence of user-defined preferences in this case. 13 14Custom profiles can be provided two different ways: 15 16 1. by appending `--profile /some/location` to the [`args` capability], 17 which will instruct geckodriver to use the profile _in-place_; 18 19 2. or by setting the [`profile` capability] to a Base64-encoded 20 ZIP of the profile directory. 21 22Note that geckodriver has a [known bug concerning `--profile`] that 23prevents the randomised Marionette port from being passed to 24geckodriver. To circumvent this issue, make sure you specify the 25port manually using `--marionette-port <port>`. 26 27The second way is compatible with shipping Firefox profiles across 28a network, when for example the geckodriver instance is running on 29a remote system. This is the case when using Selenium’s `RemoteWebDriver` 30concept, where the WebDriver client and the server are running on 31two distinct systems. 32 33[profiles]: https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data 34[_Automation preferences_]: #automation-preferences 35[`args` capability]: ./Capabilities.html#capability-args 36[`profile` capability]: ./Capabilities.html#capability-profile 37[known bug concerning `--profile`]: https://github.com/mozilla/geckodriver/issues/1058 38 39 40Default locations for temporary profiles 41---------------------------------------- 42 43When a custom user profile is not provided with the `-profile` 44command-line argument geckodriver generates a temporary, throwaway 45profile. This is written to the default system temporary folder 46and subsequently removed when the WebDriver session expires. 47 48The default location for temporary profiles depends on the system. 49On Unix systems it uses /tmp, and on Windows it uses the Windows 50directory. 51 52The default location can be overridden. On Unix you set the `TMPDIR` 53environment variable. On Windows, the following environment variables 54are respected, in order: 55 56 1. `TMP` 57 2. `TEMP` 58 3. `USERPROFILE` 59 60It is not necessary to change the temporary directory system-wide. 61All you have to do is make sure it gets set for the environment of 62the geckodriver process: 63 64 % TMPDIR=/some/location ./geckodriver 65 66 67Automation preferences 68---------------------- 69 70As indicated in the introduction, geckodriver configures Firefox 71so it is well-behaved in automation environments. It uses a 72combination of preferences written to the profile prior to launching 73Firefox (1), and a set of recommended preferences set on startup (2). 74 75These can be perused here: 76 77 1. [testing/geckodriver/src/prefs.rs](https://searchfox.org/mozilla-central/source/testing/geckodriver/src/prefs.rs) 78 2. [remote/components/marionette.js](https://searchfox.org/mozilla-central/source/remote/components/marionette.js) 79 80As mentioned, these are _recommended_ preferences, and any user-defined 81preferences in the [user.js file] or as part of the [`prefs` capability] 82take precedence. This means for example that the user can tweak 83`browser.startup.page` to override the recommended preference for 84starting the browser with a blank page. 85 86The recommended preferences set at runtime (see 2 above) may also 87be disabled entirely by setting `remote.prefs.recommended` starting with Firefox 8891. For older versions of Firefox, the preference to use was 89`marionette.prefs.recommended`. 90This may however cause geckodriver to not behave correctly according 91to the WebDriver standard, so it should be used with caution. 92 93Users should take note that the `marionette.port` preference is 94special, and will always be overridden when using geckodriver unless 95the `--marionette-port <port>` flag is used specifically to instruct 96the Marionette server in Firefox which port to use. 97 98[user.js file]: http://kb.mozillazine.org/User.js_file 99[`prefs` capability]: ./Capabilities.html#capability-prefs 100 101 102Temporary profiles not being removed 103------------------------------------ 104 105It is a known bug that geckodriver in some instances fails to remove 106the temporary profile, particularly when the session is not explicitly 107deleted or the process gets interrupted. See [geckodriver issue 108299] for more information. 109 110[geckodriver issue 299]: https://github.com/mozilla/geckodriver/issues/299 111