remote/doc/marionette/Debugging.md

   1 # Debugging
   2
   3 ## Redirecting the Gecko output
   4
   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`.
   9
  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:
  15
  16 ```shell
  17 % ./mach marionette-test --gecko-log -
  18 ```
  19
  20 It is common to use this in conjunction with an option to increase
  21 the Marionette log level:
  22
  23 ```shell
  24 % ./mach test --gecko-log - -vv TEST
  25 ```
  26
  27 A single `-v` enables debug logging, and a double `-vv` enables
  28 trace logging.
  29
  30 This debugging technique can be particularly effective when combined
  31 with using [pdb] in the Python client or the JS remote debugger
  32 that is described below.
  33
  34 [pdb]: https://docs.python.org/3/library/pdb.html
  35
  36 ## JavaScript debugger
  37
  38 You can attach the [Browser Toolbox] JavaScript debugger to the
  39 Marionette server using the `--jsdebugger` flag.  This enables you
  40 to introspect and set breakpoints in Gecko chrome code, which is a
  41 more powerful debugging technique than using `dump()` or `console.log()`.
  42
  43 To automatically open the JS debugger for `Mn` tests:
  44
  45 ```shell
  46 % ./mach marionette-test --jsdebugger
  47 ```
  48
  49 It will prompt you when to start to allow you time to set your
  50 breakpoints.  It will also prompt you between each test.
  51
  52 You can also use the `debugger;` statement anywhere in chrome code
  53 to add a breakpoint.  In this example, a breakpoint will be added
  54 whenever the `WebDriver:GetPageSource` command is called:
  55
  56 ```javascript
  57     GeckoDriver.prototype.getPageSource = async function() {
  58       debugger;
  59       …
  60     }
  61 ```
  62
  63 To be prompted at the start of the test run or between tests,
  64 you can set the `marionette.debugging.clicktostart` preference to
  65 `true` this way:
  66
  67 ```shell
  68 % ./mach marionette-test --setpref='marionette.debugging.clicktostart=true' --jsdebugger
  69 ```
  70
  71 For reference, below is the list of preferences that enables the
  72 chrome debugger for Marionette.  These are all set implicitly when
  73 `--jsdebugger` is passed to mach.  In non-official builds, which
  74 are the default when built using `./mach build`, you will find that
  75 the chrome debugger won’t prompt for connection and will allow
  76 remote connections.
  77
  78 * `devtools.browsertoolbox.panel` -> `jsdebugger`
  79
  80   Selects the Debugger panel by default.
  81
  82 * `devtools.chrome.enabled` → true
  83
  84   Enables debugging of chrome code.
  85
  86 * `devtools.debugger.prompt-connection` → false
  87
  88   Controls the remote connection prompt.  Note that this will
  89   automatically expose your Firefox instance to localhost.
  90
  91 * `devtools.debugger.remote-enabled` → true
  92
  93   Allows a remote debugger to connect, which is necessary for
  94   debugging chrome code.
  95
  96 [Browser Toolbox]: /devtools-user/browser_toolbox/index.rst