Variable Interpolation

Variable interpolation is the mechanism that replaces {{placeholder}} expressions with actual values at runtime. This page covers all interpolation contexts, resolution rules, and advanced patterns.

Interpolation Syntax

All interpolation uses double curly braces:

{{variableName}}

Where Interpolation Works

Variables can appear in:

Context	Example
URLs	`GET {{baseUrl}}/users/{{userId}}`
Headers	`Authorization: Bearer {{token}}`
Request bodies	`{"name": "{{userName}}"}`
Query parameters	`? key = {{apiKey}}`
Assertion values	`expect body.name == "{{expectedName}}"`
Variable definitions	`@apiPath = {{baseUrl}}/v1`
Metadata directives	`# @auth bearer {{token}}`
Metadata arguments	`# @timeout {{timeoutMs}}`

Variable Sources

Inline Variables

Defined at the top of a .http file:

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

Environment Variables

From hitspec.yaml environments section:

environments:
  dev:
    baseUrl: http://localhost:3000
    token: dev-token

System Environment Variables

Using the $env() function:

@token = {{$env(API_TOKEN)}}
@dbUrl = {{$env(DATABASE_URL, sqlite://./test.db)}}

Built-in Functions

Dynamic values generated at runtime:

{
  "id": "{{$uuid()}}",
  "timestamp": {{$timestamp()}},
  "email": "{{$randomEmail()}}"
}

Captured Values

Values extracted from prior responses:

GET {{baseUrl}}/users/{{login.userId}}
Authorization: Bearer {{login.token}}

Resolution Order

When the same variable name exists in multiple sources, hitspec resolves in this order (later sources win):

Config environments — hitspec.yaml environments section for the active --env
Inline variables — @variable = value in the file
Captured values — {{requestName.captureName}}

Built-in functions ($uuid(), $timestamp(), $env(), …) and system variables ({{$VAR}}) are evaluated wherever they appear. An inline variable that references its own name, such as @baseUrl = {{baseUrl}}, resolves that reference against the lower layers (the config environment, then .env, then the OS environment). The file default therefore delegates to the environment. Captured values are inserted literally. A captured value that contains {{...}} (for example a response body with {{$env(SECRET)}}) is never expanded, so a server cannot read your local variables through a capture.

Capture Chains

Chain captures across dependent requests:

### Step 1: Login
# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

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

>>>capture
token from body.access_token
<<<

### Step 2: Create resource
# @name createResource
# @depends login

POST {{baseUrl}}/resources
Authorization: Bearer {{login.token}}
Content-Type: application/json

{"name": "New Resource"}

>>>capture
resourceId from body.id
<<<

### Step 3: Get resource
# @depends createResource

GET {{baseUrl}}/resources/{{createResource.resourceId}}
Authorization: Bearer {{login.token}}

>>>
expect status 200
<<<

Step 3 references captures from both Step 1 (login.token) and Step 2 (createResource.resourceId).

Nested Interpolation

Variables can reference other variables:

@baseUrl = https://api.example.com
@apiPath = {{baseUrl}}/v2
@usersEndpoint = {{apiPath}}/users

GET {{usersEndpoint}}

Captured and interpolated non-string values are inserted as their JSON text: numbers keep their exact digits (1000000, 123456789012), booleans are true or false, null is null, and objects and arrays are compact JSON.

Unresolved Variables

If a variable cannot be resolved, it remains as the literal {{variableName}} string in the request. hitspec does not error on unresolved variables — the request is sent with the raw placeholder, which typically causes a server-side error that surfaces through your assertions.

Use --verbose (or -v) to see resolved variable values in the output, which helps debug interpolation issues.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Variable Interpolation

Interpolation Syntax

Where Interpolation Works

Variable Sources

Inline Variables

Environment Variables

System Environment Variables

Built-in Functions

Captured Values

Resolution Order

Capture Chains

Nested Interpolation

Unresolved Variables