# Snapshots and refs

Take a snapshot before you click. The snapshot is the list of elements you can act on. Each interactive line ends with a ref such as `[ref=e3]`.

```
npx wdio session open chrome http://localhost:3000

npx wdio session snapshot --interactive
```

A line looks like `button "Add to cart" [ref=e3]`. The next command uses that ref:

```
npx wdio session click e3
```

Refs come from the latest snapshot. After navigation, snapshot again. An old ref fails with `REF_STALE`. An unknown ref fails with `REF_NOT_FOUND`.

Experimental

The text layout of a snapshot, and the shape `--json` prints for it, are experimental: a minor release may change them, for example to share one snapshot engine with the [DevTools trace](/docs/devtools/wdio/trace-mode.md). The ref syntax (`e3`, `@e3`), the actions that take a ref and the code they record stay stable. Take refs from a snapshot and don't parse the rest of its lines.

## What to run[​](#what-to-run "Direct link to What to run")

| Command                  | Use it for                                                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `snapshot --interactive` | The elements you can act on, each with a ref                                                                                                                 |
| `find "Add to cart"`     | Each match with the node around it, e.g. a whole list item, so a value next to the match comes along. `-A`, `-B` and `-C` print plain line context like grep |
| `diff`                   | What changed since the previous snapshot                                                                                                                     |
| `screenshot`             | Layout. Skip it when a snapshot answers the question                                                                                                         |
| `source`                 | The page HTML or the native XML                                                                                                                              |

`snapshot` without `--interactive` includes more of the tree. Prefer `--interactive` when you are about to click or type.

## What an action changed[​](#what-an-action-changed "Direct link to What an action changed")

In a web session, `open` prints the interactive snapshot of the page it opened, and every action that can change the page (`click`, `fill`, `type`, `press`, `select`, `check`, `navigate`, `frame`, …) reports what changed:

```
Clicked e6 (button "Start subscription")

Changes:

+ - status "Subscription started. Confirmation code: 4F2A9C"
```

When the action opened a tab, the report says so (`Opened a new tab [1]: https://…`); the session stays on the current tab until you run `tabs switch`. When the page is a bot check (Cloudflare, DataDome, Akamai, …) rather than the site, the report says that too, once per page. The session doesn't try to get past it; in a headless browser it suggests reopening with `--headed`.

On the same page you get the new or changed lines with their refs, including text that is not interactive, like the status above. After a navigation you get the new page's interactive elements, or for a large page a one-line summary that points to `find`. So you rarely need a separate `snapshot` after an action. Set `WDIO_SESSION_CHANGES=0` to turn the report off, and pass `open --no-snapshot` to skip the snapshot after `open`.

## Frames[​](#frames "Direct link to Frames")

In a WebDriver BiDi session the snapshot shows the content of the page's iframes, cross-origin ones included, under the iframe they are in:

```
- iframe "Payment" [ref=e4]

  - textbox "Card number" [ref=e5]

  - button "Pay" [ref=e6]
```

Actions on these refs enter the frame, act, and come back to the page, and the printed code does the same. Up to five iframes are shown, each cut at 300 elements; `frame e4` and `snapshot` show all of a frame that was cut short. Iframes smaller than 100 square pixels, like tracking pixels, are left out.

## Shadow DOM and clickable elements without a role[​](#shadow-dom-and-clickable-elements-without-a-role "Direct link to Shadow DOM and clickable elements without a role")

With WebDriver BiDi, the snapshot also covers closed shadow roots, and elements that only have a click listener (an icon wired up with `addEventListener`) get a ref. Such an element has no accessible name, so the snapshot describes it instead:

```
- generic [ref=e8] (icon 3 of 3 in "Invoice #1002 · Contoso Ltd · $860.00")
```

On Android, iOS, macOS and Windows the snapshot comes from the Appium page source. Two controls that share an accessibility id stay separate refs when the rest of their selectors differ. `snapshot --scope e3` limits the tree to that ref.

## Native taps[​](#native-taps "Direct link to Native taps")

Web sessions use `click`. Mobile and native desktop sessions use `tap` on the same ref:

```
npx wdio session open android --app ./shop.apk

npx wdio session snapshot --interactive

npx wdio session tap e3
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

| Message         | What to do                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `REF_STALE`     | The element from the last snapshot is gone. Run `snapshot` and use a new ref.                  |
| `REF_NOT_FOUND` | That id was never in this session. The ref in your command does not match the latest snapshot. |
| `NO_MATCH`      | `find` did not see that text. Snapshot and read the names that are actually there.             |

## Next steps[​](#next-steps "Direct link to Next steps")

* [Run code](/docs/session/exec.md) — assertions and steps that are more than one command
* [Commands](/docs/session-commands.md) — `snapshot`, `find`, `diff`, `screenshot` and `source` flags