Lighthouse Scanner

name: lighthouse-scanner description: Integration patterns for Lighthouse CI accessibility auditing. Teaches agents how to detect Lighthouse CI configuration, parse accessibility audit results, map findings to the standard severity model, correlate with local axe-core scans, and track score regressions.

Lighthouse CI Accessibility Integration

What Is Lighthouse CI?

Lighthouse CI is a suite of tools for running Google Lighthouse audits in CI pipelines. The most common GitHub Actions integration uses treosh/lighthouse-ci-action.

Lighthouse provides:

• Performance, accessibility, best practices, and SEO scoring (0-100)
• Individual audit results with pass/fail status and detailed findings
• Score budgets and assertions to fail builds on regressions
• HTML and JSON report artifacts
• Score comparison across runs for trend tracking

Accessibility focus: The Lighthouse accessibility category runs a subset of axe-core rules and reports a weighted score from 0-100 along with individual audit violations.

Detecting Lighthouse CI Presence

Workflow File Detection

Search for workflow files referencing Lighthouse CI:

# Search for the treosh Lighthouse CI action
grep -rl "treosh/lighthouse-ci-action" .github/workflows/

# Search for official Lighthouse CI CLI usage
grep -rl "lhci autorun\|lighthouse-ci" .github/workflows/

Patterns to match in YAML:

- uses: treosh/lighthouse-ci-action@v12

Configuration File Detection

Lighthouse CI uses configuration files in the repository root:

# Check for Lighthouse CI config files
ls lighthouserc.js lighthouserc.json .lighthouserc.js .lighthouserc.json .lighthouserc.yml 2>/dev/null

Configuration Structure

Key fields in Lighthouse CI config:

{
  "ci": {
    "collect": {
      "url": ["https://example.com", "https://example.com/about"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", {"minScore": 0.9}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

Parsing Lighthouse Accessibility Results

Accessibility Score

Lighthouse computes a weighted accessibility score from 0-100 based on individual audit results.

Individual Audit Results

Each Lighthouse accessibility audit corresponds to an axe-core rule:

Severity Mapping

Lighthouse uses weights rather than impact levels. Map to the agent severity model based on weight and audit pass/fail:

Correlation with Local Scans

Lighthouse-to-axe-core Mapping

Since Lighthouse uses axe-core under the hood, correlation is straightforward:

1. Match by audit/rule ID: Lighthouse audit IDs correspond directly to axe-core rule IDs
2. Match by URL: Compare scanned URLs from Lighthouse config with local scan targets
3. Boost confidence: Findings confirmed by both Lighthouse CI and local axe-core scan receive high confidence

Source Comparison

Score Regression Detection

Track Lighthouse accessibility scores across runs to detect regressions:

Comparing Scores

{
  "url": "https://example.com",
  "previousScore": 95,
  "currentScore": 87,
  "delta": -8,
  "status": "regressed",
  "newFailures": ["color-contrast", "image-alt"],
  "newPasses": []
}

Regression Thresholds

Structured Output Format

When lighthouse-bridge normalizes Lighthouse data, it produces findings in this format:

{
  "source": "lighthouse-ci",
  "ruleId": "color-contrast",
  "wcagCriterion": "1.4.3",
  "wcagLevel": "AA",
  "severity": "serious",
  "confidence": "high",
  "url": "https://example.com/login",
  "element": "button.submit-btn",
  "description": "Element has insufficient color contrast ratio",
  "lighthouseWeight": 7,
  "lighthouseScore": {
    "overall": 87,
    "previousOverall": 95,
    "delta": -8,
    "status": "regressed"
  }
}

GitHub Actions Integration

treosh/lighthouse-ci-action

The most common Lighthouse CI GitHub Action:

- name: Run Lighthouse CI
  uses: treosh/lighthouse-ci-action@v12
  with:
    urls: |
      https://example.com
      https://example.com/about
    uploadArtifacts: true
    configPath: ./lighthouserc.json

Action Inputs

Extracting Results from Artifacts

Lighthouse CI uploads results as workflow artifacts. To retrieve scores:

1. Download the artifact from the workflow run
2. Parse the JSON report files
3. Extract categories.accessibility.score for the overall score
4. Extract individual audits.{audit-id} results for violations