Share setup between recipes

When several recipes begin with the same clicks, put those steps in a macro. When a recipe has to repeat itself over a list of values, put the list in a data file. This guide does both.

Extract steps into a macro

Create one file per macro in screenshots/macros/. The filename is the macro's name. A macro holds steps, and optionally defaults for the values it accepts:

screenshots/macros/sign-in.yaml

defaults:
  who: [email protected]
steps:
  - fill: { label: Email }
    value: $who
  - click: { role: button, name: Sign in }

Call it from any recipe with use, overriding values with with:

screenshots/recipes/dashboard.yaml

setup:
  - use: sign-in
  - use: sign-in
    with: { who: [email protected] }

The first call signs in as [email protected], because that is the default the macro declares. The second overrides it.

Drive a recipe from a list

Create a file in screenshots/data/. Its filename becomes the variable name, so orders.yaml is available as $orders:

screenshots/data/orders.yaml

- name: Acme Corp
  reference: INV-1042
- name: Globex
  reference: INV-1043

Iterate it with each, naming each item with as:

screenshots/recipes/orders.yaml

setup:
  - each: $orders
    as: order
    steps:
      - fill: { label: Search }
        value: ${order.name}
      - click: { role: button, name: Search }
      - wait: { css: '.order-row' }

${order.name} reads the name field of the current item. Use the braces whenever the reference runs into text that would otherwise be read as part of it: a name continues through letters, digits, underscores and dots, so ${order.name} and $order.name differ only where the next character could belong to either.

Use a list without a file

For a handful of values that do not deserve a file, write the list inline:

screenshots/recipes/searches.yaml

setup:
  - each: [Acme Corp, Globex, Initech]
    as: customer
    steps:
      - fill: { label: Search }
        value: $customer
      - click: { role: button, name: Search }

Move the folders

Macros and data files are found by convention. Change the locations under paths if your project needs different ones:

shotlist.config.yaml

paths:
  recipes: screenshots/recipes
  macros: screenshots/macros
  data: screenshots/data
  out: screenshots/out

Avoid hyphens in data filenames

A filename becomes a $name, and a reference stops at a hyphen. Name the file orders.yaml rather than open-orders.yaml, and group related lists into one file addressed by path: $orders.open, $orders.shipped.