Adding upstream version 124.0.1.upstream/124.0.1

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

1 files changed, 143 insertions, 0 deletions

diff --git a/testing/geckodriver/doc/Usage.md b/testing/geckodriver/doc/Usage.md
new file mode 100644
index 0000000000..ee4ab86f8d
--- /dev/null
+++ b/testing/geckodriver/doc/Usage.md
@@ -0,0 +1,143 @@
+# Usage
+
+geckodriver is an implementation of WebDriver, and WebDriver can
+be used for widely different purposes.  How you invoke geckodriver
+largely depends on your use case.
+
+## Running Firefox in a container-based package
+
+When Firefox is packaged inside a container (e.g. [Snap], [Flatpak]), it may
+see a different filesystem to the host. This can affect access to the generated
+profile directory, which may result in a hang when starting Firefox.
+
+This is known to affect launching the default Firefox shipped with Ubuntu 22.04+.
+
+There are several workarounds available for this problem:
+
+- Do not use container-packaged Firefox builds with geckodriver. Instead
+download a Firefox release from <https://download.mozilla.org/?product=firefox-latest&os=linux>
+and a geckodriver release from <https://github.com/mozilla/geckodriver/releases>.
+
+- Use a geckodriver that runs in the same container filesystem as the Firefox
+package. For example on Ubuntu `/snap/bin/geckodriver` will work with the
+default Firefox.
+
+- Set the `--profile-root` command line option to write the profile to a
+directory accessible to both Firefox and geckodriver, for example a non-hidden
+directory under `$HOME`.
+
+[Flatpak]: https://flatpak.org/
+[Snap]: https://ubuntu.com/core/services/guide/snaps-intro
+
+## Selenium
+
+If you are using geckodriver through [Selenium], you must ensure that
+you have version 3.11 or greater.  Because geckodriver implements the
+[W3C WebDriver standard][WebDriver] and not the same Selenium wire
+protocol older drivers are using, you may experience incompatibilities
+and migration problems when making the switch from FirefoxDriver to
+geckodriver.
+
+Generally speaking, Selenium 3 enabled geckodriver as the default
+WebDriver implementation for Firefox.  With the release of Firefox 47,
+FirefoxDriver had to be discontinued for its lack of support for the
+[new multi-processing architecture in Gecko][e10s].
+
+Selenium client bindings will pick up the _geckodriver_ binary executable
+from your [system’s `PATH` environmental variable][PATH] unless you
+override it by setting the `webdriver.gecko.driver` [Java VM system
+property]:
+
+```java
+System.setProperty("webdriver.gecko.driver", "/home/user/bin");
+```
+
+Or by passing it as a flag to the [java(1)] launcher:
+
+```shell
+% java -Dwebdriver.gecko.driver=/home/user/bin YourApplication
+```
+
+Your mileage with this approach may vary based on which programming
+language bindings you are using.  It is in any case generally the case
+that geckodriver will be picked up if it is available on the system path.
+In a bash compatible shell, you can make other programs aware of its
+location by exporting or setting the `PATH` variable:
+
+```shell
+% export PATH=$PATH:/home/user/bin
+% whereis geckodriver
+geckodriver: /home/user/bin/geckodriver
+```
+
+On Window systems you can change the system path by right-clicking **My
+Computer** and choosing **Properties**.  In the dialogue that appears,
+navigate **Advanced** → **Environmental Variables** → **Path**.
+
+Or in the Windows console window:
+
+```shell
+% set PATH=%PATH%;C:\bin\geckodriver
+```
+
+## Standalone
+
+Since geckodriver is a separate HTTP server that is a complete remote end
+implementation of [WebDriver], it is possible to avoid using the Selenium
+remote server if you have no requirements to distribute processes across
+a matrix of systems.
+
+Given a W3C WebDriver conforming client library (or _local end_) you
+may interact with the geckodriver HTTP server as if you were speaking
+to any Selenium server.
+
+Using [curl(1)]:
+
+```shell
+% geckodriver &
+[1] 16010
+% 1491834109194   geckodriver     INFO    Listening on 127.0.0.1:4444
+% curl -H 'Content-Type: application/json' -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
+{"value":{"sessionId":"d4605710-5a4e-4d64-a52a-778bb0c31e00","capabilities":{"acceptInsecureCerts":true,[...]}}}
+% curl -H 'Content-Type: application/json' -d '{"url": "https://mozilla.org"}' http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
+{}
+% curl http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
+{"value":"https://www.mozilla.org/en-US/"
+% curl -X DELETE http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00
+{}
+% fg
+geckodriver
+^C
+```
+
+Using the Python [wdclient] library:
+
+```python
+import webdriver
+
+with webdriver.Session("127.0.0.1", 4444) as session:
+    session.url = "https://mozilla.org"
+    print "The current URL is %s" % session.url
+```
+
+And to run:
+
+```shell
+% geckodriver &
+[1] 16054
+% python example.py
+1491835308354   geckodriver     INFO    Listening on 127.0.0.1:4444
+The current URL is https://www.mozilla.org/en-US/
+% fg
+geckodriver
+^C
+```
+
+[Selenium]: http://seleniumhq.org/
+[e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
+[PATH]: https://en.wikipedia.org/wiki/PATH_(variable)
+[Java VM system property]: http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html
+[java(1)]: http://www.manpagez.com/man/1/java/
+[WebDriver]: https://w3c.github.io/webdriver/
+[curl(1)]: http://www.manpagez.com/man/1/curl/
+[wdclient]: https://github.com/web-platform-tests/wpt/tree/master/tools/webdriver