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)

atra GET https://api.example.com/health -a "status eq 200"

# Using --assert (long form)

atra GET https://api.example.com/health --assert "status eq 200"

# Multiple assertions

atra 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)

atra GET https://api.example.com/users \

-a "status eq 200, body contains users, response_time lt 500"

Exit Codes: When assertions are used, atra returns exit code 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

atra GET https://api.example.com/users -a "status eq 200"

atra GET https://api.example.com/users -a "status equals 200"

# Check status is not an error

atra GET https://api.example.com/users -a "status lt 400"

# Check for specific error

atra GET https://api.example.com/missing -a "status eq 404"

Response Body

# Body contains a string

atra GET https://api.example.com/users -a "body contains users"

# Body does not contain error

atra GET https://api.example.com/users -a "body not_contains error"

# Body is not empty

atra GET https://api.example.com/users -a "body is_not_empty"

# Body matches regex

atra GET https://api.example.com/users/1 -a 'body matches_regex "id":\s*\d+'

Response Time

# Response time under 500ms

atra GET https://api.example.com/health -a "response_time lt 500"

# Response time under 2 seconds

atra GET https://api.example.com/data -a "response_time lt 2000"

Response Headers

# Header exists

atra GET https://api.example.com/users -a "header content-type exists"

# Header contains value

atra GET https://api.example.com/users -a "header content-type contains json"

# Header equals exact value

atra 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, because atra automatically recognizes JSONPath expressions.

# Check a nested JSON value

atra GET https://api.example.com/users/1 -a "$.name equals John"

# Check array is not empty

atra GET https://api.example.com/users -a "$.users is_not_empty"

# Check value type

atra GET https://api.example.com/users/1 -a "$.id is_type number"

# Check first array element

atra 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, naming 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 in 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

atra 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.

atra 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 @"

Tip: Combine assertions with --json output for machine-readable results in your CI pipeline.

Dynamic Variables Output