Document the new JS APIs.

Also update the pubspec and changelog.

Author: nex3

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.12.16
+
+* Allow tools to interact with browser debuggers using the JSON reporter.
+
 ## 0.12.15+12
 
 * Fix a race condition that could cause the runner to stall for up to three

doc/json_reporter.md

@@ -440,3 +440,33 @@ class Metadata {
 ```
 
 The metadata class is deprecated and should not be used.
+
+## Remote Debugger APIs
+
+When running browser tests with `--pause-after-load`, the test package embeds a
+few APIs in the JavaScript context of the host page. These allow tools to
+control the debugging process in the same way a user might do from the command
+line. They can be accessed by connecting to the remote debugger using the
+[`DebugEvent.remoteDebugger`](#DebugEvent) URL.
+
+All APIs are defined as methods on the top-level `dartTest` object. The
+following methods are available:
+
+### `resume()`
+
+Calling `resume()` when the test runner is paused causes it to resume running
+tests. If the test runner is not paused, it won't do anything. When
+`--pause-after-load` is passed, the test runner will pause after loading each
+suite but before any tests are run.
+
+This gives external tools a chance to use the remote debugger protocol to set
+breakpoints before tests have begun executing. They can start the test runner
+with `--pause-after-load`, connect to the remote debugger using the
+[`DebugEvent.remoteDebugger`](#DebugEvent) URL, set breakpoints, then call
+`dartTest.resume()` in the host frame when they're finished.
+
+### `restartCurrent()`
+
+Calling `restartCurrent()` when the test runner is running a test causes it to
+re-run that test once it completes its current run. It's intended to be called
+when the browser is paused, as at a breakpoint.

pubspec.yaml

@@ -1,5 +1,5 @@
 name: test
-version: 0.12.16-dev
+version: 0.12.16
 author: Dart Team <[email protected]>
 description: A library for writing dart unit tests.
 homepage: https://github.com/dart-lang/test