playwright-lighthouse

Lighthouse opens a new page for its audit, which means it does not automatically share the authentication state (cookies/localStorage) of your current Playwright page.

To audit authenticated routes, you must use a persistent context (launchPersistentContext). This ensures that when Lighthouse opens a new page, the storage/session is persisted and available.

import os from 'os';
import path from 'path';
import { playAudit } from 'playwright-lighthouse';
import { chromium } from 'playwright';

describe('audit example', () => {
  it('open browser', async () => {
    const userDataDir = path.join(os.tmpdir(), 'pw', String(Math.random()));
    const context = await chromium.launchPersistentContext(userDataDir, {
      args: ['--remote-debugging-port=9222'],
    });
    const page = await context.newPage();
    await page.goto('http://localhost:3000/');

    // Perform login steps here which will save to cookie or localStorage

    await playAudit({
      page: page,
      port: 9222,
    });

    await context.close();
  });
});

You can execute Lighthouse audits on the LambdaTest platform while running Playwright tests. This allows you to generate multiple reports within a single test execution on their infrastructure.

Prerequisites

1. Install the library:

   npm install playwright-lighthouse

2. Set the LIGHTHOUSE_LAMBDATEST environment variable to true in your project environment:

   export LIGHTHOUSE_LAMBDATEST='true'

Implementation Pattern

Connect to LambdaTest using chromium.connect with the appropriate capabilities, perform your browser actions, and then call playAudit. You can use page.evaluate to communicate the test status (passed/failed) back to the LambdaTest dashboard based on whether playAudit meets your defined thresholds.

import { chromium } from 'playwright';
import { playAudit } from 'playwright-lighthouse';

(async () => {
  let browser, page;
  try {
    const capabilities = {
      browserName: 'Chrome', // Browsers allowed: `Chrome`, `MicrosoftEdge` and `pw-chromium`
      browserVersion: 'latest',
      'LT:Options': {
        platform: 'Windows 11',
        build: 'Web Performance testing',
        name: 'Lighthouse test',
        user: process.env.LT_USERNAME,
        accessKey: process.env.LT_ACCESS_KEY,
        network: true,
        video: true,
        console: true,
      },
    };

    browser = await chromium.connect({
      wsEndpoint: `wss://cdp.lambdatest.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
    });

    page = await browser.newPage();

    await page.goto('https://duckduckgo.com');
    // ... perform actions ...

    try {
      await playAudit({
        url: 'https://duckduckgo.com',
        page: page,
        thresholds: {
          performance: 50,
          accessibility: 50,
          'best-practices': 50,
          seo: 50,
          pwa: 10,
        },
        reports: {
          formats: {
            json: true,
            html: true,
            csv: true,
          },
        },
      });

      await page.evaluate(
        (_) => {},
        `lambdatest_action: ${JSON.stringify({ action: 'setTestStatus', arguments: { status: 'passed', remark: 'Web performance metrics are are above the thresholds.' } })}`
      );
    } catch (e) {
      await page.evaluate(
        (_) => {},
        `lambdatest_action: ${JSON.stringify({ action: 'setTestStatus', arguments: { status: 'failed', remark: e.stack } })}`
      );
      console.error(e);
    }
  } catch (e) {
    await page.evaluate(
      (_) => {},
      `lambdatest_action: ${JSON.stringify({ action: 'setTestStatus', arguments: { status: 'failed', remark: e.stack } })}`
    );
  } finally {
    await page.close();
    await browser.close();
  }
})();

To use playwright-lighthouse with the Playwright Test Runner (especially for parallel execution), you should extend the test base with a custom fixture that assigns a unique port to each worker using get-port.

For authenticated routes in the test runner, use launchPersistentContext within a fixture to ensure the Lighthouse audit can access the session.

import { chromium } from 'playwright';
import type { Browser } from 'playwright';
import { playAudit } from 'playwright-lighthouse';
import { test as base } from '@playwright/test';
import getPort from 'get-port';

export const lighthouseTest = base.extend<{}, { port: number; browser: Browser }>({
  port: [
    async ({}, use) => {
      const port = await getPort();
      await use(port);
    },
    { scope: 'worker' },
  ],

  browser: [
    async ({ port }, use) => {
      const browser = await chromium.launch({
        args: [`--remote-debugging-port=${port}`],
      });
      await use(browser);
    },
    { scope: 'worker' },
  ],
});

lighthouseTest.describe('Lighthouse', () => {
  lighthouseTest('should pass lighthouse tests', async ({ page, port }) => {
    await page.goto('http://example.com');
    await page.waitForSelector('#some-element');
    await playAudit({
      page,
      port,
    });
  });
});

By default, playAudit will fail the test if any Lighthouse metric score is below 100. You can customize these thresholds by passing a thresholds object.

Available metric keys include:

• performance
• accessibility
• best-practices
• seo
• pwa

If a score falls below the value specified in the thresholds object, the test will fail.

import { playAudit } from 'playwright-lighthouse';
import playwright from 'playwright';

describe('audit example', () => {
  it('open browser', async () => {
    const browser = await playwright['chromium'].launch({
      args: ['--remote-debugging-port=9222'],
    });
    const page = await browser.newPage();
    await page.goto('https://angular.io/');

    await playAudit({
      page: page,
      thresholds: {
        performance: 50,
        accessibility: 50,
        'best-practices': 50,
        seo: 50,
        pwa: 50,
      },
      port: 9222,
    });

    await browser.close();
  });
});

The lighthouse() function is the primary entrypoint for running Lighthouse audits within a Playwright environment. It executes the audit on a provided page and url, compares the resulting scores against defined thresholds, and can generate various report formats.

Parameters

Return Value

Returns a Promise that resolves to an object containing:

• comparison: An object with errors (thresholds not met) and results (thresholds met).
• results: The full Lighthouse Result object (lhr).

import { lighthouse } from 'playwright-lighthouse';

const results = await lighthouse({
  page, // Playwright Page instance
  url: 'https://example.com',
  thresholds: {
    performance: 90,
    accessibility: 90,
    best-practices: 90,
    seo: 90,
    pwa: 90
  },
  reports: {
    formats: { html: true, json: true },
    directory: './reports',
    name: 'my-audit'
  }
});