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
bugs1603451
milestone73.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 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
remote/doc/Testing.md
remote/test/browser/head.js
--- 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 {