remote/doc/PuppeteerVendor.md

   1 # Vendoring Puppeteer
   2
   3 As mentioned in the chapter on [Testing], we run the full [Puppeteer
   4 test suite] on try.  These tests are vendored in central under
   5 _remote/test/puppeteer/_ and we have a script to pull in upstream changes.
   6
   7 We periodically perform a manual two-way sync. Below is an outline of the
   8 process interspersed with some tips.
   9
  10 ## Check for not-yet upstreamed changes
  11
  12 Before vendoring a new Puppeteer release make sure that there are no Puppeteer
  13 specific changes in mozilla-central repository that haven't been upstreamed yet
  14 since the last vendor happened. Run one of the following commands and check the
  15 listed bugs or related upstream code to verify:
  16
  17 ```shell
  18 % hg log remote/test/puppeteer
  19 % git log remote/test/puppeteer
  20 ```
  21
  22 If an upstream pull request is needed please see their [contributing.md].
  23 Typically, the changes we push to Puppeteer include unskipping newly passing
  24 unit tests for Firefox along with minor fixes to the tests or
  25 to Firefox-specific browser-fetching and launch code.
  26
  27 Be sure to [run tests against both Chromium and Firefox] in the Puppeteer
  28 repo. You can specify your local Firefox build when you do so:
  29
  30 ```shell
  31 % BINARY=<path-to-objdir-binary> npm run test:firefox
  32 % BINARY=<path-to-objdir-binary> npm run test:firefox:bidi
  33 ```
  34
  35 ## Prepare the Puppeteer Repository
  36
  37 Clone the Puppeteer git repository and checkout the release tag you want
  38 to vendor into mozilla-central.
  39
  40 ```shell
  41 % git checkout tags/puppeteer-%version%
  42 ```
  43
  44 You might want to [install the project] at this point and make sure unit tests pass.
  45 Check the project's `package.json` for relevant testing commands.
  46
  47 ## Update the Puppeteer code in mozilla-central
  48
  49 You can run the following mach command to copy over the Puppeteer branch you
  50 just prepared. The mach command has flags to specify a local or remote
  51 repository as well as a commit:
  52
  53 ```shell
  54 % ./mach remote vendor-puppeteer --commitish puppeteer-%version% [--repository %path%]
  55 ```
  56
  57 By default, this command also installs the newly-pulled Puppeteer package in
  58 order to generate a new `package-lock.json` file for the purpose of pinning
  59 Puppeteer dependencies for our CI. There is a `--no-install` option if you want
  60 to skip this step; for example, if you want to run installation separately at
  61 a later point.
  62
  63 Validate that newly created files and folders are required to be tracked by
  64 version control. If that is not the case then update both the top-level
  65 `.hgignore` and `remote/.gitignore` files for those paths.
  66
  67 ### Validate that the new code works
  68
  69 Use `./mach puppeteer-test` (see [Testing]) to run Puppeteer tests against both
  70 Chromium and Firefox in headless mode. Again, only running a subset of tests
  71 against Firefox is fine -- at this point you just want to check that the
  72 typescript compiles and the browser binaries are launched successfully.
  73
  74 If something at this stage fails, you might want to check changes in
  75 `remote/test/puppeteer/package.json` and update `remote/mach_commands.py`
  76 with new npm scripts.
  77
  78 ### Verify the expectation meta data
  79
  80 Next, you want to make sure that the expectation meta data is correct. Check
  81 changes in [TestExpectations.json]. If there are
  82 newly skipped tests for Firefox, you might need to update these expectations.
  83 To do this, run the Puppeteer test job on try (see [Testing]). If these tests
  84 are specific for Chrome or time out, we want to keep them skipped, if they fail
  85 we want to have `FAIL` status for all platforms in the expectation meta data.
  86 You can see, if the meta data needs to be updated, at the end of the log file.
  87
  88 Examine the job logs and make sure the run didn't get interrupted early by a
  89 crash or a hang, especially if you see a lot of `TEST-UNEXPECTED-MISSING` in
  90 the Treeherder Failure Summary. You might have to fix some new bug in the unit
  91 tests. This is the fun part.
  92
  93 Some tests can also unexpectedly pass. Make sure it's correct, and if needed
  94 update the expectation data by following the instructions at the end of the
  95 log file.
  96
  97 ### Submit the code changes
  98
  99 Once you are happy with the metadata and are ready to submit the sync patch
 100 up for review, run the Puppeteer test job on try again with `--rebuild 10`
 101 to check for stability.
 102
 103 [Testing]: Testing.md
 104 [Puppeteer test suite]: https://github.com/GoogleChrome/puppeteer/tree/master/test
 105 [install the project]: https://github.com/puppeteer/puppeteer/blob/main/docs/contributing.md#getting-started
 106 [run tests against both Chromium and Firefox]: https://github.com/puppeteer/puppeteer/blob/main/test/README.md#running-tests
 107 [TestExpectations.json]: https://searchfox.org/mozilla-central/source/remote/test/puppeteer/test/TestExpectations.json
 108 [contributing.md]: https://github.com/puppeteer/puppeteer/blob/main/docs/contributing.md