remote/doc/Testing.md

   1 # Testing
   2
   3 The Remote Protocol has unit- and functional tests located under different folders:
   4
   5 * CDP: `remote/cdp/`
   6 * Marionette: `remote/marionette/`.
   7 * Shared Modules: `remote/shared/`
   8 * WebDriver BiDi: `remote/webdriver-bidi/`
   9
  10 You may want to run all the tests under a particular subfolder locally like this:
  11
  12 ```shell
  13 % ./mach test remote
  14 ```
  15
  16 ## Unit tests
  17
  18 Because tests are run in parallel and [xpcshell] itself is quite
  19 chatty, it can sometimes be useful to run the tests in sequence:
  20
  21 ```shell
  22 % ./mach xpcshell-test --sequential remote/cdp/test/unit/test_DomainCache.js
  23 ```
  24
  25 The unit tests will appear as part of the `X` (for _xpcshell_) jobs
  26 on Treeherder.
  27
  28 [xpcshell]: /testing/xpcshell/index.rst
  29
  30 ## Browser Chrome Mochitests
  31
  32 We also have a set of functional browser-chrome mochitests located
  33 under several components, ie. _remote/shared/messagehandler/test/browser_:
  34
  35 ```shell
  36 % ./mach mochitest remote/shared/messagehandler/test/browser/browser_*
  37 ```
  38
  39 The functional tests will appear under the `M` (for _mochitest_)
  40 category in the `remote` jobs on Treeherder.
  41
  42 As the functional tests will sporadically pop up new Firefox
  43 application windows, a helpful tip is to run them in headless
  44 mode:
  45
  46 ```shell
  47 % ./mach mochitest --headless remote/shared/messagehandler/test/browser
  48 ```
  49
  50 The `--headless` flag is equivalent to setting the `MOZ_HEADLESS`
  51 environment variable.  You can additionally use `MOZ_HEADLESS_WIDTH`
  52 and `MOZ_HEADLESS_HEIGHT` to control the dimensions of the virtual
  53 display.
  54
  55 The `add_task()` function used for writing asynchronous tests is
  56 replaced to provide some additional test setup and teardown useful
  57 for writing tests against the Remote Agent and the targets.
  58
  59 There are also specific browser-chrome tests for CDP.
  60
  61 Before such a task is run, the `nsIRemoteAgent` listener is started
  62 and a [CDP client] is connected.  You will use this CDP client for
  63 interacting with the agent just as any other CDP client would.
  64
  65 Also target discovery is getting enabled, which means that targetCreated,
  66 targetDestroyed, and targetInfoChanged events will be received by the client.
  67
  68 The task function you provide in your test will be called with the
  69 three arguments `client`, `CDP`, and `tab`:
  70
  71 * `client` is the connection to the `nsIRemoteAgent` listener,
  72     and it provides the a client CDP API
  73
  74 * `CDP` is the CDP client class
  75
  76 * `tab` is a fresh tab opened for each new test, and is automatically
  77     removed after the test has run
  78
  79 This is what it looks like all put together:
  80
  81 ```javascript
  82 add_task(async function testName({client, CDP, tab}) {
  83   // test tab is implicitly created for us
  84   info("Current URL: " + tab.linkedBrowser.currentURI.spec);
  85
  86   // manually connect to a specific target
  87   const { mainProcessTarget } = RemoteAgent.cdp.targetList;
  88   const target = mainProcessTarget.wsDebuggerURL;
  89   const client = await CDP({ target });
  90
  91   // retrieve the Browser domain, and call getVersion() on it
  92   const { Browser } = client;
  93   const version = await Browser.getVersion();
  94
  95   await client.close();
  96
  97   // tab is implicitly removed
  98 });
  99 ```
 100
 101 You can control the tab creation behavior with the `createTab`
 102 option to `add_task(taskFunction, options)`:
 103
 104 ```javascript
 105 add_task(async function testName({client}) {
 106   // tab is not implicitly created
 107 }, { createTab: false });
 108 ```
 109
 110 If you want to write an asynchronous test _without_ this implicit
 111 setup you may instead use `add_plain_task()`, which works exactly like the
 112 original `add_task()`.
 113
 114 [CDP client]: https://github.com/cyrus-and/chrome-remote-interface
 115
 116 ## Puppeteer tests
 117
 118 In addition to our own Firefox-specific tests, we run the upstream
 119 [Puppeteer test suite] against our implementation to [track progress]
 120 towards achieving full [Puppeteer support] in Firefox. The tests are written
 121 in the behavior-driven testing framework [Mocha].
 122
 123 Puppeteer tests are vendored under _remote/test/puppeteer/_ and are
 124 run locally like this:
 125
 126 ```shell
 127 % ./mach puppeteer-test
 128 ```
 129
 130 You can also run them against Chrome as:
 131
 132 ```shell
 133 % ./mach puppeteer-test --product=chrome
 134 ```
 135
 136 By default the mach command will automatically install Puppeteer but that's
 137 only needed for the very first time, or when a new Puppeteer release has been
 138 vendored in. To skip the install step use the `--no-install` option.
 139
 140 To run only some specific tests from the whole test suite the appropriate
 141 test files have to be updated first. To select specific tests or test
 142 groups within a file define [exclusive tests] by adding the `.only` suffix
 143 like `it.only()` or `describe.only()`.
 144
 145 More customizations for [Mocha] can be found in its own documentation.
 146
 147 Test expectation metadata is collected in _remote/test/puppeteer-expected.json_
 148 via log parsing and a custom Mocha reporter under
 149 _remote/test/puppeteer/json-mocha-reporter.js_
 150
 151 Check the upstream [Puppeteer test suite] documentation for instructions on
 152 how to skip tests, run only one test or a subsuite of tests.
 153
 154 ## Testing on Try
 155
 156 To schedule all the Remote Protocol tests on try, you can use the
 157 `remote-protocol` [try preset]:
 158
 159 ```shell
 160 % ./mach try --preset remote-protocol
 161 ```
 162
 163 But you can also schedule tests by selecting relevant jobs yourself:
 164
 165 ```shell
 166 % ./mach try fuzzy
 167 ```
 168
 169 [Puppeteer test suite]: https://github.com/puppeteer/puppeteer/blob/master/test/README.md
 170 [Puppeteer support]: https://bugzilla.mozilla.org/show_bug.cgi?id=puppeteer
 171 [Mocha]: https://mochajs.org/
 172 [exclusive tests]: https://mochajs.org/#exclusive-tests
 173 [track progress]: https://puppeteer.github.io/ispuppeteerfirefoxready/
 174 [try preset]: /tools/try/presets