Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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