bug 1603451: remote: document add_task() r=remote-protocol-reviewers,maja_zf,whimboo
authorAndreas Tolfsen <ato@sny.no>
Wed, 18 Dec 2019 12:53:52 +0000
changeset 507746 7b207b360a5d516bb9da536e4e837fb347566ae6
parent 507745 6f014beafb349b8f4469dcd6a4d8fdb291a347bf
child 507747 f61815665e1ff22a340300cd0589082083b52931
push id36932
push useraciure@mozilla.com
push dateThu, 19 Dec 2019 21:52:02 +0000
treeherdermozilla-central@8e1b11b00157 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersremote-protocol-reviewers, maja_zf, whimboo
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 1603451: remote: document add_task() r=remote-protocol-reviewers,maja_zf,whimboo The documentation for the overridden add_task() is quite poor. Document it as to not confuse new developers why it is behaving differently to the default bc add_task(). DONTBUILD Differential Revision: https://phabricator.services.mozilla.com/D57078
--- 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
+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(
 const { RemoteAgent } = ChromeUtils.import(
- * 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
+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 {