> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# visualDiff

> Compare a viewport or element screenshot against a golden file.

On first run, captures the golden image and stores it next to the test. On
subsequent runs, fails the step if the rendered region differs by more than
`threshold`. Re-record a golden by deleting it and re-running. The bare form
`- visualDiff` diffs the full viewport.

## Parameters

| Parameter   | Type                 | Required | Description                                                                                     |
| ----------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `on`        | `string`             | No       | Description of the element to diff against.                                                     |
| `css`       | `string`             | No       | CSS selector for the target. Use instead of the description key.                                |
| `coords`    | `string \| { x, y }` | No       | Absolute viewport coordinates. Either an `x, y` string (e.g. `120, 40`) or a `{ x, y }` object. |
| `x`         | `number \| string`   | No       | X coordinate. Must be provided together with `y`.                                               |
| `y`         | `number \| string`   | No       | Y coordinate. Must be provided together with `x`.                                               |
| `force`     | `boolean`            | No       | Force the action even when the element is not actionable.                                       |
| `iframe`    | `string`             | No       | URL or URL pattern of the iframe that contains the target element.                              |
| `threshold` | `number`             | No       | Maximum allowed visual difference. 0 = identical.                                               |
| `saveAs`    | `string`             | No       | Name of the variable to write this step's return value to.                                      |
| `retries`   | `number`             | No       | Number of times to retry the step on failure before failing the test.                           |
| `skipped`   | `boolean`            | No       | Skip this step at execution time.                                                               |

## Shorthand

Bare command. Diffs the full viewport.

```yaml theme={null}
- visualDiff
```

## Examples

```yaml theme={null}
- visualDiff:
    threshold: 0.1
```

```yaml theme={null}
- visualDiff:
    on: the 'Start HTTP upload' button
    threshold: 0.4
    screenshot:
      data: momentic/tests/visual-diff/golden/upload-button.jpg
      width: 125
      height: 20
```

```yaml theme={null}
- visualDiff:
    threshold: 0.1
    screenshot:
      data: https://screenwriter-test-code.s3.us-west-1.amazonaws.com/screenshots/abbd74b9-b4e1-4c70-abd1-56093db36ffe.jpg
      width: 1920
      height: 1080
```

## Related

* [Golden files](/guides/visual-testing/golden-files)
* [Test format](/core-concepts/test-format)