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