--- a/remote/doc/Testing.md
+++ b/remote/doc/Testing.md
@@ -40,18 +40,70 @@ mode]:
 
 	% ./mach mochitest --headless remote/test/browser
 
 The `--headless` flag is equivalent to setting the `MOZ_HEADLESS`
 environment variable.  You can additionally use `MOZ_HEADLESS_WIDTH`
 and `MOZ_HEADLESS_HEIGHT` to control the dimensions of the virtual
 display.
 
+The `add_task()` function used for writing [asynchronous tests] is
+replaced to provide some additional test setup and teardown useful
+for writing tests against the remote agent and the targets.
+
+Before the task is run, the `nsIRemoteAgent` listener is started
+and a [CDP client] is connected.  You will use this CDP client for
+interacting with the agent just as any other CDP client would.
+
+The task function you provide in your test will be called with the
+three arguments `client`, `CDP`, and `tab`:
+
+  - `client` is the connection to the `nsIRemoteAgent` listener,
+    and it provides the a client CDP API
+
+  - `CDP` is the CDP client class
+
+  - `tab` is a fresh tab opened for each new test, and is automatically
+    removed after the test has run
+
+This is what it looks like all put together:
+
+	add_task(async function testName(client, CDP, tab) {
+	  // test tab is implicitly created for us
+	  info("Current URL: " + tab.linkedBrowser.currentURI.spec);
+
+	  // manually connect to a specific target
+	  const { mainProcessTarget } = RemoteAgent.targets;
+	  const target = mainProcessTarget.wsDebuggerURL;
+	  const client = await CDP({ target });
+
+	  // retrieve the Browser domain, and call getVersion() on it
+	  const { Browser } = client;
+	  const version = await Browser.getVersion();
+
+           await client.close();
+
+	  // tab is implicitly removed
+	});
+
+You can control the tab creation behaviour with the `createTab`
+option to `add_task(taskFunction, options)`:
+
+	add_task(async function testName(client) {
+	  // tab is not implicitly created
+	}, { createTab: false });
+
+If you want to write an asynchronous test _without_ this implicit
+setup you may instead use `add_plain_task()`, which works exactly like the
+original `add_task()`.
+
 [browser chrome]: https://developer.mozilla.org/en-US/docs/Mozilla/Browser_chrome_tests
 [headless mode]: https://developer.mozilla.org/en-US/Firefox/Headless_mode
+[asynchronous tests]: https://developer.mozilla.org/en-US/docs/Mozilla/Browser_chrome_tests#Test_functions
+[CDP client]: https://github.com/cyrus-and/chrome-remote-interface
 
 
 Puppeteer tests
 ---------------
 
 In addition to our own Firefox-specific tests, we run the upstream
 [Puppeteer test suite] against our implementation to track progress
 towards achieving full [Puppeteer support] in Firefox.

--- a/remote/test/browser/head.js
+++ b/remote/test/browser/head.js
@@ -7,21 +7,37 @@ const { OS } = ChromeUtils.import("resou
 
 const { RemoteAgentError } = ChromeUtils.import(
   "chrome://remote/content/Error.jsm"
 );
 const { RemoteAgent } = ChromeUtils.import(
   "chrome://remote/content/RemoteAgent.jsm"
 );
 
-/**
- * Override `add_task` in order to translate chrome-remote-interface exceptions
- * into something that logs better errors on stdout
- */
+/*
+add_task() is overriden to setup and teardown a test environment
+making it easier to  write browser-chrome tests for the remote
+debugger.
+
+Before the task is run, the nsIRemoteAgent listener is started and
+a CDP client is connected to it.  A new tab is also added.  These
+three things are exposed to the provided task like this:
+
+	add_task(async function testName(client, CDP, tab) {
+	  // client is an instance of the CDP class
+	  // CDP is ./chrome-remote-interface.js
+	  // tab is a fresh tab, destroyed after the test
+	});
+
+add_plain_task() may be used to write test tasks without the implicit
+setup and teardown described above.
+*/
+
 const add_plain_task = add_task.bind(this);
+
 this.add_task = function(taskFn, opts = {}) {
   const { createTab = true } = opts;
   add_plain_task(async function() {
     let client;
     await RemoteAgent.listen(Services.io.newURI("http://localhost:9222"));
     info("CDP server started");
 
     try {