remote/doc/PuppeteerVendor.md

   1 Vendoring Puppeteer
   2 ===================
   3
   4 As mentioned in the chapter on [Testing], we run the full [Puppeteer
   5 test suite] on try.  These tests are vendored in central under
   6 _remote/test/puppeteer/_ and we have a script to pull in upstream changes.
   7
   8 We periodically perform a manual two-way sync. Below is an outline of the
   9 process interspersed with some tips.
  10
  11 1. Clone the Puppeteer git repository and checkout the release tag you want
  12    to vendor into mozilla-central.
  13
  14         % git checkout tags/v10.0 -b sync-v10.0
  15
  16 2. Apply any recent changes in `remote/test/puppeteer` to the Puppeteer branch
  17    created above.
  18
  19          You might want to [install the project] at this point and make sure unit
  20          tests pass. Check the project's `package.json` for relevant testing commands.
  21
  22    You should use this as basis for a PR to the Puppeteer project once you are
  23          satisfied that the two-way sync will be successful in mozilla-central. See
  24          their [CONTRIBUTING.md].
  25
  26          Typically, the changes we push to Puppeteer include unskipping newly passing
  27          unit tests for Firefox along with minor fixes to the tests or
  28          to Firefox-specific browser-fetching and launch code.
  29
  30          Be sure to [run tests against both Chromium and Firefox] in the Puppeteer
  31          repo. You can specify your local Firefox build when you do so:
  32
  33                 % BINARY=<path-to-objdir-binary> npm run funit
  34
  35 3. Now back in mozilla-central, you can run the following mach command to
  36          copy over the Puppeteer branch you just prepared. The mach command has
  37          flags to specify a local or remote repository as well as a commit.
  38
  39                 % ./mach remote vendor-puppeteer
  40
  41          By default, this command also installs the newly-pulled Puppeteer package
  42          in order to generate a new `package-lock.json` file for the purpose of
  43          pinning Puppeteer dependencies for our CI. There is a `--no-install` option
  44          if you want to skip this step; for example, if you want to run installation
  45          separately at a later point.
  46
  47 4. Go through the changes under `remote/test/puppeteer/test` and [unskip] any
  48          newly-skipped tests (e.g. change `itFailsFirefox` to `it`).
  49          A mass-change with `awk` might be useful here.
  50
  51          Why do we do this? The Puppeteer team runs their unit tests against Firefox
  52          in their CI with many tests skipped. In contrast, we leave these tests
  53          unskipped in Mozilla CI and track test expectation metadata
  54          in [puppeteer-expected.json] instead.
  55
  56 5. Use `./mach puppeteer-test` (see [Testing]) to run Puppeteer tests against
  57    both Chromium and Firefox in headless mode. Again, only running a subset of
  58          tests against Firefox is fine -- at this point you just want to check that
  59          the typescript compiles and the browser binaries are launched successfully.
  60
  61 6. Next you want to update the test expectation metadata: test results might
  62    have changed, tests may have been renamed, removed or added. The
  63          easiest way to do this is to run the Puppeteer test job on try
  64          (see [Testing]). You will find the new test metadata as an artifact on that
  65          job and you can copy it over into your sync patch if it looks reasonable.
  66
  67          Examine the job logs and makes sure the run didn't get interrupted early
  68          by a crash or a hang, especially if you see a lot of
  69          `TEST-UNEXPECTED-MISSING` in the Treeherder Failure Summary. You might need
  70          to add new test skips or fix some new bug in the unit tests. This is the
  71          fun part.
  72
  73 7. Once you are happy with the metadata and are ready to submit the sync patch
  74    up for review, run the Puppeteer test job on try again with `--rebuild 10`
  75          to check for stability.
  76
  77 [Testing]: ./Testing.html
  78 [Puppeteer test suite]: https://github.com/GoogleChrome/puppeteer/tree/master/test
  79 [re-install the project]: https://github.com/puppeteer/puppeteer/blob/main/CONTRIBUTING.md#getting-code
  80 [run tests against both Chromium and Firefox]: https://github.com/puppeteer/puppeteer/blob/main/test/README.md#running-tests
  81 [puppeteer-expected.json]: https://searchfox.org/mozilla-central/source/remote/test/puppeteer-expected.json
  82 [CONTRIBUTING.md]: https://github.com/puppeteer/puppeteer/blob/main/CONTRIBUTING.md
  83 [unskip]: https://github.com/puppeteer/puppeteer/blob/main/test/README.md#skipping-tests-in-specific-conditions