lighthouse 8.0.0-dev.20210709 → 8.0.0

package/docs/recipes/custom-gatherer-puppeteer/custom-gatherer.js

@@ -0,0 +1,51 @@
+/**
+ * @license Copyright 2020 The Lighthouse Authors. 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';
+
+/* global document */
+
+const Gatherer = require('lighthouse').Gatherer;
+const Puppeteer = require('puppeteer-core');
+
+async function connect(driver) {
+  const browser = await Puppeteer.connect({
+    browserWSEndpoint: await driver.wsEndpoint(),
+    defaultViewport: null,
+  });
+  const {targetInfo} = await driver.sendCommand('Target.getTargetInfo');
+  const puppeteerTarget = (await browser.targets())
+    .find(target => target._targetId === targetInfo.targetId);
+  const page = await puppeteerTarget.page();
+  return {browser, page, executionContext: driver.executionContext};
+}
+
+class CustomGatherer extends Gatherer {
+  async afterPass(options) {
+    const {driver} = options;
+    const {page, executionContext} = await connect(driver);
+
+    // Inject an input field for our debugging pleasure.
+    function makeInput() {
+      const el = document.createElement('input');
+      el.type = 'number';
+      document.body.append(el);
+    }
+    await executionContext.evaluate(makeInput, {args: []});
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Prove that `driver` (Lighthouse) and `page` (Puppeteer) are talking to the same page.
+    await executionContext.evaluateAsync(`document.querySelector('input').value = '1'`);
+    await page.type('input', '23', {delay: 300});
+    const value = await executionContext.evaluateAsync(`document.querySelector('input').value`);
+    if (value !== '123') throw new Error('huh?');
+
+    // No need to close the browser or page. Puppeteer doesn't own either of them.
+
+    return {value};
+  }
+}
+
+module.exports = CustomGatherer;

package/docs/recipes/custom-gatherer-puppeteer/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "custom-lighthouse-pptr-recipe",
+  "private": true,
+  "scripts": {
+    "test": "sh test.sh"
+  },
+  "devDependencies": {
+    "lighthouse": "file:../../../dist/lighthouse.tgz"
+  },
+  "dependencies": {
+    "puppeteer-core": "^2.0.0"
+  }
+}

package/docs/recipes/custom-gatherer-puppeteer/readme.md

@@ -0,0 +1,7 @@
+# Using Puppeteer in a Gatherer
+
+> **Tip**: see [Basic Custom Audit Recipe](../custom-audit) for basic information about custom audits.
+
+```sh
+lighthouse --config-path=custom-config.js https://www.example.com
+```

package/docs/recipes/custom-gatherer-puppeteer/test.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# Make sure we're in this `docs/recipes/customer-gatherer-puppeteer` directory
+cd "$(dirname "$0")"
+
+yarn
+node node_modules/.bin/lighthouse --config-path=custom-config.js https://www.example.com --output=json |
+  jq '.audits["custom-audit"].score' |
+  grep -q 1

package/docs/recipes/gulp/gulpfile.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * @license Copyright 2017 The Lighthouse Authors. 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.
+ */
+
+const gulp = require('gulp');
+const connect = require('gulp-connect');
+const lighthouse = require('lighthouse');
+const chromeLauncher = require('chrome-launcher');
+const PORT = 8080;
+
+/**
+ * Start server
+ */
+const startServer = function() {
+  return connect.server({
+    root: './public',
+    port: PORT,
+  });
+};
+
+/**
+ * Stop server
+ */
+const stopServer = function() {
+  connect.serverClose();
+};
+
+/**
+ * Run lighthouse
+ */
+function launchChromeAndRunLighthouse(url, flags, config = null) {
+  return chromeLauncher.launch().then(chrome => {
+    flags.port = chrome.port;
+    return lighthouse(url, flags, config).then(results =>
+      chrome.kill().then(() => results)
+    );
+  });
+}
+
+/**
+ * Handle ok result
+ * @param {Object} results - Lighthouse results
+ */
+const handleOk = function(results) {
+  stopServer();
+  console.log(results); // eslint-disable-line no-console
+  // TODO: use lighthouse results for checking your performance expectations.
+  // e.g. process.exit(1) or throw Error if score falls below a certain threshold.
+  // if (results.audits['first-meaningful-paint'].numericValue > 3000) {
+  //   console.log(`Warning: Time to first meaningful paint ${results.audits['first-meaningful-paint'].displayValue}`);
+  //   process.exit(1);
+  // }
+  return results;
+};
+
+/**
+ * Handle error
+ */
+const handleError = function(e) {
+  stopServer();
+  console.error(e); // eslint-disable-line no-console
+  throw e; // Throw to exit process with status 1.
+};
+
+const flags = {}; // available options - https://github.com/GoogleChrome/lighthouse/#cli-options
+
+gulp.task('lighthouse', function() {
+  startServer();
+  const config = {settings: {onlyCategories: ['performance']}};
+  return launchChromeAndRunLighthouse(`http://localhost:${PORT}/index.html`, flags, config)
+    .then(handleOk)
+    .catch(handleError);
+});
+
+gulp.task('default', ['lighthouse']);

package/docs/recipes/gulp/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "gulp-lighthouse-recipe",
+  "private": true,
+  "scripts": {
+    "start": "gulp"
+  },
+  "devDependencies": {
+    "gulp": "^3.9.1",
+    "gulp-connect": "^5.0.0",
+    "lighthouse": "^8.0.0"
+  }
+}

package/docs/recipes/gulp/public/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<!--
+ * Copyright 2017 The Lighthouse Authors. 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.
+-->
+<html>
+<head>
+  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.css">
+  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap-theme.css">
+  <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.js"></script>
+  <script src="https://code.jquery.com/jquery-3.1.0.js"></script>
+  <script src="https://code.jquery.com/ui/jquery-ui-git.js"></script>
+</head>
+<body>
+
+<h1>Slow page</h1>
+
+<img src="https://cloud.githubusercontent.com/assets/238208/21210165/b3c368c0-c22d-11e6-91fb-aa24959e2637.png">
+
+</body>
+</html>

package/docs/recipes/gulp/readme.md

@@ -0,0 +1,6 @@
+# Gulp recipe for Lighthouse
+ 
+## Run
+
+- `npm install`
+- `npm start`

package/docs/recipes/integration-test/README.md

@@ -0,0 +1,14 @@
+# Running Lighthouse on in Your Integration Jest Tests
+
+See [example-lh-auth.test.js](./example-lh-auth.test.js) for an example of how to run Lighthouse in your Jest tests on pages in both an authenticated and non-authenticated session. This recipe builds on the [auth docs](../auth).
+
+```sh
+# Be in this folder: docs/recipes/integration-test
+
+# Install deps.
+yarn
+yarn --cwd ../auth
+
+# Test.
+yarn test
+```

package/docs/recipes/integration-test/example-lh-auth.test.js

@@ -0,0 +1,160 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. 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';
+
+/* eslint-env jest */
+/* eslint-disable new-cap */
+
+/**
+ * @fileoverview Example Jest tests for demonstrating how to run Lighthouse on an authenticated
+ * page as integration tests. See docs/recipes/auth/README.md for more.
+ */
+
+/** @typedef {import('lighthouse/types/lhr')} LH */
+
+const puppeteer = require('puppeteer');
+const lighthouse = require('lighthouse');
+const server = require('../auth/server/server.js');
+const {login, logout} = require('../auth/example-lh-auth.js');
+
+const CHROME_DEBUG_PORT = 8042;
+const SERVER_PORT = 10632;
+const ORIGIN = `http://localhost:${SERVER_PORT}`;
+
+jest.setTimeout(30000);
+
+// Provide a nice way to assert a score for a category.
+// Note, you could just use `expect(lhr.categories.seo.score).toBeGreaterThanOrEqual(0.9)`,
+// but by using a custom matcher a better error report is generated.
+expect.extend({
+  toHaveLighthouseScoreGreaterThanOrEqual(lhr, category, threshold) {
+    const score = lhr.categories[category].score;
+    const auditsRefsByWeight = [...lhr.categories[category].auditRefs]
+      .filter((auditRef) => auditRef.weight > 0)
+      .sort((a, b) => b.weight - a.weight);
+    const report = auditsRefsByWeight.map((auditRef) => {
+      const audit = lhr.audits[auditRef.id];
+      const status = audit.score === 1 ?
+        this.utils.EXPECTED_COLOR('○') :
+        this.utils.RECEIVED_COLOR('✕');
+      const weight = this.utils.DIM_COLOR(`[weight: ${auditRef.weight}]`);
+      return `\t${status} ${weight} ${audit.id}`;
+    }).join('\n');
+
+    if (score >= threshold) {
+      return {
+        pass: true,
+        message: () =>
+          `expected category ${category} to be < ${threshold}, but got ${score}\n${report}`,
+      };
+    } else {
+      return {
+        pass: false,
+        message: () =>
+          `expected category ${category} to be >= ${threshold}, but got ${score}\n${report}`,
+      };
+    }
+  },
+});
+
+/**
+ * @param {string} url
+ * @return {Promise<LH.Result>}
+ */
+async function runLighthouse(url) {
+  const result = await lighthouse(url, {
+    port: CHROME_DEBUG_PORT,
+    disableStorageReset: true,
+    onlyCategories: ['seo'],
+  });
+  return result.lhr;
+}
+
+describe('my site', () => {
+  /** @type {import('puppeteer').Browser} */
+  let browser;
+  /** @type {import('puppeteer').Page} */
+  let page;
+
+  beforeAll(async () => {
+    await new Promise(resolve => server.listen(SERVER_PORT, resolve));
+    browser = await puppeteer.launch({
+      args: [`--remote-debugging-port=${CHROME_DEBUG_PORT}`],
+      headless: !process.env.DEBUG,
+      slowMo: process.env.DEBUG ? 50 : undefined,
+    });
+  });
+
+  afterAll(async () => {
+    await browser.close();
+    await new Promise(resolve => server.close(resolve));
+  });
+
+  beforeEach(async () => {
+    page = await browser.newPage();
+  });
+
+  afterEach(async () => {
+    await page.close();
+    await logout(browser, ORIGIN);
+  });
+
+  describe('/ logged out', () => {
+    it('lighthouse', async () => {
+      await page.goto(ORIGIN);
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('login form should exist', async () => {
+      await page.goto(ORIGIN);
+      const emailInput = await page.$('input[type="email"]');
+      const passwordInput = await page.$('input[type="password"]');
+      expect(emailInput).toBeTruthy();
+      expect(passwordInput).toBeTruthy();
+    });
+  });
+
+  describe('/ logged in', () => {
+    it('lighthouse', async () => {
+      await login(browser, ORIGIN);
+      await page.goto(ORIGIN);
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('login form should not exist', async () => {
+      await login(browser, ORIGIN);
+      await page.goto(ORIGIN);
+      const emailInput = await page.$('input[type="email"]');
+      const passwordInput = await page.$('input[type="password"]');
+      expect(emailInput).toBeFalsy();
+      expect(passwordInput).toBeFalsy();
+    });
+  });
+
+  describe('/dashboard logged out', () => {
+    it('has no secrets', async () => {
+      await page.goto(`${ORIGIN}/dashboard`);
+      expect(await page.content()).not.toContain('secrets');
+    });
+  });
+
+  describe('/dashboard logged in', () => {
+    it('lighthouse', async () => {
+      await login(browser, ORIGIN);
+      await page.goto(`${ORIGIN}/dashboard`);
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('has secrets', async () => {
+      await login(browser, ORIGIN);
+      await page.goto(`${ORIGIN}/dashboard`);
+      expect(await page.content()).toContain('secrets');
+    });
+  });
+});

package/docs/recipes/integration-test/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "test": "jest example-lh-auth.test.js"
+  },
+  "dependencies": {
+    "jest": "^24.9.0",
+    "lighthouse": "file:../../../dist/lighthouse.tgz"
+  }
+}

package/docs/recipes/lighthouse-plugin-example/audits/preload-as.js

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. 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';
+
+const Audit = require('lighthouse').Audit;
+
+/**
+ * @fileoverview A fake additional check of the robots.txt file.
+ */
+
+// https://fetch.spec.whatwg.org/#concept-request-destination
+const allowedTypes = new Set(['font', 'image', 'script', 'serviceworker', 'style', 'worker']);
+
+class PreloadAsAudit extends Audit {
+  static get meta() {
+    return {
+      id: 'preload-as',
+      title: 'Preloaded requests have proper `as` attributes',
+      failureTitle: 'Some preloaded requests do not have proper `as` attributes',
+      description: '`<link rel=preload>` tags need an `as` attribute to specify the type of ' +
+          'content being loaded.',
+
+      // The name of the artifact provides input to this audit.
+      requiredArtifacts: ['LinkElements'],
+    };
+  }
+
+  static audit(artifacts) {
+    // Check that all `<link rel=preload>` elements had a defined `as` attribute.
+    const preloadLinks = artifacts.LinkElements.filter(el => el.rel === 'preload');
+    const noAsLinks = preloadLinks.filter(el => !allowedTypes.has(el.as));
+
+    // Audit passes if there are no missing attributes.
+    const passed = noAsLinks.length === 0;
+
+    return {
+      score: passed ? 1 : 0,
+      displayValue: `Found ${noAsLinks.length} preload requests with missing \`as\` attributes`,
+    };
+  }
+}
+
+module.exports = PreloadAsAudit;

package/docs/recipes/lighthouse-plugin-example/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "lighthouse-plugin-example",
+  "private": true,
+  "main": "./plugin.js",
+  "peerDependencies": {
+    "lighthouse": "^8.0.0"
+  },
+  "devDependencies": {
+    "lighthouse": "^8.0.0"
+  }
+}

package/docs/recipes/lighthouse-plugin-example/plugin.js

@@ -0,0 +1,24 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. 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';
+
+/** @type {LH.Config.Plugin} */
+module.exports = {
+  // Additional audit to run on information Lighthouse gathered.
+  audits: [{
+    path: 'lighthouse-plugin-example/audits/preload-as.js',
+  }],
+
+  // A new category in the report for the new audit's output.
+  category: {
+    title: 'My Plugin Category',
+    description: 'Results for our new plugin category.',
+    auditRefs: [
+      {id: 'preload-as', weight: 1},
+      {id: 'meta-description', weight: 1}, // Can also reference default Lighthouse audits.
+    ],
+  },
+};

package/docs/recipes/lighthouse-plugin-example/readme.md

@@ -0,0 +1,53 @@
+# Lighthouse plugin recipe
+
+## Contents
+- `package.json` - declares the plugin's entry point (`plugin.js`)
+- `plugin.js` - instructs Lighthouse to run the plugin's own `preload-as.js` audit; describes the new category and its details for the report
+- `audits/preload-as.js` - the new audit to run in addition to Lighthouse's default audits
+
+## To develop as a plugin developer
+
+Run the following to start of with the recipe as a template:
+
+```sh
+mkdir lighthouse-plugin-example && cd lighthouse-plugin-example
+curl -L https://github.com/GoogleChrome/lighthouse/archive/master.zip | tar -xzv
+mv lighthouse-master/docs/recipes/lighthouse-plugin-example/* ./
+rm -rf lighthouse-master
+```
+
+Install and run just your plugin:
+
+```sh
+yarn
+NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view
+```
+
+When you rename the plugin, be sure to rename its directory as well.
+
+### Iterating
+To speed up development, you can gather once and iterate by auditing repeatedly.
+
+```sh
+# Gather artifacts from the browser
+NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --gather-mode
+
+# and then iterate re-running this:
+NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --audit-mode --view
+```
+
+Finally, publish to NPM.
+
+## To run as a plugin user
+
+1. Install `lighthouse` (v5+) and the plugin `lighthouse-plugin-example`, likely as `devDependencies`. 
+   * `npm install -D lighthouse lighthouse-plugin-example`
+1. To run your private lighthouse binary, you have three options
+   1. `npx --no-install lighthouse https://example.com --plugins=lighthouse-plugin-example --view`
+   1. `yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --view`
+   1. Add an npm script calling `lighthouse` and run that.
+
+
+## Result
+
+![Screenshot of report with plugin results](./plugin-recipe-screenshot.png)