Assertions

Assertions let you validate every aspect of an HTTP response — status codes, headers, body content, response times, and more. hitspec provides 26 operators grouped into six categories.

Assertion Block Syntax

Wrap assertions in >>> and <<< markers:

GET {{baseUrl}}/users

>>>
expect status 200
expect body type array
expect body[0].id exists
expect duration < 500
<<<

Each line inside the block follows this pattern:

expect <subject> <operator> <value>

When the operator is ==, you can omit it, as long as the value starts like a value (a number, a quoted string, true, false, null, [ or {):

>>>
expect status 200          # shorthand for: expect status == 200
expect status == 200       # explicit form
<<<

A trailing # comment is allowed on any line (the # must follow whitespace and be followed by whitespace or the end of the line). Blank lines and lines starting with # or // inside the block are ignored. Any other line that does not start with expect is an error.

Mistakes are errors, not guesses

hitspec refuses assertion lines it would otherwise have to guess at. hitspec run and hitspec validate report them with file:line:column and exit with code 2:

api.http:6:18: unknown operator "contians" (did you mean "contains"?)

An unknown operator (contians, =, ===, equals) is an error. A bare word after the subject is never read as ”== word”: write expect body.name == Jane or expect body.name "Jane".
An operator without a value (expect body.name ==) is an error. It no longer reads the next line as its value.
Extra values are an error: expect status 200 201 fails with a hint to write expect status in [200, 201].
expect misspelt (expcet status 200) is an error, so a line can never silently assert nothing.

Expected Values

Every operator that takes a value reads it with one rule. The value is either:

a JSON literal: a string ("Jane Doe" or 'Jane Doe'), a number, true, false, null, a list [1, "a", b], or an object {"a": 1}; or
a regular expression /pattern/flags after matches (flags i, m, s, U; g is accepted and ignored); or
otherwise, the rest of the line, trimmed, exactly as written, as a string.

>>>
expect body.name == Jane Doe          # the string "Jane Doe", no quotes needed
expect body.path == ./files/x         # ./files/x, $HOME, ^start, @handle, #fff are all fine
expect body.msg == "line\nbreak"      # JSON escapes work inside quotes
expect body.address == {"city": "Oslo", "zip": "0150"}
expect status in [200, 201]
<<<

Quoted strings use JSON escapes; if the text is not valid JSON (a regex such as "\d+"), it is used as written. In a list, each element follows the same rule. {{variable}} references are filled in before comparing. Text after a closing quote is an error ("Jane" Doe), so quote the whole value or none of it. For contains, !contains, startsWith and endsWith the value is always text: a quoted string is decoded, anything else is used exactly as written (expect body startsWith {, expect body.price contains 1.50).

Assertion Subjects

Subject	Description	Example
`status`	HTTP status code	`expect status 200`
`duration`	Response time in milliseconds	`expect duration < 1000`
`header <name>`	Response header value	`expect header Content-Type contains json`
`body`	Full response body (parsed when JSON, text otherwise)	`expect body contains "success"`
`body.<path>`	Path into a JSON body (gjson syntax: `.#` counts, `.#(...)` queries)	`expect body.user.name == "John"`
`body[n]`	Array index	`expect body[0].id exists`
`jsonpath $.<path>`	JSONPath expression (`$.a.b`, `$.a[0]`, `$.a[*].b`)	`expect jsonpath $.users[0].id exists`

A body path needs a JSON response: application/json, text/json and any +json type such as application/problem+json, with or without ; charset=.... On any other response, body.x fails with “response body is not JSON” instead of quietly matching; only the whole body can be read. See Assertion Subjects.

Equality and Comparison

Compare values using standard comparison operators.

Operator	Syntax	Description
`==`	`expect status == 200`	Equals
`!=`	`expect body.error != null`	Not equals
`>`	`expect body.count > 0`	Greater than
`>=`	`expect body.count >= 1`	Greater than or equal
`<`	`expect duration < 1000`	Less than
`<=`	`expect duration <= 500`	Less than or equal

### Verify response timing and pagination
GET {{baseUrl}}/users?page=1&limit=20

>>>
expect status == 200
expect duration < 500
expect body.total > 0
expect body.page == 1
expect body.perPage >= 20
<<<

Use expect status 200 as shorthand for expect status == 200. The == operator is implied when omitted.

== and != compare objects and arrays deeply, as JSON: key order does not matter, 1 equals 1.0, and ["a b"] is not ["a", "b"]:

>>>
expect body.address == {"city": "Oslo", "zip": "0150"}
expect body.ids == [1, 2, 3]
<<<

Scalars are compared loosely: "42" and 42 are equal. null only equals null (see null versus absent).

String Operators

Match, search, and compare string values.

Operator	Syntax	Description
`contains`	`expect body contains "success"`	Contains substring
`!contains`	`expect body !contains "error"`	Does not contain substring
`startsWith`	`expect body.url startsWith "https"`	Starts with prefix
`endsWith`	`expect body.email endsWith ".com"`	Ends with suffix
`matches`	`expect body.id matches /^\d+$/`	Matches regular expression

### Check user profile fields
GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.email endsWith "@example.com"
expect body.website startsWith "https"
expect body.bio !contains "<script>"
expect body.phone matches /^\+?[\d\s\-()]+$/
<<<

Regular expressions in matches are enclosed in forward slashes: /pattern/ or /pattern/i (flags i, m, s, U). The pattern uses Go’s regexp syntax. A value without slashes (matches "^a") is used as the pattern as written.

The string operators work on text. On the whole body of a JSON response they see the response’s raw JSON text; on an object or array they see its JSON encoding (never Go’s map[...] form); numbers appear without an exponent:

>>>
expect body contains "\"name\":\"Jane\""
expect body.address contains "\"city\":\"Oslo\""
expect body.tags endsWith "]"
<<<

Existence and Type

Check whether values exist and validate their types.

Operator	Syntax	Description
`exists`	`expect body.id exists`	Value is present and not null
`!exists`	`expect body.error !exists`	Value is absent or null
`type`	`expect body.items type array`	Check value type

Supported types for the type operator: null, boolean, number, string, array, object. Anything else is an error (type strng suggests string).

null versus absent

A field that is missing and a field that is null are different, and the operators treat them differently:

Body	`exists`	`!exists`	`== null`	`!= null`	`type null`
`{"x": 5}`	pass	fail	fail	pass	fail
`{"x": null}`	fail	pass	pass	fail	pass
`{}` (x is absent)	fail	pass	fail	fail	fail

== null needs a real JSON null, and != null needs a present, non-null value, so a misspelt path cannot pass either. To accept “absent or null”, use !exists. Every other operator fails on an absent path, except the negated ones (!=, !contains, !includes, !in), which hold because nothing is there to match.

### Validate response structure
GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id exists
expect body.name type string
expect body.age type number
expect body.active type boolean
expect body.tags type array
expect body.address type object
expect body.deletedAt !exists
<<<

Length and Arrays

Validate array lengths and check array contents.

Operator	Syntax	Description
`length`	`expect body.items length 10`	Length equals exact value (strings count characters, not bytes)
`length >`	`expect body.items length > 0`	Length greater than
`length >=`	`expect body.items length >= 1`	Length greater than or equal
`length <`	`expect body.items length < 100`	Length less than
`length <=`	`expect body.items length <= 50`	Length less than or equal
`includes`	`expect body.tags includes "admin"`	Array contains value
`!includes`	`expect body.tags !includes "test"`	Array does not contain value
`in`	`expect status in [200, 201, 204]`	Value is one of the listed values
`!in`	`expect status !in [400, 404, 500]`	Value is not one of the listed values
`each`	`expect body.items each type object`	Apply an assertion to every element

### Validate paginated list
GET {{baseUrl}}/users?role=admin

>>>
expect status 200
expect body.users length > 0
expect body.users length <= 100
expect body.users each type object
<<<

The `each` Operator

each applies an assertion to every element in an array. It is useful for validating the shape of list responses. After each write an operator and value, optionally preceded by a path inside the element (body or a leading . means the element itself):

>>>
expect body.users each type object
expect body.users each body.id exists
expect body.users each email matches /^.+@.+\..+$/
expect body.scores each > 0
expect body.users each {"operator": "type", "value": "object"}
<<<

A failure names the element: item[2]: expected type string, got number. An empty array passes (nothing to check); add length > 0 to require elements.

The `in` Operator

in checks whether a value is a member of a set. List values in square brackets:

>>>
expect status in [200, 201]
expect body.role in ["admin", "editor", "viewer"]
<<<

The `includes` Operator

includes checks whether an array contains a specific value:

>>>
expect body.permissions includes "read"
expect body.permissions includes "write"
expect body.permissions !includes "superadmin"
<<<

Schema Validation

Validate the entire response body against a JSON Schema file.

Operator	Syntax	Description
`schema`	`expect body schema ./schema.json`	Validate against JSON Schema

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body schema ./schemas/user.json
<<<

Where schemas/user.json contains a standard JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "user", "guest"] }
  }
}

Schema file paths are resolved relative to the .http file that references them.

Snapshot Testing

Compare the response body against a previously saved baseline. A snapshot is never created by a plain run: the first run fails with “snapshot does not exist (run with —update-snapshots to create)”. Run once with --update-snapshots to save the baseline, then later runs compare against it.

Operator	Syntax	Description
`snapshot`	`expect body snapshot "name"`	Compare against saved snapshot

GET {{baseUrl}}/config

>>>
expect status 200
expect body snapshot "app-config"
<<<

Snapshots are stored in a __snapshots__ directory next to your test file. Create them the first time, and update them when the response intentionally changes:

hitspec run tests/ --update-snapshots

Snapshot testing works well for responses that should remain stable over time, such as configuration endpoints or reference data.

Combining Assertions

A single assertion block can mix operators from any category:

### Full response validation
POST {{baseUrl}}/orders
Content-Type: application/json

{
  "productId": "prod-123",
  "quantity": 2
}

>>>
expect status 201
expect duration < 1000
expect header Content-Type contains json
expect body.id exists
expect body.id type string
expect body.status == "pending"
expect body.items length 2
expect body.items each type object
expect body.total > 0
expect body schema ./schemas/order.json
<<<

Header Assertions

Assert on response headers using the header <name> subject:

>>>
expect header Content-Type contains "application/json"
expect header X-Request-Id exists
expect header X-RateLimit-Remaining > 0
expect header Cache-Control contains "no-cache"
<<<

Reading a failure

When a request fails, the console output alone says why: the failed assertions with their expected and actual values, then the request as it was sent, the response status line with its duration, and an excerpt of the response body.

  ✗ getUser (12ms)
    → status == (line 5)
      Expected: 200
      Actual:   404
      expected 200, got 404
    → body.id == (line 6)
      Expected: 1
      Actual:   42
      expected 1, got 42
    Request:  GET https://api.example.com/users/42?api_key=[REDACTED]
    Response: 404 Not Found (9ms)
    Body:
      {
        "error": "user not found",
        "id": 42
      }

JSON bodies are pretty-printed and the excerpt is capped at about 2 KB or 30 lines; a note says how much was cut, and -vvv prints the whole body. Credentials are redacted: header values such as Authorization and Cookie, the password in user:password@host, and query parameters named like api_key or access_token. If a request errored before any response arrived (connection refused, timeout), you get the request line and the error. See output formats for -v, -vv and -vvv.

Testing Error Responses

Assertions are equally useful for verifying error behavior:

### Missing authentication
GET {{baseUrl}}/admin/users

>>>
expect status 401
expect body.error exists
expect body.message contains "unauthorized"
<<<

### Non-existent resource
GET {{baseUrl}}/users/99999999

>>>
expect status 404
expect body.error exists
<<<

### Invalid input
POST {{baseUrl}}/users
Content-Type: application/json

{"email": "not-an-email"}

>>>
expect status 400
expect body.errors type array
expect body.errors length > 0
<<<

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Assertion Block Syntax

Mistakes are errors, not guesses

Expected Values

Assertion Subjects

Equality and Comparison

String Operators

Existence and Type

null versus absent

Length and Arrays

The `each` Operator

The `in` Operator

The `includes` Operator

Schema Validation

Snapshot Testing

Combining Assertions

Header Assertions

Reading a failure

Testing Error Responses

Assertion Block Syntax

Mistakes are errors, not guesses

Expected Values

Assertion Subjects

Equality and Comparison

String Operators

Existence and Type

null versus absent

Length and Arrays

The each Operator

The in Operator

The includes Operator

Schema Validation

Snapshot Testing

Combining Assertions

Header Assertions

Reading a failure

Testing Error Responses

The `each` Operator

The `in` Operator

The `includes` Operator