# Steps

Steps appear under `setup` in a recipe, under `steps` in a macro, and under `steps` inside a `repeat` or `each` block. Each step is a mapping led by one verb.

screenshots/recipes/order-row.yaml

```
setup:
  - click: { role: button, name: Orders }
  - fill: { label: Search }
    value: Acme
  - wait: { css: '.order-row' }
    comment: the list has settled, so the row can be measured
```

## Navigation and pages

| Step | Extra keys | Effect |
| --- | --- | --- |
| `goto: <url>` | — | Navigate the current page |
| `openPage: <url>` | `as`, `viewport` | Open a second page and name it |
| `usePage: <name>` | — | Switch which page later steps drive |

## Pointer

| Step | Extra keys | Effect |
| --- | --- | --- |
| `click: <query>` | — | Click an element |
| `dblclick: <query>` | — | Double-click an element |
| `hover: <query>` | — | Move the pointer onto an element |
| `scrollIntoView: <query>` | — | Scroll an element into view |

## Input

| Step | Extra keys | Effect |
| --- | --- | --- |
| `fill: <query>` | `value` | Set an input's value |
| `type: <text>` | `on` | Type text, optionally after focusing an element |
| `press: <key>` | `on` | Press a key, optionally after focusing an element |
| `select: <query>` | `option`, `optionLabel` | Choose an option by value or visible text |
| `check: <query>` | — | Tick a checkbox |
| `uncheck: <query>` | — | Untick a checkbox |
| `blur: <query>` | — | Remove focus |
| `readValue: <query>` | `as` | Read an input's value into a variable |

## Waiting

| Step | Effect |
| --- | --- |
| `wait: <ms>` | Wait a fixed number of milliseconds |
| `wait: <query>` | Wait until an element exists, bounded by `site.timeout` |

## Dialogs

| Step | Extra keys | Effect |
| --- | --- | --- |
| `dialog: accept` | `value` | Accept every dialog from here on. `value` answers a `prompt()` |
| `dialog: dismiss` | — | Dismiss every dialog from here on |

Covers `alert`, `confirm`, `prompt` and `beforeunload`. The setting holds until another `dialog` step replaces it, and applies to a page opened after it. Unset, dialogs are dismissed — see [Capture a page after interaction](/docs/how-to/drive-a-page/).

screenshots/recipes/order-deleted.yaml

```
name: order-deleted
setup:
  - dialog: accept
  - click: { role: button, name: Delete }
  - wait: { text: Order deleted }
clip: { css: '.notice' }
```

## Blocks

| Step | Extra keys | Effect |
| --- | --- | --- |
| `use: <macro>` | `with` | Run a macro, overriding its defaults |
| `repeat: <n>` | `steps` | Run steps n times, up to 1000 |
| `each: <list>` | `as`, `steps` | Run steps once per item |
| `optional: [steps]` | — | Run steps, ignoring failures |

screenshots/recipes/order-list.yaml

```
setup:
  - repeat: 3
    steps:
      - click: { role: button, name: Load more }
  - each: [Acme Corp, Globex]
    as: customer
    steps:
      - fill: { label: Search }
        value: $customer
  - optional:
      - click: { role: button, name: Dismiss }
```

## Keys any step accepts

| Key | Effect |
| --- | --- |
| `comment` | A note for the reader; ignored at run time |

`comment` rides alongside a verb rather than being one, so a comment on its own is not a step.

## Variables

`as` names a value the following steps can read. `readValue: … as: total` binds `$total` for the rest of the setup; `each: … as: order` binds `$order` for its own steps only. Substitution happens in steps and nowhere else — see [references](/docs/reference/macros-and-data/#references).

## Not available

There is no step that evaluates JavaScript. See [Why recipes cannot run code](/docs/explanation/no-code/).

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