@wiredbydesign/web-tests

Reusable Lighthouse CI testing component with automatic sitemap discovery and flexible device configuration.

Features

• 🔍 Automatic URL Discovery - Discovers URLs from sitemaps, URL lists, glob patterns, or custom functions
• 📱 Device Agnostic - Configure any device types and screen sizes (no hardcoded defaults)
• 🌐 Remote & Local - Test both local development servers and remote production sites
• 📊 Rich Reports - Generates Markdown and HTML summary reports
• 🔧 Highly Configurable - Flexible configuration via files, CLI args, or environment variables
• 🗂️ Domain-Based Output - Automatically organizes results by domain/URL to prevent overwrites when testing multiple sites

Installation

npm install @wiredbydesign/web-tests

Or use as a git dependency:

{
  "dependencies": {
    "@wiredbydesign/web-tests": "git+https://github.com/your-org/web-tests.git"
  }
}

Quick Start

1. Start your web server (the package doesn't manage servers):

# Example: using serve
serve -l 4321 dist

# Or use your own server command
npm run preview

2. Create a config file (web-tests.config.js):

module.exports = {
  sites: [
    {
      name: 'Local Dev',
      urls: {
        baseUrl: 'http://localhost:4321', // REQUIRED: point at your running server
        source: 'sitemap'
      }
    }
  ],
  devices: [
    {
      name: 'desktop',
      preset: 'desktop'
    },
    {
      name: 'mobile',
      formFactor: 'mobile',
      screenWidth: 412,
      screenHeight: 843,
      deviceScaleFactor: 1.75
    }
  ],
  thresholds: {
    performance: 0.8,
    accessibility: 0.9,
    'best-practices': 0.9,
    seo: 0.9,
    pwa: 'off'
  }
};

3. Run tests (in another terminal):

npx web-tests --config web-tests.config.js

Configuration

Sites Configuration (REQUIRED)

You must provide a sites array with at least one site. Each site defines its own URL discovery configuration.

sites: [
  {
    name: 'Local Dev', // Optional but recommended
    urls: {
      baseUrl: 'http://localhost:4321', // REQUIRED
      source: 'sitemap' // 'sitemap' | 'urls' | 'custom'
    }
  }
]

For Single Site: Provide an array with one entry.
For Multiple Sites: Add more entries to test sequentially.

URL Discovery

Each site in the sites array has a urls configuration:

From Sitemap (Recommended)

sites: [
  {
    name: 'My Site',
    urls: {
      source: 'sitemap',
      baseUrl: 'http://localhost:4321',
      // Optional: specify exact sitemap path, otherwise tries multiple common paths
      sitemapPath: '/sitemap-index.xml',
      // Optional: specify custom paths to try (default: ['/sitemap.xml', '/sitemap-index.xml', '/sitemap-0.xml'])
      // sitemapPaths: ['/sitemap.xml', '/custom-sitemap.xml']
    }
  }
]

Automatic Sitemap Discovery: If sitemapPath is not specified, the package will automatically try multiple common sitemap paths:

• /sitemap.xml
• /sitemap-index.xml
• /sitemap-0.xml

Redirect Support: The package automatically follows HTTP redirects (301, 302, 307, 308) when fetching sitemaps.

Sitemap Index Support: The package automatically follows references in sitemap index files to discover all URLs across multiple sitemap files.

From URL List

sites: [
  {
    name: 'My Site',
    urls: {
      source: 'urls',
      baseUrl: 'http://localhost:4321',
      urlList: ['/', '/about', '/contact']
    }
  }
]

Custom Function

sites: [
  {
    name: 'My Site',
    urls: {
      source: 'custom',
      baseUrl: 'http://localhost:4321',
      customFn: () => {
        // Your custom logic
        return ['/', '/about'];
      }
    }
  }
]

Multiple Sites Example

You can test multiple sites sequentially by adding more entries to the sites array:

module.exports = {
  // Base configuration (shared by all sites unless overridden)
  devices: [
    { name: 'desktop', preset: 'desktop' },
    { name: 'mobile', formFactor: 'mobile', screenWidth: 412, screenHeight: 843 }
  ],
  thresholds: {
    performance: 0.8,
    accessibility: 0.9,
    'best-practices': 0.9,
    seo: 0.9
  },
  outputDir: '.lighthouse',

  // Multiple sites to test sequentially
  sites: [
    {
      name: 'Production',
      urls: {
        baseUrl: 'https://wiredby.design',
        source: 'sitemap'
      }
      // Uses base devices and thresholds
    },
    {
      name: 'Staging',
      urls: {
        baseUrl: 'https://staging.wiredby.design',
        source: 'sitemap'
      },
      thresholds: {
        performance: 0.7, // Lower threshold for staging
        accessibility: 0.9,
        'best-practices': 0.9,
        seo: 0.9
      }
    },
    {
      name: 'Local Dev',
      urls: {
        baseUrl: 'http://localhost:4321',
        source: 'sitemap'
      }
    }
  ]
};

Key Points:

• Each site in the sites array can override any base configuration (devices, thresholds, etc.)
• Sites are tested sequentially (one after another)
• Results are automatically organized by domain: .lighthouse/{domain}/{device}/
• Each site must have its server running before testing begins
• The name field is optional but recommended for better logging

Device Configuration

Important: Devices are passed as parameters - no hardcoded defaults. You must configure at least one device.

devices: [
  {
    name: 'desktop',
    preset: 'desktop'  // Uses Lighthouse desktop preset
  },
  {
    name: 'mobile',
    formFactor: 'mobile',
    screenWidth: 412,
    screenHeight: 843,
    deviceScaleFactor: 1.75
  },
  {
    name: 'tablet',
    formFactor: 'mobile',  // Lighthouse uses 'mobile' for non-desktop
    screenWidth: 768,
    screenHeight: 1024,
    deviceScaleFactor: 2
  },
  {
    name: 'custom-large',
    preset: 'desktop',
    screenWidth: 2560,
    screenHeight: 1440,
    deviceScaleFactor: 1
  }
]

Device Config Options:

• name (required) - Unique identifier for the device
• preset - Lighthouse preset ('desktop' or 'mobile')
• formFactor - 'mobile' or 'desktop'
• screenWidth - Screen width in pixels
• screenHeight - Screen height in pixels
• deviceScaleFactor - Device pixel ratio

Thresholds

thresholds: {
  performance: 0.8,      // 80% minimum
  accessibility: 0.9,   // 90% minimum
  'best-practices': 0.9, // 90% minimum (or use bestPractices)
  seo: 0.9,            // 90% minimum
  pwa: 'off'           // 'off' or number like 0.8
}

Output Directory Structure

Results are automatically organized by domain to prevent overwrites when testing multiple sites:

.lighthouse/
├── localhost-4321/          # Results for http://localhost:4321
│   ├── desktop/
│   │   ├── -report.json
│   │   ├── -report.html
│   │   └── summary.html
│   └── mobile/
│       ├── -report.json
│       └── summary.html
├── wiredby.design/          # Results for https://wiredby.design
│   ├── desktop/
│   └── mobile/
└── example.com/             # Results for https://example.com
    ├── desktop/
    └── mobile/

The domain name is automatically extracted from the baseUrl in your configuration:

• http://localhost:4321 → localhost-4321
• https://wiredby.design → wiredby.design
• http://127.0.0.1:8080 → 127.0.0.1-8080

This allows you to run tests against multiple sites without results overwriting each other.

Usage

CLI

# With config file
web-tests --config web-tests.config.js

# With environment variables
WEB_TESTS_DEVICES='[{"name":"desktop","preset":"desktop"}]' \
WEB_TESTS_SITES='[{"name":"Local","urls":{"baseUrl":"http://localhost:4321","source":"sitemap"}}]' \
web-tests

Programmatic API

const WebTestsRunner = require('@wiredbydesign/web-tests');

const runner = new WebTestsRunner({
  sites: [
    {
      name: 'Local Dev',
      urls: {
        baseUrl: 'http://localhost:4321',
        source: 'sitemap'
      }
    }
  ],
  devices: [
    { name: 'desktop', preset: 'desktop' },
    { name: 'mobile', formFactor: 'mobile', screenWidth: 412, screenHeight: 843 }
  ],
  thresholds: {
    performance: 0.8,
    accessibility: 0.9,
    'best-practices': 0.9,
    seo: 0.9
  }
});

const results = await runner.run();

GitHub Actions

name: Lighthouse Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Build
        run: npm run build
      
      - name: Install dependencies
        run: npm install @wiredbydesign/web-tests @lhci/cli
      
      - name: Run Lighthouse tests
        run: npx web-tests --config web-tests.config.js
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

Output

Reports are saved to .lighthouse/ directory (configurable via outputDir):

.lighthouse/
├── desktop/
│   ├── -report.json
│   ├── -report.html
│   ├── about-report.json
│   ├── about-report.html
│   └── summary.html
└── mobile/
    ├── -report.json
    └── ...

Requirements

• Node.js >= 14.0.0
• @lhci/cli (installed automatically as dependency)
• A running web server (start your server separately before running tests)

License

MIT