Macros and data files

Macro files

One file per macro in paths.macros. The filename is the macro's name. A macro cannot contain clip, marks or callouts.

Key	Default	Effect
`steps`	required	The steps to run
`defaults`	`{}`	Values the macro reads, overridable by the caller

screenshots/macros/sign-in.yaml

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

Call it from a recipe or another macro with the use step:

screenshots/recipes/dashboard.yaml

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

Data files

Every file in paths.data is in scope, named after its filename: orders.yaml is $orders. A filename must contain only letters, digits and underscores, because a reference stops at a hyphen.

screenshots/data/orders.yaml

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

screenshots/recipes/orders.yaml

setup:
  - each: $orders.open
    as: order
    steps:
      - fill: { label: Search }
        value: ${order.name}

References

Form	Meaning
`$name`	The value bound to `name`
`{"${name}"}`	The same, delimited
`$a.b`	A path into the value bound to `a`
`{"${env.NAME}"}`	An environment variable the run was allowed to read

A name continues through letters, digits, underscores and dots, so braces are required where the reference runs into text that could belong to it: Order ${order.name}. ends the reference before the full stop, while Order $order.name. looks for a path ending in a dot.

Where values come from

data files, by filename
with on a use step, for the macro it calls
readValue: … as: name, for the steps that follow it
each: … as: name, for its own steps only

Rules

A reference that is the whole value keeps that value's type. A reference inside a longer string becomes text.
References are substituted in steps only, never in clip, marks or callouts.
A reference that matches nothing is an error, not an empty string.
A literal $ inside a longer string is left alone.
__proto__, constructor and prototype resolve to nothing.
${env.NAME} resolves only for names given to --allow-env or listed in SHOTLIST_ENV; an --untrusted run resolves none.