The .http file format for API tests

hitspec tests live in plain text files with .http or .hitspec extensions. Each file contains one or more HTTP requests along with optional variables, assertions, and captures.

Minimal Example

The smallest valid test is a request with one assertion:

GET https://api.example.com/health

>>>
expect status 200
<<<

File Structure

A typical .http file follows this structure:

@baseUrl = https://api.example.com
@token = my-secret-token

### Get all users
# @name getUsers
# @tags smoke, users

GET {{baseUrl}}/users
Authorization: Bearer {{token}}

>>>
expect status 200
expect body type array
<<<

>>>capture
total from header X-Total-Count
<<<

### Get single user
# @name getUser
# @depends getUsers

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id == 1
<<<

Request Separator

Use ### to separate multiple requests within a single file. Everything before the first ### (or before the first request line if no separator is used) is treated as the file-level scope for variable definitions.

### First request
GET https://api.example.com/posts

>>>
expect status 200
<<<

### Second request
GET https://api.example.com/users

>>>
expect status 200
<<<

The ### separator is required when a file contains more than one request. Text after ### on the same line is treated as a human-readable title and is ignored by the parser.

Variables

Define variables at the top of a file using the @variable = value syntax:

@baseUrl = https://api.example.com
@apiVersion = v1
@timeout = 5000

Reference them anywhere in the file with double curly braces:

GET {{baseUrl}}/{{apiVersion}}/users

See Variables for the full variable system including built-in functions and captures.

Request Line

Every request starts with an HTTP method followed by a URL:

GET {{baseUrl}}/users
POST {{baseUrl}}/users
PUT {{baseUrl}}/users/1
PATCH {{baseUrl}}/users/1
DELETE {{baseUrl}}/users/1
HEAD {{baseUrl}}/health
OPTIONS {{baseUrl}}/users

The method is the first word and the URL is everything after it. An optional final HTTP/1.1-style token is read as the protocol version and is not part of the URL. Spaces inside {{ ... }} never split the line, so built-in function arguments and padded variable names work in a URL:

GET {{ baseUrl }}/search?q={{$urlEncode(hello world)}}&n={{$random(1, 100)}}

Headers

Headers follow the request line, one per line, using standard Name: Value format:

POST {{baseUrl}}/users
Content-Type: application/json
Authorization: Bearer {{token}}
Accept: application/json
X-Request-Id: {{$uuid()}}

Everything after the first : is the header value, trimmed of surrounding whitespace and otherwise sent exactly as written: quotes, # and apostrophes are part of the value.

If-None-Match: "33a64df5"
Content-Disposition: attachment; filename="report.txt"
X-Color: #fff

Comment lines (# ... or // ...) between the request line and the blank line are skipped, and headers after them are still headers. A # @name x line in this position is only a comment; put directives before the request line.

A blank line separates headers from the request body. Any lines after the blank line (until the next block marker or separator) are treated as the body.

Request Body

JSON

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

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin"
}

Form URL-Encoded

Use the & prefix syntax for readable form data:

POST {{baseUrl}}/login
Content-Type: application/x-www-form-urlencoded

& username = john
& password = secret123
& remember = true

Multipart Form Data

Use the >>>multipart block for file uploads and mixed form data:

POST {{baseUrl}}/upload

>>>multipart
field name = John Doe
field email = john@example.com
file avatar @./photo.jpg
file @./report.pdf
<<<

file <name> @<path> sends the file as form field <name>; file @<path> uses the field name file. A file that cannot be read fails the request with an error naming the path.

GraphQL

Use >>>graphql and >>>variables blocks:

POST {{baseUrl}}/graphql
Content-Type: application/json

>>>graphql
query GetUsers($limit: Int) {
  users(limit: $limit) {
    id
    name
    email
  }
}
<<<

>>>variables
{
  "limit": 10
}
<<<

XML

POST {{baseUrl}}/soap
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <action>getUser</action>
  <id>123</id>
</request>

File-Based Body

Reference an external file as the request body using < ./path:

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

< ./fixtures/user.json

The file path is resolved relative to the .http file’s directory. A file that cannot be read fails the request with an error naming the path; hitspec does not send the path text instead. Content-Type is auto-detected from the file extension (.json, .xml, .yaml, .html, .csv, .txt) when no explicit Content-Type header is set. Variable interpolation works in the file path:

POST {{baseUrl}}/import
Content-Type: application/json

< ./fixtures/{{scenario}}.json

Query Parameters

Inline with the URL:

GET {{baseUrl}}/search?query=test&limit=10

Or use the explicit ? prefix syntax for readability:

GET {{baseUrl}}/search
? query = test
? limit = 10
? sort = created_at
? order = desc

Query parameters written as ? name = value lines are appended to the URL in the order you wrote them, repeated names are all sent, and names and values are percent-encoded (a space is %20). Characters that cannot appear in a URL (spaces, quotes, non-ASCII) in the URL itself are percent-encoded too; %XX escapes you wrote are kept. In a form block (& name = value lines) values keep their spaces and each name and value is percent-encoded when sent. A body written inline as a=b&c=d is sent exactly as written.

Assertion Blocks

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

GET {{baseUrl}}/users

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

Every line in the block is an expect line, a comment (# or //) or blank. A block must be closed with <<<, must follow a request line, and may appear more than once per request. Unknown operators, operators without a value and misspelt block types (>>>captur) are parse errors (exit code 2), not silently ignored. See Assertions for all 26 operators.

Capture Blocks

Capture response values for use in later requests:

POST {{baseUrl}}/auth/login
Content-Type: application/json

{"email": "test@example.com", "password": "secret"}

>>>capture
token from body.access_token
userId from body.user.id
<<<

See Captures for the full capture system.

Metadata Directives

Metadata directives are comments that start with # @ and control request behavior:

### Create user
# @name createUser
# @description Creates a new user account
# @tags smoke, users, write
# @timeout 10000
# @retry 3
# @retryDelay 1000
# @depends login
# @auth bearer {{login.token}}

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

{"name": "Test User"}

All Directives

Directive	Description	Example
`@name`	Request identifier for captures and dependencies	`# @name createUser`
`@description`	Human-readable description	`# @description Creates a user`
`@tags`	Comma-separated tags for filtering	`# @tags smoke, auth`
`@skip`	Skip this request	`# @skip Temporarily disabled`
`@only`	Run only this request	`# @only`
`@timeout`	Request timeout in milliseconds	`# @timeout 5000`
`@retry`	Number of retry attempts	`# @retry 3`
`@retryDelay`	Delay between retries in milliseconds	`# @retryDelay 1000`
`@retryOn`	Status codes that trigger a retry	`# @retryOn 500, 502, 503`
`@depends`	Request dependencies (comma-separated names)	`# @depends login, setup`
`@auth`	Authentication method	`# @auth bearer {{token}}`
`@before`	Shell script to run before the request	`# @before ./setup.sh`
`@after`	Shell script to run after the request (always runs)	`# @after ./cleanup.sh`
`@db`	Database connection for DB assertions	`# @db sqlite://./test.db`
`@waitFor`	Poll URL until ready before executing	`# @waitFor {{baseUrl}}/health 200 30000 1000`
`@if`	Run only when the condition is true (a truthy value, or a `==` / `!=` comparison)	`# @if {{env}} == "prod"`
`@unless`	Skip when the condition is true	`# @unless {{skipAuth}}`
`@stress.weight`	Relative selection weight for stress tests	`# @stress.weight 3`
`@stress.think`	Think time in ms after this request (stress)	`# @stress.think 500`
`@stress.skip`	Exclude from stress testing	`# @stress.skip`
`@stress.setup`	Run once before stress test starts	`# @stress.setup`
`@stress.teardown`	Run once after stress test ends	`# @stress.teardown`

Directives not in this table are reported by hitspec validate as warnings (# @tag is probably # @tags), except custom ones starting with x- (# @x-owner team-a) and @contract.*. A request may start with its # @directives and omit the ### line.

@waitFor — Service Readiness Polling

The @waitFor directive polls a URL before executing the request. This is useful when your test depends on a service that may not be immediately available (e.g., a container that was just started).

### Create order (waits for payment service)
# @waitFor http://localhost:4000/health 200 30000 1000

POST {{baseUrl}}/orders
Content-Type: application/json

{"product": "Widget", "quantity": 1}

Syntax:

# @waitFor <url> [status] [timeout_ms] [interval_ms]

Parameter	Default	Description
`url`	(required)	URL to poll
`status`	`200`	Expected HTTP status code
`timeout_ms`	`30000`	Maximum time to wait (milliseconds)
`interval_ms`	`1000`	Time between poll attempts (milliseconds)

If the URL does not return the expected status within the timeout, the request fails without executing. When the target cannot be reached at all (connection refused, DNS failure), the run exits with code 4. The poll uses the same HTTP client settings as the run (default headers, proxy, CA bundle, --insecure).

@if / @unless — Conditional Execution

Skip requests based on variable values:

### Run only in CI
# @if {{CI}}

POST {{baseUrl}}/deploy

### Skip when auth is disabled
# @unless {{skipAuth}}
# @auth bearer {{token}}

GET {{baseUrl}}/admin

A bare value is truthy when it is defined and not empty, "0", "false", "no" or "null". An undefined variable is falsy. Conditions can compare with == and !=, negate with !, and combine with && and || (&& binds tighter):

### Only against production
# @if {{env}} == "prod"

POST {{baseUrl}}/deploy

### Everything except staging, when enabled
# @if {{env}} != staging && {{runSlow}}

GET {{baseUrl}}/slow

Each side of a comparison is resolved on its own and compared as text (as numbers when both sides are numbers); quotes around either side are ignored. An undefined variable counts as empty, so {{missing}} == "prod" is false and {{missing}} != "prod" is true. Without a comparison, # @if {{env}} is true for any non-empty value, so use == to test for a specific one.

Stress Test Annotations

Fine-tune how individual requests behave during stress testing:

### Create session (setup)
# @name createSession
# @stress.setup

POST {{baseUrl}}/sessions

### High-traffic endpoint
# @name getProducts
# @stress.weight 5
# @stress.think 200

GET {{baseUrl}}/products

### Cleanup (teardown)
# @name deleteSession
# @stress.teardown

DELETE {{baseUrl}}/sessions/{{createSession.id}}

### Exclude from load test
# @name healthCheck
# @stress.skip

GET {{baseUrl}}/health

Annotation	Description
`@stress.weight N`	Relative selection weight (default 1). Higher weight = more frequent selection.
`@stress.think N`	Think time in milliseconds after this request completes.
`@stress.skip`	Exclude this request from stress test execution.
`@stress.setup`	Run this request once before the stress test starts.
`@stress.teardown`	Run this request once after the stress test ends.

Comments

Lines starting with # that do not have an @ directive are treated as regular comments and ignored:

# This is a comment
# Another comment

### Get users
# @name getUsers

# The following request fetches all active users
GET {{baseUrl}}/users?active=true

Authentication

Use @auth to attach credentials to a request. hitspec supports 8 authentication methods:

# @auth bearer {{token}}

GET {{baseUrl}}/me

# @auth basic {{username}}, {{password}}

GET {{baseUrl}}/admin

# @auth apiKey X-API-Key, {{apiKey}}

GET {{baseUrl}}/data

# @auth apiKeyQuery api_key, {{apiKey}}

GET {{baseUrl}}/data

# @auth digest {{username}}, {{password}}

GET {{baseUrl}}/secure

# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}

GET {{baseUrl}}/s3/object

# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}, {{sessionToken}}

GET {{baseUrl}}/s3/object

# @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2

GET {{baseUrl}}/protected

# @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2

GET {{baseUrl}}/protected

File Extensions

hitspec recognizes two file extensions:

.http — the standard extension, compatible with REST Client and other HTTP file tools
.hitspec — an alternative extension for files that use hitspec-specific features

Both are functionally identical.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

The .http file format for API tests

Minimal Example

File Structure

Request Separator

Variables

Request Line

Headers

Request Body

JSON

Form URL-Encoded

Multipart Form Data

GraphQL

XML

File-Based Body

Query Parameters

Assertion Blocks

Capture Blocks

Metadata Directives

All Directives

@waitFor — Service Readiness Polling

@if / @unless — Conditional Execution

Stress Test Annotations

Comments

Authentication

File Extensions