Skip to main content
Snapshot testing captures a response body and saves it to disk. On subsequent runs, hitspec compares the current response against the saved snapshot and reports any differences. This is useful for detecting unexpected changes in API responses.

​
How It Works

  1. First run — hitspec saves the response body to a snapshot file.
  2. Subsequent runs — hitspec compares the current response against the saved snapshot.
  3. Mismatch — if the response has changed, the test fails with a diff.
  4. Update — use --update-snapshots to accept the new response as the baseline.

​
Basic Usage

Add the snapshot assertion operator in your expect block:
The string "getUserResponse" is the snapshot name. It must be unique within the test file.

​
Snapshot Files

Snapshots are stored in a __snapshots__/ directory next to your test file. Each test file gets a single <filename>.snap.json file that holds all of that file’s named snapshots:
So tests/api.http stores its snapshots in tests/__snapshots__/api.snap.json, keyed by the snapshot names you give in expect body snapshot "...". Snapshots group by test file, not one file per snapshot.
Commit your __snapshots__/ directories to version control. This allows your team to review snapshot changes in pull requests and catch unexpected API changes.

​
Updating Snapshots

When an API response changes intentionally (new fields, updated values), update the snapshots:
This overwrites all existing snapshot files with the current responses. Review the changes in your version control diff to confirm they are expected.

​
Workflow

A typical snapshot testing workflow:
  1. Write the test with expect body snapshot "name"
  2. Run once to generate the initial snapshot
  3. Commit the snapshot file alongside your test
  4. CI runs compare responses against the committed snapshots
  5. When the API changes, run --update-snapshots locally, review the diff, and commit

​
Combining with Other Assertions

Snapshot testing works alongside other assertion operators:
The snapshot assertion captures the entire response body. Other assertions run independently and can validate specific fields or structure.
Snapshots compare the full response body. If your API returns dynamic values (timestamps, UUIDs, etc.), those will cause snapshot mismatches on every run. Use field-level assertions for dynamic values and reserve snapshots for stable response shapes.

​
Example: API Regression Detection

Running these tests in CI will catch any unexpected changes to the product listing or detail endpoints.
Last modified on July 13, 2026