lighthouse 8.0.0-dev.20210709 → 8.0.0

package/docs/recipes/auth/README.md

@@ -0,0 +1,129 @@
+# Running Lighthouse on Authenticated Pages with Puppeteer
+
+If you just want to view the code for using Lighthouse with Puppeteer, see [example-lh-auth.js](./example-lh-auth.js).
+
+See [the integration test docs](../integration-test) for an example of how to run Lighthouse in your Jest tests on pages in both an authenticated and non-authenticated session.
+
+## The Example Site
+
+There are two pages on the site:
+
+1. `/` - the homepage
+2. `/dashboard`
+
+The homepage shows the login form, but only to users that are not signed in.
+
+The dashboard shows a secret to users that are logged in, but shows an error to users that are not.
+
+The server responds with different HTML for each of these pages and session states.
+
+(Optional) To run the server:
+```sh
+# be in root lighthouse directory
+yarn # install global project deps
+cd docs/recipes/auth
+yarn # install deps related to just this recipe
+yarn start # start the server on http://localhost:10632
+```
+
+Now that the server is started, let's login with Puppeteer and then run Lighthouse:
+```sh
+node example-lh-auth.js
+```
+What does this do?  Read on....
+
+## Process
+
+Puppeteer - a browser automation tool - can be used to programatically setup a session.
+
+1. Launch a new browser.
+1. Navigate to the login page.
+1. Fill and submit the login form.
+1. Run Lighthouse using the same browser.
+
+First, launch Chrome:
+```js
+// This port will be used by Lighthouse later. The specific port is arbitrary.
+const PORT = 8041;
+const browser = await puppeteer.launch({
+  args: [`--remote-debugging-port=${PORT}`],
+  // Optional, if you want to see the tests in action.
+  headless: false,
+  slowMo: 50,
+});
+```
+
+Navigate to the login form:
+```js
+const page = await browser.newPage();
+await page.goto('http://localhost:10632');
+```
+
+Given a login form like this:
+```html
+<form action="/login" method="post">
+  <label>
+    Email:
+    <input type="email" name="email">
+  </label>
+  <label>
+    Password:
+    <input type="password" name="password">
+  </label>
+  <input type="submit">
+</form>
+```
+
+Direct Puppeteer to fill and submit it:
+```js
+const emailInput = await page.$('input[type="email"]');
+await emailInput.type('admin@example.com');
+const passwordInput = await page.$('input[type="password"]');
+await passwordInput.type('password');
+await Promise.all([
+  page.$eval('.login-form', form => form.submit()),
+  page.waitForNavigation(),
+]);
+```
+
+At this point, the session that Puppeteer is managing is now logged in.
+
+Close the page used to log in:
+```js
+await page.close();
+// The page has been closed, but the browser still has the relevant session.
+```
+
+Now run Lighthouse, using the same port as before:
+```js
+// The local server is running on port 10632.
+const url = 'http://localhost:10632/dashboard';
+// Direct Lighthouse to use the same port.
+const result = await lighthouse(url, {port: PORT, disableStorageReset: true});
+const lhr = result.lhr;
+
+// Direct Puppeteer to close the browser - we're done with it.
+await browser.close();
+```
+
+All of the above is done in the example script. To run:
+```sh
+# make sure server is running (see beginning of recipe) ...
+node example-lh-auth.js # login via puppeteer and run lighthouse
+```
+
+## Alternatives
+
+### [`page.setCookie`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetcookiecookies)
+
+**NOTE:** We strongly recommend your tests use the form-based login flow above instead. Only directly set the token like this as a last resort.
+
+If you don't have user credentials to login but you do have direct access to a token for authentication, you can instead directly set a cookie.
+
+```js
+await page.setCookie({
+  name: 'myAuthCookie',
+  value: '<auth token goes here>',
+  url: 'http://localhost:10632/dashboard',
+});
+```

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

@@ -0,0 +1,81 @@
+/**
+ * @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';
+
+/**
+ * @fileoverview Example script for running Lighthouse on an authenticated page.
+ * See docs/recipes/auth/README.md for more.
+ */
+
+const puppeteer = require('puppeteer');
+const lighthouse = require('lighthouse');
+
+// This port will be used by Lighthouse later. The specific port is arbitrary.
+const PORT = 8041;
+
+/**
+ * @param {import('puppeteer').Browser} browser
+ * @param {string} origin
+ */
+async function login(browser, origin) {
+  const page = await browser.newPage();
+  await page.goto(origin);
+  await page.waitForSelector('input[type="email"]', {visible: true});
+
+  // Fill in and submit login form.
+  const emailInput = await page.$('input[type="email"]');
+  await emailInput.type('admin@example.com');
+  const passwordInput = await page.$('input[type="password"]');
+  await passwordInput.type('password');
+  await Promise.all([
+    page.$eval('.login-form', form => form.submit()),
+    page.waitForNavigation(),
+  ]);
+
+  await page.close();
+}
+
+/**
+ * @param {puppeteer.Browser} browser
+ * @param {string} origin
+ */
+async function logout(browser, origin) {
+  const page = await browser.newPage();
+  await page.goto(`${origin}/logout`);
+  await page.close();
+}
+
+async function main() {
+  // Direct Puppeteer to open Chrome with a specific debugging port.
+  const browser = await puppeteer.launch({
+    args: [`--remote-debugging-port=${PORT}`],
+    // Optional, if you want to see the tests in action.
+    headless: false,
+    slowMo: 50,
+  });
+
+  // Setup the browser session to be logged into our site.
+  await login(browser, 'http://localhost:10632');
+
+  // The local server is running on port 10632.
+  const url = 'http://localhost:10632/dashboard';
+  // Direct Lighthouse to use the same port.
+  const result = await lighthouse(url, {port: PORT, disableStorageReset: true});
+  // Direct Puppeteer to close the browser as we're done with it.
+  await browser.close();
+
+  // Output the result.
+  console.log(JSON.stringify(result.lhr, null, 2));
+}
+
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    login,
+    logout,
+  };
+}

package/docs/recipes/auth/package.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "start": "node server/server.js"
+  },
+  "dependencies": {
+    "express": "^4.17.1",
+    "express-session": "^1.16.2",
+    "lighthouse": "file:../../../dist/lighthouse.tgz",
+    "morgan": "^1.9.1"
+  }
+}

package/docs/recipes/auth/server/public/dashboard-unauthenticated.html

@@ -0,0 +1,21 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard - Unauthenticated</title>
+</head>
+<body>
+  you need to be logged in.
+  <style>
+    body {
+      background-color: #CD5C5C;
+    }
+</style>
+</body>
+</html>

package/docs/recipes/auth/server/public/dashboard.html

@@ -0,0 +1,25 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard</title>
+</head>
+<body>
+  <h1>Dashboard</h1>
+  <div>
+    secrets here
+  </div>
+  <a href="/logout">logout</a>
+  <style>
+    body {
+      background-color: green;
+    }
+  </style>
+</body>
+</html>

package/docs/recipes/auth/server/public/home-unauthenticated.html

@@ -0,0 +1,27 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Home - Login</title>
+</head>
+<body>
+  <h1>Plz login</h1>
+  <form class="login-form" action="/login" method="post">
+    <label>
+      Email:
+      <input type="email" name="email">
+    </label>
+    <label>
+      Password:
+      <input type="password" name="password">
+    </label>
+    <input type="submit">
+  </form> 
+</body>
+</html>

package/docs/recipes/auth/server/public/home.html

@@ -0,0 +1,17 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Home - Logged In</title>
+</head>
+<body>
+  <h1>Welcome home!</h1>
+  <span>You are logged in. Go to <a href="/dashboard">the dashboard</a>.</span>
+</body>
+</html>

package/docs/recipes/auth/server/public/unauthenticated.html

@@ -0,0 +1,22 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <title>Dashboard</title>
+</head>
+<body>
+  you need to be logged in.
+  <style>
+    body {
+      background-color: #CD5C5C;
+    }
+</style>
+</body>
+</html>

package/docs/recipes/auth/server/server.js

@@ -0,0 +1,85 @@
+/**
+ * @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';
+
+/**
+ * @fileoverview Example Express server for demonstrating how to run Lighthouse on an authenticated
+ * page. See docs/recipes/auth/README.md for more.
+ */
+
+const createError = require('http-errors');
+const express = require('express');
+const morgan = require('morgan');
+const session = require('express-session');
+const http = require('http');
+const path = require('path');
+const PUBLIC_DIR = path.join(__dirname, 'public');
+
+const app = express();
+
+app.use(morgan('dev'));
+app.use(express.urlencoded({extended: false}));
+
+app.use(session({
+  secret: 'notverysecret',
+  resave: true,
+  saveUninitialized: false,
+}));
+
+app.get('/dashboard', (req, res) => {
+  if (req.session.user) {
+    res.sendFile('./dashboard.html', {root: PUBLIC_DIR});
+  } else {
+    res.status(401).sendFile('./dashboard-unauthenticated.html', {root: PUBLIC_DIR});
+  }
+});
+
+app.get('/', (req, res) => {
+  if (req.session.user) {
+    res.sendFile('home.html', {root: PUBLIC_DIR});
+  } else {
+    res.sendFile('home-unauthenticated.html', {root: PUBLIC_DIR});
+  }
+});
+
+app.post('/login', (req, res, next) => {
+  const {email, password} = req.body;
+  // super secret login and password ;)
+  if (email !== 'admin@example.com' || password !== 'password') {
+    return next(createError(401));
+  }
+
+  req.session.user = {
+    email,
+  };
+  res.redirect('/dashboard');
+});
+
+app.get('/logout', (req, res, next) => {
+  req.session.destroy(() => {
+    res.redirect('/');
+  });
+});
+
+// Error handlers
+app.use(function(req, res, next) {
+  next(createError(404));
+});
+
+app.use(function(err, req, res, next) {
+  res.locals.message = err.message;
+  res.locals.error = err;
+
+  res.status(err.status || 500);
+  res.json({err});
+});
+
+const server = http.createServer(app);
+if (require.main === module) {
+  server.listen(10632);
+} else {
+  module.exports = server;
+}

package/docs/recipes/custom-audit/custom-config.js

@@ -0,0 +1,36 @@
+/**
+ * @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.
+ */
+'use strict';
+
+module.exports = {
+  // 1. Run your custom tests along with all the default Lighthouse tests.
+  extends: 'lighthouse:default',
+
+  // 2. Add gatherer to the default Lighthouse load ('pass') of the page.
+  passes: [{
+    passName: 'defaultPass',
+    gatherers: [
+      'searchable-gatherer',
+    ],
+  }],
+
+  // 3. Add custom audit to the list of audits 'lighthouse:default' will run.
+  audits: [
+    'searchable-audit',
+  ],
+
+  // 4. Create a new 'My site metrics' section in the default report for our results.
+  categories: {
+    mysite: {
+      title: 'My site metrics',
+      description: 'Metrics for our super awesome site',
+      auditRefs: [
+        // When we add more custom audits, `weight` controls how they're averaged together.
+        {id: 'searchable-audit', weight: 1},
+      ],
+    },
+  },
+};

package/docs/recipes/custom-audit/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "custom-lighthouse-recipe",
+  "private": true,
+  "scripts": {},
+  "devDependencies": {
+    "lighthouse": "^8.0.0"
+  }
+}

package/docs/recipes/custom-audit/readme.md

@@ -0,0 +1,32 @@
+# Basic Custom Audit Recipe
+
+> **Tip**: see [Lighthouse Architecture](../../../docs/architecture.md) for information
+on terminology and architecture.
+
+## What this example does
+
+This example shows how to write a custom Lighthouse audit for a hypothetical search page. The page is considered fully initialized when the main search box (the page's "hero element") is ready to be used. When this happens, the page uses `performance.now()` to mark the time it took to become ready and saves the value in a global variable called `window.myLoadMetrics.searchableTime`.
+
+## The Audit, Gatherer, and Config
+
+- [searchable-gatherer.js](searchable-gatherer.js) - a [Gatherer](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that collects `window.myLoadMetrics.searchableTime`
+from the context of the page.
+
+- [searchable-audit.js](searchable-audit.js) - an [Audit](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that tests whether or not `window.myLoadMetrics.searchableTime`
+stays below a 4000ms threshold. In other words, Lighthouse will consider the audit "passing"
+in the report if the search box initializes within 4s.
+
+- [custom-config.js](custom-config.js) - this file tells Lighthouse where to
+find the gatherer and audit files, when to run them, and how to incorporate their
+output into the Lighthouse report. This example extends [Lighthouse's
+default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default-config.js).
+
+**Note**: when extending the default configuration file, passes with the same name are merged together, all other arrays will be concatenated, and primitive values will override the defaults.
+
+## Run the configuration
+
+Run Lighthouse with the custom audit by using the `--config-path` flag with your configuration file:
+
+```sh
+lighthouse --config-path=custom-config.js https://example.com
+```

package/docs/recipes/custom-audit/searchable-audit.js

@@ -0,0 +1,46 @@
+/**
+ * @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.
+ */
+'use strict';
+
+const Audit = require('lighthouse').Audit;
+
+const MAX_SEARCHABLE_TIME = 4000;
+
+/**
+ * @fileoverview Tests that `window.myLoadMetrics.searchableTime` was below the
+ * test threshold value.
+ */
+
+class LoadAudit extends Audit {
+  static get meta() {
+    return {
+      id: 'searchable-audit',
+      title: 'Search box initialized and ready',
+      failureTitle: 'Search box slow to initialize',
+      description: 'Used to measure time to when the search' +
+          ' box is initialized and ready to search.',
+
+      // The name of the custom gatherer class that provides input to this audit.
+      requiredArtifacts: ['TimeToSearchable'],
+    };
+  }
+
+  static audit(artifacts) {
+    const loadMetrics = artifacts.TimeToSearchable;
+
+    // Audit will pass when the search box loaded in less time than our threshold.
+    // This score will be binary, so will get a red ✘ or green ✓ in the report.
+    const belowThreshold = loadMetrics.searchableTime <= MAX_SEARCHABLE_TIME;
+
+    return {
+      numericValue: loadMetrics.searchableTime,
+      // Cast true/false to 1/0
+      score: Number(belowThreshold),
+    };
+  }
+}
+
+module.exports = LoadAudit;

package/docs/recipes/custom-audit/searchable-gatherer.js

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+'use strict';
+
+const Gatherer = require('lighthouse').Gatherer;
+
+/**
+ * @fileoverview Extracts `window.myLoadMetrics` from the test page.
+ */
+
+class TimeToSearchable extends Gatherer {
+  afterPass(options) {
+    const driver = options.driver;
+
+    return driver.executionContext.evaluateAsync('window.myLoadMetrics')
+      // Ensure returned value is what we expect.
+      .then(loadMetrics => {
+        if (!loadMetrics || loadMetrics.searchableTime === undefined) {
+          // Throw if page didn't provide the metrics we expect. This isn't
+          // fatal -- the Lighthouse run will continue, but any audits that
+          // depend on this gatherer will show this error string in the report.
+          throw new Error('Unable to find load metrics in page');
+        }
+        return loadMetrics;
+      });
+  }
+}
+
+module.exports = TimeToSearchable;

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

@@ -0,0 +1,34 @@
+/**
+ * @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';
+
+const Audit = require('lighthouse').Audit;
+
+class CustomAudit extends Audit {
+  static get meta() {
+    return {
+      id: 'custom-audit',
+      title: 'First text input field accepts `123` as input',
+      failureTitle: 'First text input field doesn\'t accept `123` as input',
+      description: 'Example custom audit which relies on a fancy gatherer.',
+
+      // The name of the custom gatherer class that provides input to this audit.
+      requiredArtifacts: ['CustomGatherer'],
+    };
+  }
+
+  static audit(artifacts) {
+    const value = artifacts.CustomGatherer.value;
+    const success = value === '123';
+
+    return {
+      // Cast true/false to 1/0
+      score: Number(success),
+    };
+  }
+}
+
+module.exports = CustomAudit;

package/{root.js → docs/recipes/custom-gatherer-puppeteer/custom-config.js}

@@ -1,8 +1,29 @@
 /**
- * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * @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';
 
-module.exports.LH_ROOT = __dirname;
+module.exports = {
+  passes: [{
+    passName: 'defaultPass',
+    gatherers: [
+      'custom-gatherer',
+    ],
+  }],
+
+  audits: [
+    'custom-audit',
+  ],
+
+  categories: {
+    mysite: {
+      title: 'My custom audit',
+      description: 'Super awesome, strings included',
+      auditRefs: [
+        {id: 'custom-audit', weight: 1},
+      ],
+    },
+  },
+};