> ## 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.

# Store golden files locally

> Keep visual diff snapshots in version control by opting into local golden file storage.

Golden files are the source of truth for snapshot-based steps like **Visual
diff**. By default they're stored on the dashboard; opt into local storage to
keep them alongside your tests.

## Enable local storage

1. In your **Visual diff** step, omit the `screenshot` key so Momentic stores
   the snapshot locally:

   ```yaml theme={null}
   - visualDiff:
       on: Order summary panel
       threshold: 0.1
   ```

2. Snapshots are written to
   `<momentic-root>/golden/visual-diff/<command-id>.jpg` by default. The command
   ID is the internal identifier minted from the step's position in the test:

   ```
   momentic.config.yaml
   golden/
     visual-diff/
       c41afa9a-....jpg
   ```

3. (Optional) Override the directory via
   [`goldenFileDir`](/configuration/momentic-config#goldenfiledir) in
   `momentic.config.yaml`:

   ```yaml momentic.config.yaml theme={null}
   goldenFileDir: tests/snapshots
   ```

## Update snapshots

```bash theme={null}
npx momentic run --update-golden-files
```

<Warning>
  `--update-golden-files` makes snapshot-based tests pass even when the current
  state differs from the stored snapshot. Use it intentionally.
</Warning>

## Colocate snapshots with tests

Point the `screenshot.data` field at a path relative to the Momentic root:

```yaml theme={null}
- visualDiff:
    on: Upload button
    threshold: 0.4
    screenshot:
      data: momentic/tests/visual-diff/golden/upload-button.jpg
      width: 1920
      height: 1080
```

Resulting layout:

```
momentic.config.yaml
momentic/
  tests/
    visual-diff/
      visual-diff.test.yaml
      golden/
        upload-button.jpg
```

## Mobile

On mobile, [`visualDiff`](/reference/mobile-commands/visual-diff) always stores
golden files locally. The golden path is part of the step:

```yaml theme={null}
- visualDiff:
    path: ./golden/visual-diff/home.png
    threshold: 0.1
```

`path` resolves relative to the test or module file the step is defined in (the
same rule used by module and JavaScript file references), so a `visualDiff`
inside a module always resolves against the module's location no matter which
test includes it.

The golden is created on the first run and the step passes. On later runs the
full-screen screenshot is compared against the golden and the step fails if it
differs by more than `threshold`. Refresh goldens after an intentional UI change
with `--update-golden-files`. Mobile `visualDiff` is only available when running
tests locally with the CLI.

## Related

* [`momentic run`](/cli-reference/momentic/commands/run)
* [`momentic.config.yaml`](/configuration/momentic-config)