# Recipe file

One YAML file per screenshot, in `paths.recipes`. The filename is the recipe's name unless `name` says otherwise.

screenshots/recipes/order-row.yaml

```
name: order-row
install: guide
url: http://localhost:4321/orders

setup:
  - click: { role: link, name: Orders }

clip: { css: '.order-row', contains: Acme Corp, pad: 20 }

marks:
  amount: { within: clip, text: $42.00 }

mask:
  - { within: clip, css: '.updated-at' }

callouts:
  - { mark: amount, text: What they owe, place: left }
```

## Fields

| Field | Default | Effect |
| --- | --- | --- |
| `name` | filename | Output filename, without the extension |
| `source` | `app` | `app` drives the site; `file` annotates an image |
| `file` | — | Image to annotate, required with `source: file` |
| `install` | — | Which named destination in `install` to copy to |
| `url` | [`site.url`](/docs/reference/configuration/#site) | Page to open; used verbatim, not resolved against `site.url` |
| `session` | — | Which of `site.sessions` to use |
| `viewport` | [`site.viewport`](/docs/reference/configuration/#site) | Viewport for this recipe |
| `scale` | [`site.scale`](/docs/reference/configuration/#site) | Device pixel ratio for this recipe |
| `theme` | [`site.theme`](/docs/reference/configuration/#site) | Color scheme for this recipe |
| `format` | [`image.format`](/docs/reference/configuration/#image) | `png`, `jpeg` or `webp` |
| `quality` | [`image.quality`](/docs/reference/configuration/#image) | For the lossy formats |
| `style` | — | Style overrides, same shape as `style` in the configuration |
| `setup` | `[]` | Steps run before anything is measured |
| `teardown` | `[]` | Steps run after the shot, and after a shot that failed |
| `clip` | `viewport` | Region to capture |
| `marks` | `{}` | Named regions, resolved in written order after `setup` |
| `mask` | `[]` | Regions painted over before callouts are drawn |
| `callouts` | `[]` | What to draw on the marks |
| `numbered` | — | Marks to number 1…n with a disc |
| `retries` | `0` | Extra attempts if the recipe fails, up to 5 |
| `check` | [`check`](/docs/reference/configuration/#check) | This recipe's comparison settings, or `false` |

## clip

| Value | Captures |
| --- | --- |
| `viewport` | The browser window at the effective viewport size |
| `full` | The whole document, however far it scrolls |
| a [query](/docs/reference/queries/) | The box of the element it resolves to |

A clip is held to the width of the viewport. Its height is not: a region reaching past the fold is captured by scrolling to it.

## marks

A mapping of names you choose to [queries](/docs/reference/queries/). Marks resolve after `setup`, in written order, so `within: clip` and `within: <mark>` can refer to anything already resolved.

A mark that matches nothing stops the run, naming the recipe and the mark. With `source: file` a mark is a literal `rect` instead.

## source: file

Annotates an image on disk. No page is opened, so `clip`, `url` and `session` do not apply, marks and masks are literal rectangles, and `retries` has no effect.

`setup` and `teardown` are refused rather than ignored: there is no page for them to run against. A recipe carrying either drops them, or drops `source: file`.

screenshots/recipes/billing-settings.yaml

```
name: billing-settings
source: file
file: captures/billing-settings.png

marks:
  plan: { rect: [866, 874, 150, 50] }

callouts:
  - { mark: plan, text: The current plan }
```

## teardown

Steps run once the shot has been taken, in the same browser as `setup`. They run after a shot that failed as well. A recipe with `retries` tears down after each attempt.

A failure in `teardown` is reported only when the shot itself succeeded. When both failed, the error names the shot. See [Undo what a shot changed](/docs/how-to/undo-what-a-shot-changed/).

screenshots/recipes/new-order.yaml

```
name: new-order
setup:
  - click: { role: button, name: New order }
  - fill: { label: Customer }
    value: Acme Corp
  - click: { role: button, name: Save }
clip: { css: '.order-row' }
teardown:
  - dialog: accept
  - click: { role: button, name: Delete }
```

## check

`false` excludes the recipe from `--check`. A mapping accepts:

| Key | Default | Effect |
| --- | --- | --- |
| `threshold` | [`check.threshold`](/docs/reference/configuration/#check) | Fraction of pixels that may differ |
| `tolerance` | [`check.tolerance`](/docs/reference/configuration/#check) | How far one channel may move, out of 255 |
| `ignore` | `[]` | Queries whose contents are excluded from the comparison |

screenshots/recipes/roll-form.yaml

```
name: roll-form
check:
  threshold: 0.01
  ignore:
    - { css: 'output#result' }
```

An ignored region is blanked in both images where it resolves now, so a region that moves or changes size is still reported.

## retries

screenshots/recipes/order-row.yaml

```
name: order-row
retries: 2
```

Up to 5. Each attempt uses a fresh browser context. Failures are reported while the run continues rather than after it.

## Failure

A run stops at the first recipe that fails and names the recipe and the key that could not be resolved. `--keep-going` takes the rest and lists every failure at the end. Either way the exit code is non-zero.

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/reference/recipe.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/reference/recipe.astro)