3 ## Redirecting the Gecko output
5 The most common way to debug Marionette, as well as chrome code in
6 general, is to use `dump()` to print a string to stdout. In Firefox,
7 this log output normally ends up in the gecko.log file in your current
8 working directory. With Fennec it can be inspected using `adb logcat`.
10 `mach marionette-test` takes a `--gecko-log` option which lets
11 you redirect this output stream. This is convenient if you want to
12 “merge” the test harness output with the stdout from the browser.
13 Per Unix conventions you can use `-` (dash) to have Firefox write
14 its log to stdout instead of file:
16 % ./mach marionette-test --gecko-log -
18 It is common to use this in conjunction with an option to increase
19 the Marionette log level:
21 % ./mach test --gecko-log - -vv TEST
23 A single `-v` enables debug logging, and a double `-vv` enables
26 This debugging technique can be particularly effective when combined
27 with using [pdb] in the Python client or the JS remote debugger
28 that is described below.
30 [pdb]: https://docs.python.org/3/library/pdb.html
32 ## JavaScript debugger
34 You can attach the [Browser Toolbox] JavaScript debugger to the
35 Marionette server using the `--jsdebugger` flag. This enables you
36 to introspect and set breakpoints in Gecko chrome code, which is a
37 more powerful debugging technique than using `dump()` or `console.log()`.
39 To automatically open the JS debugger for `Mn` tests:
41 % ./mach marionette-test --jsdebugger
43 It will prompt you when to start to allow you time to set your
44 breakpoints. It will also prompt you between each test.
46 You can also use the `debugger;` statement anywhere in chrome code
47 to add a breakpoint. In this example, a breakpoint will be added
48 whenever the `WebDriver:GetPageSource` command is called:
50 GeckoDriver.prototype.getPageSource = async function() {
55 To be prompted at the start of the test run or between tests,
56 you can set the `marionette.debugging.clicktostart` preference to
59 % ./mach marionette-test --setpref='marionette.debugging.clicktostart=true' --jsdebugger
61 For reference, below is the list of preferences that enables the
62 chrome debugger for Marionette. These are all set implicitly when
63 `--jsdebugger` is passed to mach. In non-official builds, which
64 are the default when built using `./mach build`, you will find that
65 the chrome debugger won’t prompt for connection and will allow
68 * `devtools.browsertoolbox.panel` -> `jsdebugger`
70 Selects the Debugger panel by default.
72 * `devtools.chrome.enabled` → true
74 Enables debugging of chrome code.
76 * `devtools.debugger.prompt-connection` → false
78 Controls the remote connection prompt. Note that this will
79 automatically expose your Firefox instance to localhost.
81 * `devtools.debugger.remote-enabled` → true
83 Allows a remote debugger to connect, which is necessary for
84 debugging chrome code.
86 [Browser Toolbox]: /devtools-user/browser_toolbox/index.rst