mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-09 06:22:08 +00:00
Bug 1406965 - Add docs on enabling trace logs. r=automatedtester
DONTBUILD MozReview-Commit-ID: L2uZuPjA2ig --HG-- extra : rebase_source : 4d1099d2999f619ceea7b96d58d3ec0731d978e5
This commit is contained in:
Andreas Tolfsen
parent
f1daedfa92
commit
f9e18f3217
159
testing/geckodriver/doc/TraceLogs.md
Normal file
159
testing/geckodriver/doc/TraceLogs.md
Normal file
@ -0,0 +1,159 @@
|
||||
Enabling trace logs
|
||||
===================
|
||||
|
||||
geckodriver provides different bands of logs for different audiences.
|
||||
The most important log entries are shown to everyone by default,
|
||||
and these include which port geckodriver provides the WebDriver
|
||||
API on, as well as informative warnings, errors, and fatal exceptions.
|
||||
|
||||
The different log bands are, in ascending bandwidth:
|
||||
|
||||
1. `fatal` is reserved for exceptional circumstances when geckodriver
|
||||
or Firefox cannot recover. This usually entails that either
|
||||
one or both of the processes will exit.
|
||||
|
||||
2. `error` messages are mistakes in the program code which it is
|
||||
possible to recover from.
|
||||
|
||||
3. `warn` shows warnings of more informative nature that are not
|
||||
necessarily problems in geckodriver. This could for example happen
|
||||
if you use the legacy `desiredCapabilities`/`requiredCapabilities`
|
||||
objects instead of the new `alwaysMatch`/`firstMatch` structures.
|
||||
|
||||
4. `info` (default) contains information about which port geckodriver
|
||||
binds to, but also all messages from the lower-bandwidth levels
|
||||
listed above.
|
||||
|
||||
5. `config` additionally shows the negotiated capabilities after
|
||||
matching the `alwaysMatch` capabilities with the sequence of
|
||||
`firstMatch` capabilities.
|
||||
|
||||
6. `debug` is reserved for information that is useful when programming.
|
||||
|
||||
7. `trace`, where in addition to itself, all previous levels
|
||||
are included. The trace level shows all HTTP requests received
|
||||
by geckodriver, packets sent to and from the remote protocol in
|
||||
Firefox, and responses sent back to your client.
|
||||
|
||||
In other words this means that the configured level will coalesce
|
||||
entries from all lower bands including itself. If you set the log
|
||||
level to `error`, you will get log entries for both `fatal` and `error`.
|
||||
Similarly for `trace`, you will get all the logs that are offered.
|
||||
|
||||
To help debug a problem with geckodriver or Firefox, the trace-level
|
||||
output is vital to understand what is going on. This is why we ask
|
||||
that trace logs are included when filing bugs gainst geckodriver.
|
||||
It is only under very special circumstances that a trace log is
|
||||
not needed, so you will normally find that our first action when
|
||||
triaging your issue will be to ask you to include one. Do yourself
|
||||
and us a favour and provide a trace-level log right away.
|
||||
|
||||
To silence geckodriver altogether you may for example either redirect
|
||||
all output to append to some log files:
|
||||
|
||||
% geckodriver >>geckodriver.log 2>>geckodriver.err.log
|
||||
|
||||
Or a black hole somewhere:
|
||||
|
||||
% geckodriver >/dev/null 2>&1
|
||||
|
||||
The log level set for geckodriver is propagated to the Marionette
|
||||
logger in Firefox. Marionette is the remote protocol that geckodriver
|
||||
uses to implement WebDriver. This means enabling trace logs for
|
||||
geckodriver will also implicitly enable them for Marionette.
|
||||
|
||||
The log level is set in different ways. Either by using the
|
||||
`--log <LEVEL>` option, where `LEVEL` is one of the log levels
|
||||
from the list above, or by using the `-v` (for debug) or `-vv`
|
||||
(for trace) shorthands. For example, the following command will
|
||||
enable trace logs for both geckodriver and Marionette:
|
||||
|
||||
% geckodriver -vv
|
||||
|
||||
The second way of setting the log level is through capabilities.
|
||||
geckodriver accepts a Mozila-specific configuration object
|
||||
in [`moz:firefoxOptions`]. This JSON Object, which is further
|
||||
described in the [README] can hold Firefox-specific configuration,
|
||||
such as which Firefox binary to use, additional preferences to set,
|
||||
and of course which log level to use.
|
||||
|
||||
[`moz:firefoxOptions`]: ../README.md#firefox-capabilities
|
||||
[README]: ../README.md
|
||||
|
||||
Each client has its own way of specifying capabilities, and some clients
|
||||
include “helpers” for providing browser-specific configuration.
|
||||
It is often advisable to use these helpers instead of encoding the
|
||||
JSON Object yourself because it can be difficult to get the exact
|
||||
details right, but if you choose to, it should look like this:
|
||||
|
||||
{"moz:firefoxOptions": {"log": {"level": "trace"}}}
|
||||
|
||||
Note that most known WebDriver clients, such as those provided by
|
||||
the Selenium project, do not expose a way to actually _see_ the logs
|
||||
unless you redirect the log output to a particular file (using the
|
||||
method shown above) or let the client “inherit” geckodriver’s
|
||||
output, for example by redirecting the stdout and stderr streams to
|
||||
its own. The notable exceptions are the Python and Ruby bindings,
|
||||
which surface geckodriver logs in a remarkable easy and efficient way.
|
||||
|
||||
See the client-specific documentation below for the most idiomatic
|
||||
way to enable trace logs in your language. We want to expand this
|
||||
documentation to cover all the best known clients people use with
|
||||
geckodriver. If you find your language missing, please consider
|
||||
[submitting a patch].
|
||||
|
||||
[submitting a patch]: ../CONTRIBUTING.md
|
||||
|
||||
|
||||
Python
|
||||
------
|
||||
|
||||
The Selenium [Python client] comes with an
|
||||
[`selenium.webdriver.firefox.options.Options`] helper that can
|
||||
be used programmatically to construct the [`moz:firefoxOptions`]
|
||||
capabilities object:
|
||||
|
||||
from selenium.webdriver import Firefox
|
||||
from selenium.webdriver.firefox.options import Options
|
||||
|
||||
opts = Options()
|
||||
opts.log.level = "trace"
|
||||
driver = Firefox(firefox_options=opts)
|
||||
|
||||
The log output is stored in a file called _geckodriver.log_ in your
|
||||
script’s current working directory.
|
||||
|
||||
[Python client]: https://selenium-python.readthedocs.io/
|
||||
[`selenium.webdriver.firefox.options.Options`]: https://github.com/SeleniumHQ/selenium/blob/master/py/selenium/webdriver/firefox/options.py
|
||||
|
||||
|
||||
Ruby
|
||||
----
|
||||
|
||||
The Selenium [Ruby client] comes with an [`Options`] helper to
|
||||
generate the correct [`moz:firefoxOptions`] capabilities object:
|
||||
|
||||
opts = Selenium::WebDriver::Firefox::Options.new(log_level: :trace)
|
||||
driver = Selenium::WebDriver.for :firefox, options: opts
|
||||
|
||||
To show the logs, set the `DEBUG=1` output variable or start your
|
||||
Ruby interpreter with the `-d` flag.
|
||||
|
||||
[Ruby client]: http://seleniumhq.github.io/selenium/docs/api/rb/
|
||||
[`Options`]: http://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/Firefox/Options.html
|
||||
|
||||
|
||||
Java
|
||||
----
|
||||
|
||||
The Selenium [Java client] also comes with
|
||||
a [`org.openqa.selenium.firefox.FirefoxOptions`] helper for
|
||||
constructing the [`moz:firefoxOptions`] capabilities object:
|
||||
|
||||
FirefoxOptions opts = new FirefoxOptions().setLogLevel(Level.ALL);
|
||||
WebDriver driver = new FirefoxDriver(opts);
|
||||
|
||||
The log output is helpfully propagated to stdout.
|
||||
|
||||
[Java client]: https://seleniumhq.github.io/selenium/docs/api/java/
|
||||
[`org.openqa.selenium.firefox.FirefoxOptions`]: https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/firefox/FirefoxOptions.html
|
||||
Loading…
Reference in New Issue
Block a user