> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
npm install puppeteer lighthouse
```

```js theme={null}
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('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(),
  ]);
}

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();
```

<Warning>
  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.
</Warning>

## 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.

<CodeGroup>
  ```bash CLI theme={null}
  lighthouse https://example.com \
    --extra-headers="{\"Authorization\":\"Bearer YOUR_TOKEN\"}"
  ```

  ```js Node theme={null}
  import lighthouse from 'lighthouse';

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

  ```json Header file (headers.json) theme={null}
  {
    "Authorization": "Bearer YOUR_TOKEN"
  }
  ```
</CodeGroup>

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

```bash theme={null}
lighthouse https://example.com --extra-headers=./headers.json
```

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="Install Lighthouse globally">
    ```bash theme={null}
    npm install -g lighthouse
    ```

    This adds the `chrome-debug` binary to your PATH.
  </Step>

  <Step title="Launch the debug Chrome instance">
    ```bash theme={null}
    chrome-debug
    ```

    The command prints the debugging port number that Chrome is listening on.
  </Step>

  <Step title="Log in to your site">
    In the Chrome window that opens, navigate to your site and complete the
    login process.
  </Step>

  <Step title="Run Lighthouse against the authenticated session">
    In a separate terminal, run Lighthouse using the port number from step 2:

    ```bash theme={null}
    lighthouse https://example.com/dashboard \
      --disable-storage-reset \
      --port=9222
    ```

    Replace `9222` with the port printed by `chrome-debug`.
  </Step>
</Steps>

## 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      |