1The Firefox remote agent is a low-level debugging interface based 2on the CDP protocol. 3 4With it, you can inspect the state and control execution of documents 5running in web content, instrument Gecko in interesting ways, 6simulate user interaction for automation purposes, and debug 7JavaScript execution. 8 9This component provides an experimental and partial implementation 10of a remote devtools interface using the CDP protocol and transport 11layer. 12 13See https://firefox-source-docs.mozilla.org/remote/ for documentation. 14 15It is available in Firefox and is started this way: 16 17 % ./mach run --remote-debugging-port 18 19 20Puppeteer 21========= 22Puppeteer is a Node library which provides a high-level API to control Chrome, 23Chromium, and Firefox over the Chrome DevTools Protocol. Puppeteer runs headless 24by default, but can be configured to run full (non-headless) browsers. 25 26To verify that our implementation of the CDP protocol is valid we do not only 27run xpcshell and browser-chrome mochitests in Firefox CI but also the Puppeteer 28unit tests. 29 30Expectation Data 31---------------- 32 33With the tests coming from upstream, it is not guaranteed that they 34all pass in Gecko-based browsers. For this reason it is necessary to 35provide metadata about the expected results of each test. This is 36provided in a manifest file under `test/puppeteer-expected.json`. 37 38For each test of the Puppeteer unit test suite an equivalent entry will exist 39in this manifest file. By default tests are expected to `PASS`. 40 41Tests that are intermittent may be marked with multiple statuses using 42a list of possibilities e.g. for a test that usually passes, but 43intermittently fails: 44 45 "Page.click should click the button (click.spec.ts)": [ 46 "PASS", "FAIL" 47 ], 48 49Disabling Tests 50--------------- 51 52Tests are disabled by using the manifest file `test/puppeteer-expected.json`. 53For example, if a test is unstable, it can be disabled using `SKIP`: 54 55 "Workers Page.workers (worker.spec.ts)": [ 56 "SKIP" 57 ], 58 59For intermittents it's generally preferable to give the test multiple 60expectations rather than disable it. 61 62Autogenerating Expectation Data 63------------------------------- 64 65After changing some code it may be necessary to update the expectation 66data for the relevant tests. This can of course be done manually, but 67`mach` is able to automate the process: 68 69 mach puppeteer-test --write-results 70 71By default it writes the output to `test/puppeteer-expected.json`. 72 73Given that the unit tests run in Firefox CI only for Linux it is advised to 74download the expectation data (available as artifact) from the TaskCluster job. 75