docs(auth): running Lighthouse on authenticated pages

.eslintignore

@@ -4,6 +4,7 @@
 
 **/node_modules/**
 **/third_party/**
+/docs/**
 
 /dist/**
 

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/README.md

@@ -0,0 +1,94 @@
+# 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('[email protected]');
+const passwordInput = await page.$('input[type="password"]');
+await passwordInput.type('password');
+const submitInput = await page.$('input[type="submit"]');
+await submitInput.press('Enter');
+await 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,43 @@
+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('[email protected]');
+  const passwordInput = await page.$('input[type="password"]');
+  await passwordInput.type('password');
+  const submitInput = await page.$('input[type="submit"]');
+  await submitInput.press('Enter');
+  await 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,135 @@
+/** @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);
+
+/**
+ * @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;
+}
+
+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();
+  });
+
+  describe('logged out', () => {
+    describe('homepage', () => {
+      beforeEach(async () => {
+        await page.goto('http://localhost:8000/');
+      });
+
+      it('lighthouse', async () => {
+        const lhr = await runLighthouse(page.url());
+        expect(lhr.categories.seo.score).toBeGreaterThanOrEqual(0.9);
+      });
+
+      it('login form should exist', async () => {
+        const emailInput = await page.$('input[type="email"]');
+        const passwordInput = await page.$('input[type="password"]');
+        expect(emailInput).toBeTruthy();
+        expect(passwordInput).toBeTruthy();
+      });
+    });
+
+    describe('dashboard', () => {
+      beforeEach(async () => {
+        await page.goto('http://localhost:8000/');
+      });
+
+      it('lighthouse', async () => {
+        const lhr = await runLighthouse(page.url());
+        expect(lhr.categories.seo.score).toBeGreaterThanOrEqual(0.9);
+      });
+
+      it('has no secrets', async () => {
+        expect(await page.content()).not.toContain('secrets');
+      });
+    });
+  });
+
+  describe('logged in', () => {
+    beforeEach(async () => {
+      const loginPage = await browser.newPage();
+      await loginPage.goto('http://localhost:8000/');
+      await loginPage.waitForSelector('input[type="email"]', {visible: true});
+
+      const emailInput = await loginPage.$('input[type="email"]');
+      await emailInput.type('[email protected]');
+      const passwordInput = await loginPage.$('input[type="password"]');
+      await passwordInput.type('password');
+      await Promise.all([
+        loginPage.$eval('.login-form', form => form.submit()),
+        loginPage.waitForNavigation(),
+      ]);
+
+      await loginPage.close();
+    });
+
+    afterEach(async () => {
+      await page.goto('http://localhost:8000/logout');
+    });
+
+    describe('homepage', () => {
+      beforeEach(async () => {
+        await page.goto('http://localhost:8000/');
+      });
+
+      it('lighthouse', async () => {
+        const lhr = await runLighthouse(page.url());
+        expect(lhr.categories.seo.score).toBeGreaterThanOrEqual(0.9);
+      });
+    });
+
+    describe('dashboard', () => {
+      beforeEach(async () => {
+        await page.goto('http://localhost:8000/dashboard');
+      });
+
+      it('lighthouse', async () => {
+        const lhr = await runLighthouse(page.url());
+        expect(lhr.categories.seo.score).toBeGreaterThanOrEqual(0.9);
+      });
+
+      it('has secrets', async () => {
+        expect(await page.content()).toContain('secrets');
+      });
+    });
+  });
+});

docs/recipes/auth/package.json

@@ -0,0 +1,14 @@
+{
+  "scripts": {
+    "test": "jest example-lh-auth.test.js",
+    "start": "node server/server.js"
+  },
+  "dependencies": {
+    "express": "^4.17.1",
+    "express-session": "^1.16.2",
+    "jest": "^24.9.0",
+    "lighthouse": "^5.2.0",
+    "morgan": "^1.9.1",
+    "mustache-express": "^1.2.8"
+  }
+}