Skip to main content
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('[email protected]');
  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. 
lighthouse https://example.com \
  --extra-headers="{\"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

ApproachBest for
Puppeteer scriptingAutomated pipelines, form-based login
Chrome DevToolsManual one-off audits
--extra-headersToken or API key authentication
chrome-debug + manual loginSSO, MFA, or complex login flows

Build docs developers (and LLMs) love

Get started for freeTalk to us