# Screenshots

> Check that pages look as designed: the page, or one element of it, compared with a screenshot taken before, pixel by pixel, as Playwright compares them (small differences of color and anti-aliased edges aside). It builds on the `web-core` pack.

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

Check that pages look as designed: the page, or one element of it, compared with a screenshot taken before, pixel by pixel, as Playwright compares them (small differences of color and anti-aliased edges aside). It builds on the `web-core` pack.

The screenshots are files of the project, `screenshots/<name>.<engine>-<platform>.png`: browsers draw pages differently on each operating system, so each engine and platform has its own, compared on that platform only. The first time, a step takes its screenshot and fails: look at it, and keep it.

```yaml
packs:
  web-screenshots:
    platforms: [linux, darwin] # the platforms whose screenshots you keep
```

With `platforms`, the steps compare on those platforms (`linux`, `darwin`, `windows`), each with its own screenshots, and pass elsewhere, saying so. `update: true` takes the screenshots of the platform it runs on again.

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

## Settings

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

| Setting | Takes | Values | Default |
|---|---|---|---|
| `folder` | The folder of the screenshots, in the project. Unset, each feature keeps its screenshots in a screenshots folder next to its file. | text | |
| `platforms` | The platforms whose screenshots the project keeps: each compares its own; elsewhere the steps pass without comparing (default: every platform). | a list of `linux`, `darwin`, `windows` | |
| `tolerance` | The share of a screenshot's pixels that may differ. | a number, 0 to 1 | `0` |
| `update` | Take every screenshot again, as the page looks now, instead of comparing. | `true`, `false` | |

## Steps

### `web-screenshots.page`

```gherkin
Then [[within {duration} ]]the page looks like the {string} screenshot
```

Check that the page looks like its screenshot, pixel by pixel (anti-aliasing aside).

- The screenshot is `<name>.<engine>-<platform>.png`, in a `screenshots` folder next to the feature file. Without one, the step takes it and fails: look at it, and keep it.
- When the page looks different, the step attaches the screenshot, the page and their difference.
- The check waits for the page to settle and look right: 10 seconds, or `within {duration}`.
- On a platform `platforms` leaves out, the step passes without comparing.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out | `"Get a quote"`, `'Express'` |

**Variants**, the parts in `[[...]]` said or left out:

- `the page looks like the {string} screenshot`
- `within {duration} the page looks like the {string} screenshot`

**Example:**

```gherkin
Then the page looks like the "quote" screenshot
```

_Since 0.1.1._

### `web-screenshots.page.masked`

```gherkin
Then [[within {duration} ]]the page looks like the {string} screenshot, apart from:
  | element |
```

Check that the page looks like its screenshot, apart from what changes from run to run, such as a date, painted over in both.

- The screenshot is `<name>.<engine>-<platform>.png`, in a `screenshots` folder next to the feature file. Without one, the step takes it and fails: look at it, and keep it.
- When the page looks different, the step attaches the screenshot, the page and their difference.
- The check waits for the page to settle and look right: 10 seconds, or `within {duration}`.
- On a platform `platforms` leaves out, the step passes without comparing.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out | `"Get a quote"`, `'Express'` |

An element a row: by its text or label, or a selector like `css=time`.

**Variants**, the parts in `[[...]]` said or left out:

- `the page looks like the {string} screenshot, apart from:`
- `within {duration} the page looks like the {string} screenshot, apart from:`

**Example:**

```gherkin
Then the page looks like the "parcel" screenshot, apart from:
  | css=time |
```

_Since 0.1.1._

### `web-screenshots.element`

```gherkin
Then [[within {duration} ]]the {string} {element} looks like the {string} screenshot
```

Check that one element, by its name or a selector, looks like its screenshot.

- The screenshot is `<name>.<engine>-<platform>.png`, in a `screenshots` folder next to the feature file. Without one, the step takes it and fails: look at it, and keep it.
- When the page looks different, the step attaches the screenshot, the page and their difference.
- The check waits for the page to settle and look right: 10 seconds, or `within {duration}`.
- On a platform `platforms` leaves out, the step passes without comparing.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) |  | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{element}` | a kind of element on the page, plural after a number (`buttons`): a `field` by its label or placeholder, an `option` is a radio button, an `element` is anything, by its text, label, alternative text or title | `button`, `field`, `checkbox`, `option`, `link`, `tab`, `menu item`, `element` | `button`, `field` |

**Variants**, the parts in `[[...]]` said or left out:

- `the {string} {element} looks like the {string} screenshot`
- `within {duration} the {string} {element} looks like the {string} screenshot`

**Example:**

```gherkin
Then the "css=.quote-card" element looks like the "quote card" screenshot
```

_Since 0.1.1._