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, Puppeteer will be configured to use the WebDriver BiDi protocol. You
 137 can also force Puppeteer to use the CDP protocol with the `--cdp` option:
 138
 139 ```shell
 140 % ./mach puppeteer-test --cdp
 141 ```
 142
 143 By default the mach command will automatically install Puppeteer but that's
 144 only needed for the very first time, or when a new Puppeteer release has been
 145 vendored in. To skip the install step use the `--no-install` option.
 146
 147 To run only some specific tests from the whole test suite the appropriate
 148 test files have to be updated first. To select specific tests or test
 149 groups within a file define [exclusive tests] by adding the `.only` suffix
 150 like `it.only()` or `describe.only()`.
 151
 152 More customizations for [Mocha] can be found in its own documentation.
 153
 154 Test expectation metadata is collected in _remote/test/puppeteer-expected.json_
 155 via log parsing and a custom Mocha reporter under
 156 _remote/test/puppeteer/json-mocha-reporter.js_
 157
 158 Check the upstream [Puppeteer test suite] documentation for instructions on
 159 how to skip tests, run only one test or a subsuite of tests.
 160
 161 ## Testing on Try
 162
 163 To schedule all the Remote Protocol tests on try, you can use the
 164 `remote-protocol` [try preset]:
 165
 166 ```shell
 167 % ./mach try --preset remote-protocol
 168 ```
 169
 170 But you can also schedule tests by selecting relevant jobs yourself:
 171
 172 ```shell
 173 % ./mach try fuzzy
 174 ```
 175
 176 [Puppeteer test suite]: https://github.com/puppeteer/puppeteer/blob/master/test/README.md
 177 [Puppeteer support]: https://bugzilla.mozilla.org/show_bug.cgi?id=puppeteer
 178 [Mocha]: https://mochajs.org/
 179 [exclusive tests]: https://mochajs.org/#exclusive-tests
 180 [track progress]: https://puppeteer.github.io/ispuppeteerfirefoxready/
 181 [try preset]: /tools/try/presets