Environments

hitspec supports environment-specific configuration so you can run the same tests against different servers, credentials, and settings without modifying your test files.

Overview

There are four ways to provide variables:

Inline variables — @var = value in .http files (same for all environments)
Config file — hitspec.yaml with an environments section (per-environment values)
.env files — standard dotenv files injected with --env-file
System environment variables — accessed via {{$VAR}} or the $env() function

Per-environment variables live in hitspec.yaml under the environments: key. There is no separate JSON environment file — hitspec.yaml and .env files are the supported sources.

Inline Variables

Define variables directly in your test file:

@baseUrl = https://api.example.com
@token = your-api-token
@timeout = 5000

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

This is simple but limited:

Values are the same regardless of environment
Secrets are visible in the test file
Switching environments requires editing the file

Inline variables are best for values that do not change between environments, such as API version paths or test data.

Config File (hitspec.yaml)

The hitspec.yaml config file combines global settings with per-environment variable sets under the environments: key:

# Global settings
defaultEnvironment: dev
timeout: 30000        # milliseconds (integer)
retries: 0
followRedirects: true
validateSSL: true
verbose: false
headers:
  User-Agent: hitspec/1.0

# Per-environment variables
environments:
  dev:
    baseUrl: https://api-dev.example.com
    token: dev-token
  staging:
    baseUrl: https://api-staging.example.com
    token: "${STAGING_TOKEN}"   # expands from the OS environment
  prod:
    baseUrl: https://api.example.com
    token: "${PROD_TOKEN}"

Select the environment with the --env flag (defaults to dev):

# Uses the default environment
hitspec run tests/

# Use staging
hitspec run tests/ --env staging

# Use production
hitspec run tests/ --env prod

Your test files reference variables without knowing which environment is active:

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

>>>
expect duration < {{timeout}}
<<<

hitspec searches for config files in this order:

hitspec.yaml
hitspec.yml

You can also specify a config file explicitly:

hitspec run tests/ --config ./config/hitspec.yaml

Inside hitspec.yaml, environment values can reference OS environment variables with shell-style ${VAR} syntax — ideal for keeping secrets out of the file and injecting them from CI secrets.

.env Files

Pass a standard dotenv file with the --env-file flag to inject additional variables:

hitspec run tests/ --env staging --env-file .env.staging

The .env file uses standard KEY=VALUE format:

API_TOKEN=staging-secret-token
DB_PASSWORD=staging-db-pass

These values are exported to the process environment, so they’re available via ${VAR} in hitspec.yaml and via {{$VAR}} / {{$env(VAR)}} in your requests.

System Environment Variables

Reference system environment variables in your test files. Two forms are supported:

# Simple form -- direct lookup
@token = {{$API_TOKEN}}

# Function form -- supports an optional default value
@token = {{$env(API_TOKEN)}}
@dbUrl = {{$env(DATABASE_URL, sqlite://./test.db)}}

The second argument to $env() is an optional fallback used when the variable is unset.

The dotted form {{$env.VAR}} is not supported. Use {{$VAR}} or {{$env(VAR)}}.

In hitspec.yaml, use shell-style ${VAR} syntax instead:

environments:
  prod:
    token: "${PROD_TOKEN}"

HITSPEC_ Environment Variables

All major CLI flags can be set via environment variables with the HITSPEC_ prefix, which is useful in CI/CD pipelines:

Environment Variable	CLI Flag	Description
`HITSPEC_ENV`	`--env`	Environment to use
`HITSPEC_ENV_FILE`	`--env-file`	Path to .env file
`HITSPEC_CONFIG`	`--config`	Path to config file
`HITSPEC_TIMEOUT`	`--timeout`	Request timeout (duration, e.g. `30s`)
`HITSPEC_TAGS`	`--tags`	Filter by tags
`HITSPEC_OUTPUT`	`--output`	Output format
`HITSPEC_OUTPUT_FILE`	`--output-file`	Output file path
`HITSPEC_BAIL`	`--bail`	Stop on first failure
`HITSPEC_PARALLEL`	`--parallel`	Run in parallel
`HITSPEC_CONCURRENCY`	`--concurrency`	Concurrent requests
`HITSPEC_QUIET`	`--quiet`	Suppress output
`HITSPEC_NO_COLOR`	`--no-color`	Disable colors
`HITSPEC_PROXY`	`--proxy`	Proxy URL
`HITSPEC_INSECURE`	`--insecure`	Skip SSL verification

export HITSPEC_ENV=staging
export HITSPEC_TIMEOUT=60s
export HITSPEC_BAIL=true
hitspec run tests/

Variable Resolution Order

When the same variable name comes from multiple sources, hitspec resolves it in this order (later sources override earlier ones):

hitspec.yaml environment — values for the active --env
Inline variables — @variable = value in the .http file
Captured values — {{requestName.captureName}} from prior responses

Built-in functions ($uuid(), $timestamp(), $env(), …) and system variables ({{$VAR}}) are evaluated wherever they appear.

Inline variables override hitspec.yaml environment values. A @baseUrl = ... in your .http file takes precedence over the baseUrl defined for the active environment — remove the inline definition when you want environment-specific values to apply.

Best Practices

Keep Secrets Out of Version Control

Keep secrets in a .env file (or your CI secret store) and reference them with ${VAR} in hitspec.yaml, rather than committing tokens. Add the .env file to .gitignore:

.env
.env.*

Commit a template instead:

# .env.example
API_TOKEN=YOUR_TOKEN_HERE
DB_PASSWORD=YOUR_DB_PASSWORD_HERE

# hitspec.yaml (committed -- no secrets)
environments:
  staging:
    baseUrl: https://staging.api.example.com
    token: "${API_TOKEN}"

Use System Variables in CI/CD

GitHub Actions
Shell

env:
  API_BASE_URL: https://staging.api.example.com
  API_TOKEN: ${{ secrets.API_TOKEN }}

steps:
  - uses: abdul-hamid-achik/hitspec@v1
    with:
      files: tests/
      env: ci
      env-file: .env.ci

# Set variables inline
API_TOKEN=secret hitspec run tests/ --env staging

# Or export them
export API_TOKEN=secret
export DB_PASSWORD=dbpass
hitspec run tests/ --env staging

Shared Base Configuration

Reuse YAML anchors in hitspec.yaml to share values across environments:

environments:
  dev:
    baseUrl: http://localhost:3000
    apiVersion: &apiVersion v1
  prod:
    baseUrl: https://api.example.com
    apiVersion: *apiVersion

Environment-Specific Test Behavior

Drive timeouts, retry settings, and other behavioral differences from environment variables:

environments:
  dev:
    baseUrl: http://localhost:3000
    timeout: "30000"
    retries: "3"
  prod:
    baseUrl: https://api.example.com
    timeout: "5000"
    retries: "0"

# @timeout {{timeout}}
# @retry {{retries}}

GET {{baseUrl}}/slow-endpoint

>>>
expect status 200
<<<

Recommended Project Structure

my-api-tests/
├── hitspec.yaml        # Global config and environment definitions (committed)
├── .env                # Secret values (gitignored)
├── .env.example        # Template for team members (committed)
├── .gitignore
├── tests/
│   ├── auth.http
│   ├── users.http
│   └── orders.http
└── schemas/
    └── user.json

Troubleshooting

Variable not found

Error: variable "baseUrl" not found

Check that hitspec.yaml defines the variable under the active environment.
Verify the --env flag matches an environment key: hitspec run tests/ --env dev.
Check for typos in variable names (they are case-sensitive).

Environment not found

Error: environment "staging" not found

Add a staging: key under environments: in hitspec.yaml.
Check for typos in the environment name.

System variable not set

Error: environment variable "API_TOKEN" not set

Export the variable: export API_TOKEN=xxx
Set it inline: API_TOKEN=xxx hitspec run tests/
Pass it via a dotenv file: hitspec run tests/ --env-file .env
In CI/CD, add it to your secrets and pass it to the workflow.
Use a default value: {{$env(API_TOKEN, fallback-value)}}

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Overview

Inline Variables

Config File (hitspec.yaml)

.env Files

System Environment Variables

HITSPEC_ Environment Variables

Variable Resolution Order

Best Practices

Keep Secrets Out of Version Control

Use System Variables in CI/CD

Shared Base Configuration

Environment-Specific Test Behavior

Recommended Project Structure

Troubleshooting

​Overview

​Inline Variables

​Config File (hitspec.yaml)

​.env Files

​System Environment Variables

​HITSPEC_ Environment Variables

​Variable Resolution Order

​Best Practices

​Keep Secrets Out of Version Control

​Use System Variables in CI/CD

​Shared Base Configuration

​Environment-Specific Test Behavior

​Recommended Project Structure

​Troubleshooting

Overview

Inline Variables

Config File (hitspec.yaml)

.env Files

System Environment Variables

HITSPEC_ Environment Variables

Variable Resolution Order

Best Practices

Keep Secrets Out of Version Control

Use System Variables in CI/CD

Shared Base Configuration

Environment-Specific Test Behavior

Recommended Project Structure

Troubleshooting