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`	Page to open; used verbatim, not resolved against `site.url`
`session`	—	Which of `site.sessions` to use
`viewport`	`site.viewport`	Viewport for this recipe
`scale`	`site.scale`	Device pixel ratio for this recipe
`theme`	`site.theme`	Color scheme for this recipe
`format`	`image.format`	`png`, `jpeg` or `webp`
`quality`	`image.quality`	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`	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	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. 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.

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`	Fraction of pixels that may differ
`tolerance`	`check.tolerance`	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.