fix(docker): include globally installed puppeteer (#736)

docs/recipes/docker-client/Dockerfile

@@ -1,5 +1,8 @@
 FROM node:14-bullseye-slim
 
+# Set variable so puppeteer will not try to download chromium
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+
 # Install utilities
 RUN apt-get update --fix-missing && apt-get -y upgrade && apt-get install -y git wget gnupg && apt-get clean
 
@@ -14,12 +17,17 @@ RUN apt-get update \
 RUN npm install -g @lhci/cli@0.9.0
 RUN npm install -g lighthouse
 
+# Install puppeteer
+RUN npm install -g puppeteer
+
 # Setup a user to avoid doing everything as root
 RUN groupadd --system lhci && \
   useradd --system --create-home --gid lhci lhci && \
   mkdir --parents /home/lhci/reports && \
   chown --recursive lhci:lhci /home/lhci
 
+RUN cd /home/lhci/reports && npm link puppeteer
+
 USER lhci
 WORKDIR /home/lhci/reports
 

docs/recipes/docker-client/README.md

@@ -54,6 +54,38 @@ docker container run --cpus=".9" --shm-size=2g --cap-add=SYS_ADMIN \
 ```
 The above command will provide 0.9 CPU from the available CPUs. In a 2 core processor, docker will have access to 45% of the CPU cycles. You can tune it as per your need. Keep a check on CPU/Memory Power at the bottom of your lighthouse report for consistent results.
 
+## Using puppeteer
+Puppeteer is present as a dependency in the docker container. If you specify a `puppeteerScript` when running, you should also provide 2 `puppeteerLaunchOptions` for it to work properly in the container, `--no-sandbox` and `--disable-setuid-sandbox`.
+
+As CLI arguments:
+```bash
+docker container run --cap-add=SYS_ADMIN \
+  -v "$(pwd)/lhci-data:/home/lhci/reports/.lighthouseci" \
+  -v "$(pwd)/scripts:/home/lhci/reports/scripts" \
+  patrickhulce/lhci-client \
+  lhci collect --url="https://example.com" \
+               --puppeteerScript=docs/recipes/puppeteer-example.js \
+               --puppeteerLaunchOptions.args=--no-sandbox \
+               --puppeteerLaunchOptions.args=--disable-setuid-sandbox
+```
+
+When using `lighthouserc.js`:
+```javascript
+module.exports = {
+  ci: {
+    collect: {
+      // ...
+      puppeteerScript: 'docs/recipes/puppeteer-example.js',
+      puppeteerLaunchOptions: {
+        args: ['--no-sandbox', '--disable-setuid-sandbox']
+      },
+      // ...
+    },
+    // ...
+  },
+};
+```
+
 ## `--no-sandbox` Issues Explained
 
 Chrome uses sandboxing to isolate renderer processes and restrict their capabilities. If a rogue website is able to discover a browser vulnerability and break out of JavaScript engine for example, they would find themselves in a very limited process that can't write to the filesystem, make network requests, mess with devices, etc.

docs/recipes/puppeteer-example.js

@@ -0,0 +1,20 @@
+/**
+ * @license Copyright 2022 Google Inc. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+/**
+ * @param {puppeteer.Browser} browser
+ * @param {{url: string, options: LHCI.CollectCommand.Options}} context
+ */
+module.exports = async (browser, context) => {
+  // launch browser for LHCI
+  const page = await browser.newPage();
+
+  await page.goto("https://example.com");
+
+  // close session for next run
+  await page.close();
+};