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

# Snapshot testing for API responses

> Capture API response bodies as baselines and automatically detect regressions with snapshot comparison. Update baselines on purposeful changes.

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:

```http theme={null}
### Get user details
# @name getUser

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body snapshot "getUserResponse"
<<<
```

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:

```
tests/
  api.http
  __snapshots__/
    api.snap.json
```

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.

<Tip>
  Commit your `__snapshots__/` directories to version control. This allows your team to review snapshot changes in pull requests and catch unexpected API changes.
</Tip>

## Updating Snapshots

When an API response changes intentionally (new fields, updated values), update the snapshots:

```bash theme={null}
hitspec run tests/ --update-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:

```http theme={null}
>>>
expect status 200
expect body.id exists
expect body.items type array
expect body snapshot "fullResponse"
<<<
```

The snapshot assertion captures the entire response body. Other assertions run independently and can validate specific fields or structure.

<Note>
  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.
</Note>

## Example: API Regression Detection

```http theme={null}
@baseUrl = https://api.example.com

### List products
# @name listProducts
# @tags regression

GET {{baseUrl}}/products?category=electronics

>>>
expect status 200
expect body type array
expect body length > 0
expect body snapshot "productList"
<<<

### Product detail
# @name productDetail
# @tags regression

GET {{baseUrl}}/products/1

>>>
expect status 200
expect body.id == 1
expect body snapshot "productDetail"
<<<
```

Running these tests in CI will catch any unexpected changes to the product listing or detail endpoints.