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