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