docs(auth): running Lighthouse on authenticated pages

docs/authenticated-pages.md

@@ -0,0 +1,33 @@
+# Running Lighthouse on Authenticated Pages
+
+Default runs of Lighthouse load a page as a "new user", with no previous session or storage data. This means that pages requiring authenticated access do not work without additional setup.
+
+## Puppeteer
+
+[Puppeteer](https://pptr.dev) is the most flexible approach for auditing pages behind authentication with Lighthouse. See [recipes/auth](./recipes/auth) for more.
+
+## Chrome DevTools
+
+The Audits panel in Chrome DevTools will never clear your session cookies, so you can log in to the target site and run Lighthouse without being logged out. If `localStorage` or `indexedDB` is important for your authentication purposes, be sure to uncheck `Clear storage`.
+
+## Headers
+
+CLI:
+```sh
+lighthouse http://www.example.com --view --extra-headers="{\"Authorization\":\"...\"}"
+```
+
+Node:
+```js
+const result = await lighthouse('http://www.example.com', {
+  extraHeaders: {
+    Authorization: '...',
+  },
+});
+```
+
+You could also set the `Cookie` header, but beware: it will [override any other Cookies you expect to be there](https://github.com/GoogleChrome/lighthouse/pull/9170). A workaround is to use Puppeteer's [`page.setCookie`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetcookiecookies).
+
+## Chrome User Profile
+
+TODO: pending [#8957](https://github.com/GoogleChrome/lighthouse/issues/8957).

docs/recipes/auth/.eslintrc.js

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright 2019 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';
+
+module.exports = {
+  extends: '../../../.eslintrc.js',
+  env: {
+    jest: true,
+  },
+  rules: {
+    'new-cap': 0,
+    'no-console': 0,
+    'no-unused-vars': 0,
+  },
+};

docs/recipes/auth/README.md

@@ -0,0 +1,95 @@
+# Running Lighthouse on Authenticated Pages with Puppeteer
+
+If you just want to view the code, see [example-lh-auth.js](./example-lh-auth.js).
+
+## 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, so there are four different pages that must have passable Lighthouse SEO scores.
+
+(Optional) To run the server:
+```sh
+# be in root lighthouse directory
+yarn # install global project deps
+cd docs/auth
+yarn # install deps related to just this documentation
+yarn start # start the server on http://localhost:8000
+```
+
+## 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.
+const PORT = 8041;
+const browser = await puppeteer.launch({
+  args: [`--remote-debugging-port=${PORT}`],
+});
+```
+
+Navigate to the login form:
+```js
+const page = await browser.newPage();
+await page.goto('http://localhost:8000');
+```
+
+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
+const result = await lighthouse('http://localhost:8000/dashboard', { port: PORT });
+await browser.close();
+const lhr = result.lhr;
+```
+
+## Puppetter in Your Integration 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.

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

@@ -0,0 +1,56 @@
+/**
+ * @license Copyright 2019 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';
+
+/**
+ * @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');
+
+const PORT = 8041;
+
+/**
+ * @param {import('puppeteer').Browser} browser
+ */
+async function login(browser) {
+  const page = await browser.newPage();
+  await page.goto('http://localhost:8000');
+  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();
+}
+
+async function main() {
+  // Direct Puppeteer to open Chrome with a specific debugging port.
+  const browser = await puppeteer.launch({
+    args: [`--remote-debugging-port=${PORT}`],
+  });
+
+  // Setup the browser session to be logged into our site.
+  await login(browser);
+
+  // Direct Lighthouse to use the same port.
+  const result = await lighthouse('http://localhost:8000/dashboard', {port: PORT});
+  await browser.close();
+
+  // Output the result.
+  console.log(JSON.stringify(result.lhr, null, 2));
+}
+
+main();

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

@@ -0,0 +1,183 @@
+/**
+ * @license Copyright 2019 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';
+
+/**
+ * @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('./node_modules/lighthouse/types/lhr')} LH */
+
+const puppeteer = require('puppeteer');
+const lighthouse = require('lighthouse');
+const server = require('./server/server.js');
+
+const CHROME_DEBUG_PORT = 8042;
+const SERVER_PORT = 8000;
+
+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 can be 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,
+    onlyCategories: ['seo'],
+  });
+  return result.lhr;
+}
+
+/**
+ * @param {puppeteer.Browser} browser
+ */
+async function login(browser) {
+  const page = await browser.newPage();
+  await page.goto('http://localhost:8000/');
+  await page.waitForSelector('input[type="email"]', {visible: true});
+
+  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
+ */
+async function logout(browser) {
+  const page = await browser.newPage();
+  await page.goto('http://localhost:8000/logout');
+  await page.close();
+}
+
+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);
+  });
+
+  describe('/ logged out', () => {
+    it('lighthouse', async () => {
+      await page.goto('http://localhost:8000/');
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('login form should exist', async () => {
+      await page.goto('http://localhost:8000/');
+      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);
+      await page.goto('http://localhost:8000/');
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('login form should not exist', async () => {
+      await login(browser);
+      await page.goto('http://localhost:8000/');
+      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('http://localhost:8000/dashboard');
+      expect(await page.content()).not.toContain('secrets');
+    });
+  });
+
+  describe('/dashboard logged in', () => {
+    it('lighthouse', async () => {
+      await login(browser);
+      await page.goto('http://localhost:8000/dashboard');
+      const lhr = await runLighthouse(page.url());
+      expect(lhr).toHaveLighthouseScoreGreaterThanOrEqual('seo', 0.9);
+    });
+
+    it('has secrets', async () => {
+      await login(browser);
+      await page.goto('http://localhost:8000/dashboard');
+      expect(await page.content()).toContain('secrets');
+    });
+  });
+});