Skip to content

Assertions and snapshots

Both kinds of test are written into the .http file as directives, so they travel with the requests and run in CI as well as in the app.

An assertion checks one thing about a response:

### Get a pet
# @reqjet.assert status == 200
# @reqjet.assert time < 500
# @reqjet.assert body.$.name == "Rex"
# @reqjet.assert body.$.tags[*] exists
# @reqjet.assert header.Content-Type contains json
GET {{baseUrl}}/pets/7

You rarely need to type them:

  • Right-click a value in a JSON response body and choose Assert body.$.name == "Rex". The line is added to the request. Assert … exists only checks the value is there; objects and arrays always use exists.
  • Right-click the status to assert it.
  • Copy path copies the value’s JSONPath instead, for example to use in chaining.

# @reqjet.assert <subject> <operator> [value]

Subject Is
status The status code, such as 200.
time How long the response took, in milliseconds.
size The body’s size in bytes.
contentType The Content-Type, such as application/json.
body The whole body, as text.
body.$.path A value in a JSON body, by JSONPath: $.items[0].id, $.items[*].id, $['odd key'].
header.Name A response header, such as header.Cache-Control.
Operators
Comparing ==, !=, <, <=, >, >=
Text contains, not contains (or !contains), startsWith, endsWith, matches (a regular expression)
Presence exists, not exists (or !exists)

Quotes around the value are optional: == "Rex" and == Rex are the same. {{variables}} are filled in, as in the request, so body.$.role == "{{role}}" compares with the current value of {{role}}. A variable with no value stays as written, so the test fails.

A snapshot saves a whole response as the expected result, and every later send is compared with it. It’s the quickest way to protect an endpoint from accidental changes.

  1. Send the request, and check the response is right.
  2. Press Snapshot on the response. It saves the status and body, and adds # @reqjet.snapshot to the request.
  3. From then on, any difference is a failed test, such as “Differs: $.price: 10 → 12”.

When the API changes on purpose, press Snapshot again to accept the new response.

A Tests tab where the snapshot test failed, showing the JSON value that differsA Tests tab where the snapshot test failed, showing the JSON value that differs
A failed snapshot test says which value changed.
### Get a pet
# @name pet
# @reqjet.snapshot ignore $.updatedAt $.owners[*].lastSeen
GET {{baseUrl}}/pets/7
  • Values that change on every call, such as timestamps and generated ids, would fail every time. List their JSONPaths after ignore. [*] matches any array index, and a path covers everything below it.
  • JSON is compared value by value, so formatting, key order and escaping don’t count. Other bodies are compared as text. Headers aren’t part of a snapshot.
  • Snapshots are saved next to the file: the ones for api.http are in __snapshots__/api.http.snap.json, keyed by each request’s # @name, or its title when it has no name. Commit them with the .http file. The __snapshots__ folder is hidden in the tree.
  • In the app, a request’s first send saves its snapshot.
  • reqjet run fails on a missing snapshot instead, so a new snapshot is always a deliberate change. Pass --update-snapshots to save every response as the new snapshot.

Clear, next to Snapshot, removes a request’s last response and its history, to start again. Snapshots and the .http file stay as they are.