Assertion Operators

hitspec provides 26 assertion operators organized into six categories. Every assertion follows this pattern:

expect <subject> <operator> <value>

When the operator is ==, you can omit it: expect status 200 is shorthand for expect status == 200. An unknown operator (contians, =, equals) is a parse error with a suggestion, never a silent ==; see Assertions for the full expected-value grammar (a JSON literal, a /regex/flags, or the rest of the line verbatim).

Equality and Comparison (6 operators)

Operator	Syntax	Description
`==`	`expect status == 200`	Equals (deep equality for objects/arrays, numeric coercion for numbers)
`!=`	`expect body.error != null`	Not equals
`>`	`expect body.count > 0`	Greater than (numeric)
`>=`	`expect body.count >= 1`	Greater than or equal (numeric)
`<`	`expect duration < 1000`	Less than (numeric)
`<=`	`expect duration <= 500`	Less than or equal (numeric)

>>>
expect status == 200
expect duration < 500
expect body.total > 0
expect body.page >= 1
expect body.errors != null
<<<

Numeric comparison coerces strings to numbers when possible. "42" and 42 are considered equal by ==. Objects and arrays are compared as JSON (key order is ignored, numbers compare as numbers). == null matches only a real JSON null; a missing field is not null (use !exists for “absent or null”).

String Operators (5 operators)

Operator	Syntax	Description
`contains`	`expect body contains "success"`	Actual value contains the expected substring
`!contains`	`expect body !contains "error"`	Actual value does not contain the substring
`startsWith`	`expect body.url startsWith "https"`	Actual value starts with the expected prefix
`endsWith`	`expect body.email endsWith ".com"`	Actual value ends with the expected suffix
`matches`	`expect body.id matches /^\d+$/`	Actual value matches a regular expression

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

Regular expressions use Go’s regexp syntax and are enclosed in forward slashes: /pattern/ or /pattern/i (flags i, m, s, U).

On a JSON response, contains, startsWith, endsWith and matches applied to the whole body see the raw JSON text; applied to an object or array they see its compact JSON encoding.

Existence and Type (3 operators)

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`	Value matches the expected type

For header subjects, exists means the header is present in the response (an empty value still counts) and !exists means it is absent. Supported type values: null, boolean, number, string, array, object. expect body.deletedAt type null passes for a JSON null and fails for an absent field.

>>>
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 Operators (5 operators)

Operator	Syntax	Description
`length`	`expect body.items length 10`	Length equals exact value
`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

Works on strings (counting characters, so "日本語" has length 3), arrays, and objects (counts keys).

>>>
expect body.users length > 0
expect body.users length <= 100
expect body.name length >= 1
<<<

Array Operators (5 operators)

Operator	Syntax	Description
`includes`	`expect body.tags includes "admin"`	Array contains the value
`!includes`	`expect body.tags !includes "test"`	Array does not contain the 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`	Assertion applied to every array element

includes / !includes

Checks whether an array contains (or does not contain) a specific value:

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

in / !in

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

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

each

Applies an assertion to every element in an array. Useful for validating list shapes. After each write an operator and a value, optionally preceded by a path inside the element:

>>>
expect body.users each type object
expect body.users each > 0
expect body.users each body.id exists
expect body.users each email matches /^.+@.+\..+$/
<<<

body (or a leading .) names the element itself. An empty array passes. You can also use each with an operator/value map:

>>>
expect body.items each {"operator": "type", "value": "object"}
<<<

Schema and Snapshot (2 operators)

Operator	Syntax	Description
`schema`	`expect body schema ./schema.json`	Validate against a JSON Schema file
`snapshot`	`expect body snapshot "name"`	Compare against a saved snapshot

schema

Validates the response body against a JSON Schema file. File paths are relative to the .http file.

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

snapshot

Compares the response body against a previously saved baseline. A plain run never creates a snapshot: if none exists the assertion fails with “snapshot does not exist (run with —update-snapshots to create)”. Create the baseline once with --update-snapshots; after that, differences cause failure.

>>>
expect body snapshot "user-profile"
<<<

Create snapshots, or update them when the response intentionally changes:

hitspec run tests/ --update-snapshots

Quick Reference

#	Operator	Category	Example
1	`==`	Equality	`expect status == 200`
2	`!=`	Equality	`expect body.error != null`
3	`>`	Comparison	`expect body.count > 0`
4	`>=`	Comparison	`expect body.count >= 1`
5	`<`	Comparison	`expect duration < 1000`
6	`<=`	Comparison	`expect duration <= 500`
7	`contains`	String	`expect body contains "ok"`
8	`!contains`	String	`expect body !contains "error"`
9	`startsWith`	String	`expect body.url startsWith "https"`
10	`endsWith`	String	`expect body.email endsWith ".com"`
11	`matches`	String	`expect body.id matches /^\d+$/`
12	`exists`	Existence	`expect body.id exists`
13	`!exists`	Existence	`expect body.error !exists`
14	`type`	Type	`expect body.items type array`
15	`length`	Length	`expect body.items length 10`
16	`length >`	Length	`expect body.items length > 0`
17	`length >=`	Length	`expect body.items length >= 1`
18	`length <`	Length	`expect body.items length < 100`
19	`length <=`	Length	`expect body.items length <= 50`
20	`includes`	Array	`expect body.tags includes "admin"`
21	`!includes`	Array	`expect body.tags !includes "test"`
22	`in`	Array	`expect status in [200, 201]`
23	`!in`	Array	`expect status !in [400, 500]`
24	`each`	Array	`expect body.items each type object`
25	`schema`	Validation	`expect body schema ./schema.json`
26	`snapshot`	Validation	`expect body snapshot "name"`

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Assertion Operators

Equality and Comparison (6 operators)

String Operators (5 operators)

Existence and Type (3 operators)

Length Operators (5 operators)

Array Operators (5 operators)

includes / !includes

in / !in

each

Schema and Snapshot (2 operators)

schema

snapshot

Quick Reference