# 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)