astro-website/site/docs/lighthouse.md

Lighthouse Quality Gate

This project provides a deterministic Lighthouse runner for the required variants:

• mobile + light
• mobile + dark
• mobile + high-contrast
• desktop + light
• desktop + dark
• desktop + high-contrast

Commands

• npm run lighthouse:run
  • runs Lighthouse and writes JSON reports to site/lighthouse-reports/
• npm run verify:lighthouse
  • same as above, but fails if any median category score is below 100

Run Environment Requirements

• Use a clean Chrome environment (no extensions).
• Default target URL is http://127.0.0.1:4321/.
• The runner starts astro preview automatically for local URLs.
• To run against production explicitly, pass --url=https://santhoshj.com/.

Scoring Rule

• The runner executes 3 runs per variant by default.
• For each category (performance, accessibility, best-practices, seo), it records per-run scores.
• The quality gate uses the median score for each category per variant.
• verify:lighthouse requires all medians to equal 100.

Gate Scope (Deterministic By Design)

• The default gate target is the home page (/).
• The home page shell is the deterministic quality gate surface and is expected to avoid third-party above-the-fold image dependencies.
• If additional URLs are added to the gate, they should follow the same deterministic rule for above-the-fold media.

Useful Options

• --url=<url>: target URL
• --runs=<n>: run count per variant
• --out=<path>: report output directory
• --assert-100: enable gate failure when any median is below 100

Environment variable equivalents:

• LIGHTHOUSE_TARGET_URL
• LIGHTHOUSE_RUNS
• LIGHTHOUSE_OUTPUT_DIR
• LIGHTHOUSE_SKIP_PREVIEW=true (skip auto-starting preview)