Core Auditing

/**
 * Run Lighthouse audit on a URL
 * @param url - URL to test (optional if running in audit mode)
 * @param flags - Optional runtime settings and configuration flags
 * @param config - Configuration for the Lighthouse run
 * @param page - Puppeteer page instance for testing
 * @returns Promise resolving to RunnerResult with audit results
 */
function lighthouse(
  url?: string,
  flags?: LH.Flags,
  config?: LH.Config,
  page?: LH.Puppeteer.Page
): Promise<LH.RunnerResult | undefined>;

import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

// Basic audit
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const result = await lighthouse('https://example.com', {
  logLevel: 'info',
  output: 'json',
  port: chrome.port,
});
console.log('Performance score:', result.lhr.categories.performance.score);
await chrome.kill();

// With custom configuration
const customConfig = {
  extends: 'lighthouse:default',
  settings: {onlyCategories: ['performance', 'accessibility']},
};

const result = await lighthouse('https://example.com', {
  port: chrome.port,
}, customConfig);

/**
 * Run navigation-based audit on a page
 * @param page - Puppeteer page instance (optional)
 * @param requestor - Navigation target (URL string or navigation function)
 * @param options - Configuration and flags for the audit
 * @returns Promise resolving to RunnerResult with navigation audit results
 */
function navigation(
  page?: LH.Puppeteer.Page,
  requestor?: LH.NavigationRequestor,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<LH.RunnerResult | undefined>;

import { navigation } from 'lighthouse';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigation audit with URL
const result = await navigation(page, 'https://example.com', {
  flags: {logLevel: 'info'},
  config: {settings: {onlyCategories: ['performance']}},
});

// Navigation audit with custom navigation function
const result = await navigation(page, async () => {
  await page.goto('https://example.com');
  await page.waitForSelector('.main-content');
}, {
  flags: {throttlingMethod: 'simulate'},
});

await browser.close();

/**
 * Start timespan measurement session
 * @param page - Puppeteer page instance where measurements will occur
 * @param options - Configuration and flags for the timespan measurement
 * @returns Promise resolving to object with endTimespan function
 */
function startTimespan(
  page: LH.Puppeteer.Page,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<{ endTimespan: () => Promise<LH.RunnerResult | undefined> }>;

import { startTimespan } from 'lighthouse';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// Measure user interaction
const session = await startTimespan(page, {
  flags: {logLevel: 'info'},
});

// Perform user interactions
await page.click('.search-button');
await page.type('input[type="search"]', 'lighthouse');
await page.keyboard.press('Enter');
await page.waitForSelector('.search-results');

// End measurement and get results
const result = await session.endTimespan();
console.log('CLS during interaction:', result.lhr.audits['cumulative-layout-shift'].score);

await browser.close();

/**
 * Take snapshot audit of current page state
 * @param page - Puppeteer page instance to audit
 * @param options - Configuration and flags for the snapshot audit
 * @returns Promise resolving to RunnerResult with snapshot audit results
 */
function snapshot(
  page: LH.Puppeteer.Page,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<LH.RunnerResult | undefined>;

import { snapshot } from 'lighthouse';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// Take snapshot after page interactions
await page.evaluate(() => {
  // Modify page state
  document.body.classList.add('dark-theme');
});

const result = await snapshot(page, {
  flags: {logLevel: 'info'},
  config: {settings: {onlyCategories: ['accessibility', 'best-practices']}},
});

console.log('Accessibility score:', result.lhr.categories.accessibility.score);
await browser.close();

/**
 * Get list of available audits
 * @returns Array of audit definitions with metadata
 */
function getAuditList(): LH.Config.AuditDefn[];

import { getAuditList } from 'lighthouse';

// Get all available audits
const audits = getAuditList();
console.log('Available audits:', audits.map(audit => audit.path));

// Filter audits by category
const performanceAudits = audits.filter(audit => 
  audit.options && audit.options.category === 'performance'
);

interface LH.Flags {
  // Core options
  port?: number;                    // Chrome debugging port
  hostname?: string;                // Chrome debugging hostname  
  output?: LH.OutputMode | LH.OutputMode[]; // Output format(s)
  outputPath?: string;              // Output file path
  view?: boolean;                   // Open report in browser
  configPath?: string;              // Path to config file
  preset?: 'perf' | 'desktop';      // Quick preset configs
  
  // Chrome options
  chromeFlags?: string | string[];  // Chrome browser flags
  maxWaitForLoad?: number;          // Navigation timeout (ms)
  
  // Throttling options
  throttlingMethod?: 'provided' | 'devtools' | 'simulate';
  throttling?: LH.ThrottlingSettings;
  
  // Audit filtering
  onlyAudits?: string[];            // Run only specified audits
  skipAudits?: string[];            // Skip specified audits
  onlyCategories?: string[];        // Run only specified categories
  
  // Other options
  logLevel?: 'silent' | 'error' | 'info' | 'verbose';
  enableErrorReporting?: boolean;   // Enable error reporting to Google
}

type LH.NavigationRequestor = string | (() => Promise<void>);

// URL string requestor
const urlRequestor = 'https://example.com';

// Function requestor for complex navigation
const functionRequestor = async () => {
  await page.goto('https://example.com/login');
  await page.type('#username', 'testuser');
  await page.type('#password', 'password');
  await page.click('#login-button');
  await page.waitForNavigation();
};

try {
  const result = await lighthouse('https://example.com', flags);
  
  // Check for runtime errors
  if (result.lhr.runtimeError) {
    console.error('Runtime error:', result.lhr.runtimeError);
  }
  
  // Check for run warnings
  if (result.lhr.runWarnings.length > 0) {
    console.warn('Run warnings:', result.lhr.runWarnings);
  }
  
} catch (error) {
  console.error('Lighthouse error:', error.message);
}