bug 1509033: marionette: add docs about "debugger;" statement; r=me
authorAndreas Tolfsen <ato@sny.no>
Wed, 21 Nov 2018 14:18:29 +0000
changeset 504018 53564c1e12e7294e772c3b19f868b04533f6e2d0
parent 504017 89fa96061247c5b20e9f09fc652cd608fd36c425
child 504019 09abaef41d5e9a532278fc143ae5f6da596e7f92
push id10290
push userffxbld-merge
push dateMon, 03 Dec 2018 16:23:23 +0000
treeherdermozilla-beta@700bed2445e6 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersme
bugs1509033
milestone65.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
bug 1509033: marionette: add docs about "debugger;" statement; r=me
testing/marionette/doc/Debugging.md
--- a/testing/marionette/doc/Debugging.md
+++ b/testing/marionette/doc/Debugging.md
@@ -30,28 +30,44 @@ with using [pdb] in the Python client or
 that is described below.
 
 [pdb]: https://docs.python.org/2/library/pdb.html
 
 
 JavaScript debugger
 -------------------
 
-You can attach a JavaScript debugger to the Marionette server
-through the [Browser Toolbox].  This enables you to introspect and
-set breakpoints in Gecko chrome code, which is a far more powerful
-debuggin technique than using `dump()` or `console.log()`.
+You can attach the [Browser Toolbox] JavaScript debugger to the
+Marionette server using the `--jsdebugger` flag.  This enables you
+to introspect and set breakpoints in Gecko chrome code, which is a
+more powerful debugging technique than using `dump()` or `console.log()`.
 
-The browser toolbox can be opened automatically when running Mn
-tests by passing `--jsdebugger` to the mach command:
+To automatically open the JS debugger for `Mn` tests:
 
 	% ./mach marionette test --jsdebugger
 
-It will prompt you when to start the test run to allow you time to
-set your breakpoints.  It will also prompt you between each test.
+It will prompt you when to start to allow you time to set your
+breakpoints.  It will also prompt you between each test.
+
+You can also use the `debugger;` statement anywhere in chrome code
+to add a breakpoint.  In this example, a breakpoint will be added
+whenever the `WebDriver:GetPageSource` command is called:
+
+	GeckoDriver.prototype.getPageSource = async function() {
+	  debugger;
+	  const win = assert.open(this.getCurrentWindow());
+	  await this._handleUserPrompts();
+	  …
+	}
+
+To not be prompted at the start of the test run or between tests,
+you can set the `marionette.debugging.clicktostart` preference to
+false this way:
+
+	% ./mach marionette test --pref 'marionette.debugging.clicktostart:false' --jsdebugger
 
 For reference, below is the list of preferences that enables the
 chrome debugger for Marionette.  These are all set implicitly when
 `--jsdebugger` is passed to mach.  In non-official builds, which
 are the default when built using `./mach build`, you will find that
 the chrome debugger won’t prompt for connection and will allow
 remote connections.