Testing authenticated pages

Run Lighthouse on pages that require a login using Puppeteer, Chrome DevTools, request headers, or a debug Chrome instance.

By default, Lighthouse loads a page as a new user with no session or storage data. Pages behind a login require additional setup. There are several approaches depending on your use case.

Option 1: Script the login with Puppeteer

Puppeteer is the most flexible approach. It lets you automate the login flow before handing the authenticated page to Lighthouse.

npm install puppeteer lighthouse

import puppeteer from 'puppeteer';
import lighthouse from 'lighthouse';

async function login(page, origin) {
  await page.goto(origin);
  await page.waitForSelector('input[type="email"]', { visible: true });

  const emailInput = await page.$('input[type="email"]');
  await emailInput.type('[e-mail]');
  const passwordInput = await page.$('input[type="password"]');
  await passwordInput.type('password');

  await Promise.all([
    page.$eval('.login-form', form => form.submit()),
    page.waitForNavigation(),
  ]);
}

async function main() {
  const browser = await puppeteer.launch({
    headless: 'new',
    slowMo: 50,
  });
  const page = await browser.newPage();

  // Log in before running Lighthouse.
  await login(page, 'https://example.com');

  // Pass the authenticated page to Lighthouse.
  // disableStorageReset preserves the login session.
  const result = await lighthouse(
    'https://example.com/dashboard',
    { disableStorageReset: true },
    undefined,
    page
  );

  await browser.close();
  console.log(JSON.stringify(result.lhr, null, 2));
}

await main();

Pass disableStorageReset: true to Lighthouse when reusing a Puppeteer page. Without it, Lighthouse will clear storage on startup and your session will be lost before the audit begins.

Option 2: Use Chrome DevTools

The Lighthouse panel in Chrome DevTools never clears cookies. Log in to your site normally, then open the Lighthouse panel and run an audit.

If your authentication depends on localStorage or indexedDB, uncheck Clear storage in the Lighthouse panel settings before running.

Option 3: Pass custom request headers

Use the --extra-headers flag to inject an Authorization header or any other header your server requires.

CLI

lighthouse https://example.com \
  --extra-headers="{\"Authorization\":\"Bearer YOUR_TOKEN\"}"

import lighthouse from 'lighthouse';

const result = await lighthouse('https://example.com', {
  extraHeaders: {
    Authorization: 'Bearer YOUR_TOKEN',
  },
});

{
  "Authorization": "Bearer YOUR_TOKEN"
}

You can pass a path to a JSON file instead of an inline string:

lighthouse https://example.com --extra-headers=./headers.json

Setting the Cookie header via --extra-headers overrides all other cookies for the session. For cookie-based authentication with multiple cookies, use the Puppeteer approach (Option 1) instead.

Option 4: Open a debug Chrome instance and log in manually

This approach works when you need to authenticate interactively, such as with SSO or multi-factor authentication.

1. Install Lighthouse globally

   npm install -g lighthouse
   

   This adds the chrome-debug binary to your PATH.

2. Launch the debug Chrome instance

   chrome-debug
   

   The command prints the debugging port number that Chrome is listening on.

3. Log in to your site

   In the Chrome window that opens, navigate to your site and complete the login process.

4. Run Lighthouse against the authenticated session

   In a separate terminal, run Lighthouse using the port number from step 2:

   lighthouse https://example.com/dashboard \
     --disable-storage-reset \
     --port=9222
   

   Replace 9222 with the port printed by chrome-debug.

Choosing the right approach

Approach	Best for
Puppeteer scripting	Automated pipelines, form-based login
Chrome DevTools	Manual one-off audits
--extra-headers	Token or API key authentication
chrome-debug + manual login	SSO, MFA, or complex login flows