lhci assert: Gate Builds on Lighthouse Scores
lhci assert checks collected Lighthouse results against category-score and audit thresholds, exiting non-zero when an assertion fails.
Assertions are how Lighthouse CI becomes a quality gate. You declare the minimum scores or metric budgets, and lhci assert (or the assert phase of autorun) fails the build when a result regresses below them.
What it does
lhci assert reads the Lighthouse results from the most recent collect and evaluates the assertions block: category scores (categories:performance), specific audits, and budgets. Each assertion has a level of warn or error; an error-level failure exits non-zero.
Common usage
lhci assert --preset=lighthouse:recommended
# custom assertions in lighthouserc.json
# "assert": {
# "assertions": {
# "categories:performance": ["error", { "minScore": 0.9 }],
# "categories:accessibility": ["error", { "minScore": 1 }],
# "first-contentful-paint": ["warn", { "maxNumericValue": 2000 }]
# }
# }Options
| Assertion | What it does |
|---|---|
| categories:performance | Assert the performance category score |
| minScore: 0.9 | Minimum category score (0 to 1) |
| maxNumericValue: 2000 | Cap on a metric (ms, bytes, etc.) |
| ["error", {...}] | error fails the build; warn only logs |
| --preset | lighthouse:recommended or lighthouse:no-pwa |
| assertMatrix | Different assertions per URL pattern |
In CI
Start from --preset=lighthouse:recommended, then relax individual assertions to warn where you cannot yet pass, rather than disabling the gate entirely. Set accessibility to minScore 1 with level error so any new a11y regression fails the PR.
Common errors in CI
"Error: Assertions failed. N result(s) ..." with a per-assertion table is the gate firing; read which category or audit fell below threshold. "Error: No Lighthouse results to assert against" means assert ran without a prior collect (run lhci collect or use lhci autorun). An assertion on an audit id that does not exist is silently skipped, which can hide a typo in the audit name.