# 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: sam@example.com
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: admin@example.com }
```

The first call signs in as `sam@example.com`, 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`.

## Related

- [Macros and data files reference](/docs/reference/macros-and-data/)
- [Steps reference](/docs/reference/steps/)
- [Capture a page behind a sign-in](/docs/how-to/sign-in/)

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/how-to/share-setup.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/how-to/share-setup.astro)