Skip to main content
Variables let you avoid hardcoding values in your test files. hitspec supports inline definitions, environment files, built-in functions, system environment references, and captured values from previous responses.

​
Defining Variables

Use the @variable = value syntax at the top of a .http file: 
@baseUrl = https://api.example.com
@token = my-api-token
@userId = 42

​
Interpolation

Reference variables anywhere in your requests using double curly braces: 
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{token}}
Variables can appear in:
  • URLs
  • Headers
  • Request bodies
  • Query parameters
  • Assertion values
  • Other variable definitions
  • Metadata directive arguments
@baseUrl = https://api.example.com
@apiPath = {{baseUrl}}/v1

### Create user
# @timeout {{timeout}}
# @auth bearer {{token}}

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

{
  "name": "User {{$random(1, 1000)}}",
  "email": "{{$randomEmail()}}"
}

>>>
expect status 201
expect body.name startsWith "User"
<<<

​
Built-in Functions

hitspec provides 17 built-in functions that generate dynamic values at runtime. Call them with the $functionName() syntax inside double curly braces.

​
Identity and Randomness

FunctionDescriptionExample Output
{{$uuid()}}Generate a UUID v4550e8400-e29b-41d4-a716-446655440000
{{$random(min, max)}}Random integer in range42
{{$randomString(len)}}Random alphanumeric stringaB3kL9mN
{{$randomAlphanumeric(len)}}Random alphanumeric stringK8mNp2qRsT
{{$randomEmail()}}Random email addressuser_abc123@example.com

​
Date and Time

FunctionDescriptionExample Output
{{$timestamp()}}Unix timestamp in seconds1705612800
{{$timestampMs()}}Unix timestamp in milliseconds1705612800000
{{$now()}}Current datetime in RFC 33392024-01-18T12:00:00Z
{{$date(format)}}Custom date format (Go layout, default: 2006-01-02)2024-01-18
The $date() function uses Go’s reference time layout. The reference date is Mon Jan 2 15:04:05 MST 2006. For example, {{$date(2006-01-02)}} produces 2024-01-18.

​
Encoding and Hashing

FunctionDescriptionExample Output
{{$base64(value)}}Base64 encodeaGVsbG8=
{{$base64Decode(value)}}Base64 decodehello
{{$md5(value)}}MD5 hash5d41402abc4b2a76...
{{$sha256(value)}}SHA256 hash2cf24dba5fb0a30e...
{{$urlEncode(value)}}URL-encode a stringhello%20world
{{$urlDecode(value)}}URL-decode a stringhello world

​
Utilities

FunctionDescriptionExample Output
{{$json(value)}}JSON passthrough{"key": "value"}
{{$env(VAR, default)}}System environment variable with optional default(value of $VAR)

​
Practical Examples

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

{
  "id": "{{$uuid()}}",
  "name": "Test User {{$random(1, 9999)}}",
  "email": "{{$randomEmail()}}",
  "createdAt": "{{$now()}}"
}

​
System Environment Variables

Access system environment variables with $env(): 
@token = {{$env(API_TOKEN)}}
@dbUrl = {{$env(DATABASE_URL, sqlite://./test.db)}}
The second argument is an optional default value used when the environment variable is not set. You can also reference system variables in your environment file (.hitspec.env.json): 
{
  "prod": {
    "baseUrl": "https://api.example.com",
    "token": "{{$env.API_TOKEN}}",
    "dbPassword": "{{$env.DB_PASSWORD}}"
  }
}

​
Capture References

When a request captures values from its response, subsequent requests can reference them using the {{requestName.captureName}} pattern: 
### Login
# @name login

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

### Get profile
# @depends login

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

>>>
expect status 200
expect body.id == "{{login.userId}}"
<<<
Capture references require that (1) the source request has a @name directive, (2) the source request has a >>>capture block, and (3) the consuming request declares @depends on the source request.
See Captures and Dependencies for more detail.

​
Variable Resolution Order

When the same variable name is defined in multiple places, hitspec resolves it in this order (later sources override earlier ones):
  1. Built-in functions — $uuid(), $timestamp(), etc.
  2. Environment file — values from .hitspec.env.json for the active environment
  3. hitspec.yaml environments — values from the environments section of config
  4. Inline variables — @variable = value in the .http file
  5. Captured values — {{requestName.captureName}} from prior responses
Inline variables (@var = value) override environment file values. This is useful for local overrides during development, but be careful not to accidentally shadow environment-specific configuration.

​
Variable Scope

Variables defined with @variable = value are scoped to the file in which they appear. Every request in that file can reference them. Captured variables are scoped to the entire test run. Any request in any file can reference a captured value, as long as the capturing request has already executed (enforced by @depends). Environment variables (from .hitspec.env.json or hitspec.yaml) are global and available to all files in the test run.