dodyg/lighthouse-scanner

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

| Config File | Format | |------------|--------| | lighthouserc.js | JavaScript module | | lighthouserc.json | JSON | | .lighthouserc.js | JavaScript module (dotfile) | | .lighthouserc.json | JSON (dotfile) | | .lighthouserc.yml | YAML (dotfile) |

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"
    }
  }
}

| Section | Purpose | Agent Use | |---------|---------|-----------| | ci.collect.url | URLs to audit | Scope of CI scanning | | ci.collect.numberOfRuns | How many times to run each URL | Reliability indicator | | ci.assert.assertions | Score budgets and thresholds | Regression detection | | ci.upload.target | Where to store reports | Report retrieval |

Parsing Lighthouse Accessibility Results

Accessibility Score

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

| Score Range | Grade | Interpretation | |-------------|-------|---------------| | 90-100 | A | Good accessibility | | 70-89 | B-C | Some issues to address | | 50-69 | D | Significant issues | | 0-49 | F | Critical accessibility failures |

Individual Audit Results

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

| Audit ID | axe-core Rule | WCAG Criterion | Weight | |----------|--------------|----------------|--------| | image-alt | image-alt | 1.1.1 | 10 | | color-contrast | color-contrast | 1.4.3 | 7 | | label | label | 1.3.1 | 7 | | button-name | button-name | 4.1.2 | 7 | | link-name | link-name | 2.4.4 | 7 | | html-has-lang | html-has-lang | 3.1.1 | 7 | | document-title | document-title | 2.4.2 | 7 | | heading-order | heading-order | 1.3.1 | 3 | | meta-viewport | meta-viewport | 1.4.4 | 10 | | bypass | bypass | 2.4.1 | 7 | | tabindex | tabindex | 2.4.3 | 7 | | aria-allowed-attr | aria-allowed-attr | 4.1.2 | 10 | | aria-hidden-body | aria-hidden-body | 4.1.2 | 10 | | aria-required-attr | aria-required-attr | 4.1.2 | 10 | | aria-roles | aria-roles | 4.1.2 | 7 | | aria-valid-attr-value | aria-valid-attr-value | 4.1.2 | 7 | | aria-valid-attr | aria-valid-attr | 4.1.2 | 10 |

Severity Mapping

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

| Lighthouse Weight | Audit Status | Agent Severity | |------------------|-------------|---------------| | 10 | Fail | Critical | | 7 | Fail | Serious | | 3 | Fail | Moderate | | 1 | Fail | Minor | | Any | Pass | N/A (not reported) |

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

| Scenario | Interpretation | Action | |----------|---------------|--------| | Found by Lighthouse AND local scan | High confidence | Report as high confidence, full severity weight | | Found by Lighthouse only | Environment-specific | Report as medium confidence, note "CI-only finding" | | Found by local scan only | Not covered by Lighthouse subset | Report as medium confidence, note "local-only finding" | | Lighthouse score regressed | New accessibility issues introduced | Flag as regression, prioritize in report |

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

| Delta | Severity | Action | |-------|----------|--------| | Score drops 10+ points | Critical | Immediate attention, likely multiple new violations | | Score drops 5-9 points | Serious | New violations introduced, review before merge | | Score drops 1-4 points | Moderate | Minor regression, track for follow-up | | Score unchanged or improved | N/A | No regression detected |

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

| Input | Required | Description | |-------|----------|-------------| | urls | Yes (or in config) | Newline-separated URLs to audit | | configPath | No | Path to Lighthouse CI config file | | uploadArtifacts | No | Upload HTML reports as workflow artifacts | | temporaryPublicStorage | No | Upload to temporary public storage for sharing | | runs | No | Number of runs per URL (default: 1) | | budgetPath | No | Path to a Lighthouse budget JSON file |

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