snapshot

Compare a test artifact against a saved reference file. Instead of writing the expected output directly in the YAML, you store it in a separate file. When the actual output matches the file, the test passes. When it doesn't, you see a diff showing exactly what changed.

Snapshots are perfect when the expected output is large (a full JSON response, multi-line CLI output) or when you want to review changes over time in version control.

HTTP response body

assertions:
  - snapshot:
      artifact: responseBody
      file: ./expected-response.json

CLI stdout

assertions:
  - snapshot:
      artifact: stdout
      file: ./expected-output.txt

CLI stderr

assertions:
  - snapshot:
      artifact: stderr
      file: ./expected-errors.txt

Fields

Field	Description
`artifact`	What to compare: `responseBody` (HTTP) or `stdout`, `stderr` (CLI)
`file`	Path to the reference file, relative to the `.spark` file

Regenerating snapshots

When you intentionally change the output (new API response format, updated CLI text), update all snapshot files at once:

spark run ./tests --regenerate-snapshots

This writes the actual output to the snapshot files instead of comparing. Run your tests normally after regenerating to confirm the new snapshots are correct. It's a good idea to review the diff in version control before committing.