# Lighthouse

> Audit a web app's pages with [Lighthouse](https://developer.chrome.com/docs/lighthouse), Google's tool for the quality of web pages. It builds on the `web-core` pack.

Source: https://axx.nimbusxr.us/references/packs/web-lighthouse/

Audit a web app's pages with [Lighthouse](https://developer.chrome.com/docs/lighthouse), Google's tool for the quality of web pages. It builds on the `web-core` pack.

- **Scores.** `the {string} page scores at least:` checks the page's Lighthouse scores, from 0 to 100: performance, accessibility, best practices and SEO. A score below its minimum fails the step, which says which audits cost the page the most.
- **Loading.** `the {string} page loads within:` checks how fast the page loads, by the Core Web Vitals and Lighthouse's other metrics: largest contentful paint, first contentful paint, total blocking time, speed index and cumulative layout shift.

Lighthouse loads the page afresh in a tab of its own, beside the scenario's, with the web app's cookies and storage: signed-in pages are audited signed in. As for a first visit, it clears the browser's cache and the site's service workers first, for the scenario's tabs too. It measures the page as a mid-range phone on a slow 4G connection loads it, or a desktop computer (`device`), simulating the device and the connection rather than slowing the browser down: an audit takes about 5 seconds. Performance varies with the machine's load, so the pack audits it three times and judges the median run, as Lighthouse recommends; still, leave some room. Each audit attaches Lighthouse's report, which the pack also keeps in `.axx/web/lighthouse`.

Lighthouse audits pages in Chromium, Chrome and Edge. The pack downloads Lighthouse 13.5.0 the first time, about 18 MB from npm's registry (`npm_config_registry` points it at a mirror), and runs it with the web-core pack's Node.js.

```yaml
packs:
  web-lighthouse:
    device: desktop    # mobile (the default) or desktop
```

Add it to a project with `axx pack add web-lighthouse`; it builds on [`web-core`](https://axx.nimbusxr.us/references/packs/web-core/), which comes with it.

## Settings

In `axx.yaml`, under `packs.web-lighthouse`:

| Setting | Takes | Values |
|---|---|---|
| `device` | The device Lighthouse audits pages as: mobile, a mid-range phone on a slow 4G connection (the default), or desktop, Lighthouse's desktop preset. | `mobile`, `desktop` |

## Steps

### `web-lighthouse.scores`

```gherkin
Then the {string} page scores at least:
  | category | score |
```

The table may start with the row naming its columns, as above, or go straight to its rows.

Audit a page of the web app with Lighthouse, a path below its `url` or a whole URL, and check its scores.

- Lighthouse audits the categories listed only, as the `device` of `packs.web-lighthouse` (a phone by default).
- With performance among the categories, Lighthouse audits the page three times, and the step judges the median run.
- A score below its minimum fails the step, which lists the audits that cost the page the most.
- Lighthouse's report is attached.

| Parameter | Takes | For example |
|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out | `"Get a quote"`, `'Express'` |

| Category | Takes |
|---|---|
| `performance` | the lowest score it may have, from 0 to 100 |
| `accessibility` | the lowest score it may have, from 0 to 100 |
| `best practices` | the lowest score it may have, from 0 to 100 |
| `seo` | the lowest score it may have, from 0 to 100 |

**Example:**

```gherkin
Then the "/quote" page scores at least:
  | performance    | 90  |
  | accessibility  | 100 |
  | best practices | 100 |
  | seo            | 100 |
```

_Since 0.1.1._

### `web-lighthouse.loads`

```gherkin
Then the {string} page loads within:
  | metric | limit |
```

The table may start with the row naming its columns, as above, or go straight to its rows.

Audit how fast a page of the web app loads with Lighthouse, a path below its `url` or a whole URL, and check its metrics.

- Lighthouse measures the page as the `device` of `packs.web-lighthouse` would load it (a phone on a slow 4G connection by default).
- Lighthouse audits the page three times, and the step judges the median run: a load's metrics vary with the machine's load.
- A metric above its limit fails the step, which lists what would bring it down.
- Lighthouse's report is attached.

| Parameter | Takes | For example |
|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out | `"Get a quote"`, `'Express'` |

| Metric | Takes |
|---|---|
| `largest contentful paint` | the longest it may take, like `2.5s` (a Core Web Vital) |
| `cumulative layout shift` | the most it may be, a number like `0.1` (a Core Web Vital) |
| `first contentful paint` | the longest it may take, like `1.8s` |
| `total blocking time` | the longest it may be, like `200ms` |
| `speed index` | the longest it may take, like `3.4s` |

**Example:**

```gherkin
Then the "/quote" page loads within:
  | largest contentful paint | 2.5s  |
  | total blocking time      | 200ms |
  | cumulative layout shift  | 0.1   |
```

_Since 0.1.1._