Assertions
Validate responses directly from the command line. Check status codes, response body, headers, response time, and JSON values with natural-language expressions.
Assertion Syntax
Basic Usage
Add assertions with -a / --assert. The format is: target operator expected. You can use multiple assertions per request.
# Using -a (short form)
tgrs GET https://api.example.com/health -a "status eq 200"
# Using --assert (long form)
tgrs GET https://api.example.com/health --assert "status eq 200"
# Multiple assertions
tgrs GET https://api.example.com/users \
-a "status eq 200" \
-a "body contains users" \
-a "response_time lt 500"
# Comma-separated (multiple in one flag)
tgrs GET https://api.example.com/users \
-a "status eq 200, body contains users, response_time lt 500"
0 if all assertions pass, or exit code 1 if any assertion fails. This makes it easy to use in CI/CD pipelines.Assertion Targets
Status Code
# Check exact status
tgrs GET https://api.example.com/users -a "status eq 200"
tgrs GET https://api.example.com/users -a "status equals 200"
# Check status is not an error
tgrs GET https://api.example.com/users -a "status lt 400"
# Check for specific error
tgrs GET https://api.example.com/missing -a "status eq 404"
Response Body
# Body contains a string
tgrs GET https://api.example.com/users -a "body contains users"
# Body does not contain error
tgrs GET https://api.example.com/users -a "body not_contains error"
# Body is not empty
tgrs GET https://api.example.com/users -a "body is_not_empty"
# Body matches regex
tgrs GET https://api.example.com/users/1 -a 'body matches_regex "id":\s*\d+'
Response Time
# Response time under 500ms
tgrs GET https://api.example.com/health -a "response_time lt 500"
# Response time under 2 seconds
tgrs GET https://api.example.com/data -a "response_time lt 2000"
Response Headers
# Header exists
tgrs GET https://api.example.com/users -a "header content-type exists"
# Header contains value
tgrs GET https://api.example.com/users -a "header content-type contains json"
# Header equals exact value
tgrs GET https://api.example.com/users -a "header x-powered-by equals Express"
JSON Path
Start your assertion target with $. to assert on specific values within a JSON response. No keyword needed — tgrs automatically recognizes JSONPath expressions.
# Check a nested JSON value
tgrs GET https://api.example.com/users/1 -a "$.name equals John"
# Check array is not empty
tgrs GET https://api.example.com/users -a "$.users is_not_empty"
# Check value type
tgrs GET https://api.example.com/users/1 -a "$.id is_type number"
# Check first array element
tgrs GET https://api.example.com/users -a "$.users[0].role equals admin"
Assertion Targets
All Targets
The target is the first part of an assertion — what you want to check.
| Target | Syntax | Description |
|---|---|---|
| status | status operator value | HTTP status code (e.g., 200, 404, 500) |
| response_time | response_time operator ms | Response time in milliseconds |
| header | header name operator value | Response header value (case-insensitive name) |
| body | body operator value | Full response body as string |
| $. | $.path operator value | JSON path — dot notation with array indexing (e.g., $.users[0].name) |
Operators
All Operators
Each operator has short and long forms. Use whichever feels more natural.
| Short | Long | Description |
|---|---|---|
| eq | equals | Exact match |
| neq | not_equals | Not equal |
| gt | greater_than | Numeric greater than |
| lt | less_than | Numeric less than |
| contains | String contains | |
| not_contains | String does not contain | |
| exists | Value exists (not null) | |
| not_exists | Value is null or missing | |
| is_empty | Empty string, array, or object | |
| is_not_empty | Non-empty value | |
| matches_regex | Regex pattern match | |
| is_type | Check JSON type (string, number, boolean, array, object, null) |
CI/CD Usage
Health Check Script
Use assertions in CI/CD pipelines to verify API health after deployments.
# Health check with multiple assertions
tgrs GET https://api.example.com/health \
-a "status eq 200, response_time lt 1000, body contains healthy"
# Exit code 0 = all passed, 1 = failure
Contract Testing
Verify API response structure matches your expectations.
tgrs GET https://api.example.com/users/1 \
-a "status eq 200" \
-a "header content-type contains json" \
-a "$.id is_type number" \
-a "$.name is_type string" \
-a "$.email contains @"
--json output for machine-readable results in your CI pipeline.