Configuration Reference

hitspec is configured through a hitspec.yaml (or hitspec.yml) file in your project root (hitspec also finds it from a subdirectory of the project; see Config File Search). All settings are optional — hitspec uses sensible defaults when no config file is present.

Creating a Config File

Run hitspec init to generate a starter configuration:

hitspec init

This creates a hitspec.yaml and an example.http file.

Full Configuration Reference

# hitspec.yaml - Complete configuration reference

# Default environment used when --env is not specified
defaultEnvironment: dev

# Request timeout in milliseconds (integer).
# Note: the --timeout CLI flag / HITSPEC_TIMEOUT env var use a duration
# string instead (e.g. 30s, 1m, 500ms).
timeout: 30000

# Number of automatic retries on failure (0 = no retries)
retries: 0

# Delay between retries in milliseconds
retryDelay: 1000

# Follow HTTP redirects (3xx responses)
followRedirects: true

# Maximum number of redirects to follow
maxRedirects: 10

# Validate SSL/TLS certificates
validateSSL: true

# HTTP proxy URL for all requests
proxy: ""

# TLS and HTTP client options (paths are relative to this file)
cacert: ""                     # PEM CA bundle trusted in addition to the system roots
cert: ""                       # PEM client certificate for mutual TLS (needs key)
key: ""                        # PEM private key for cert
http1: false                   # true disables HTTP/2
cookies: false                 # keep a cookie jar for the run
maxResponseBytes: 104857600    # largest response body in bytes (-1 = unlimited)
redirectForwardHeaders: false  # keep request headers on cross-origin redirects

# Default headers added to every request
headers:
  User-Agent: "hitspec/1.0"
  Accept: "application/json"

# Output reporters (can specify multiple)
reporters:
  - console

# Directory for the report files of non-console reporters
outputDir: ""

# Run independent requests in parallel
parallel: false

# Number of concurrent requests in parallel mode
concurrency: 5

# Stop execution on first failure
bail: false

# Enable verbose output
verbose: false

# Disable colored terminal output
noColor: false

# Inline environment definitions
environments:
  dev:
    baseUrl: "http://localhost:3000"
    token: "dev-token"
  staging:
    baseUrl: "https://staging.api.example.com"
    token: "staging-token"
  prod:
    baseUrl: "https://api.example.com"

# Stress testing profiles
stress:
  profiles:
    smoke:
      duration: "10s"
      rate: 5
    load:
      duration: "5m"
      rate: 100
      thresholds:
        p95: "200ms"
        errors: "1%"
    spike:
      duration: "2m"
      vus: 200
      maxVUs: 500
      rampUp: "30s"
      thinkTime: "500ms"

Options Reference

General

Option	Type	Default	Description
`defaultEnvironment`	string	`"dev"`	Environment used when `--env` is not specified
`timeout`	integer	`30000`	Request timeout in milliseconds
`retries`	integer	`0`	Number of automatic retries on failure
`retryDelay`	integer	`1000`	Delay between retries in milliseconds

Network

Option	Type	Default	Description
`followRedirects`	boolean	`true`	Follow HTTP 3xx redirects
`maxRedirects`	integer	`10`	Maximum number of redirects to follow
`validateSSL`	boolean	`true`	Validate SSL/TLS certificates
`proxy`	string	`""`	HTTP proxy URL (e.g., `http://proxy:8080`)
`cacert`	string	`""`	PEM CA bundle trusted in addition to the system roots. Relative to the directory of this file
`cert`	string	`""`	PEM client certificate for mutual TLS (needs `key`). Relative to this file
`key`	string	`""`	PEM private key for `cert`. Relative to this file
`http1`	boolean	`false`	`true` disables HTTP/2 (uses HTTP/1.1 only)
`cookies`	boolean	`false`	Keep a cookie jar for the run: `Set-Cookie` from one response is sent on later requests
`maxResponseBytes`	integer	`104857600`	Largest response body in bytes (0 = default, `-1` = unlimited)
`redirectForwardHeaders`	boolean	`false`	Keep your request headers on redirects to another origin

Relative cacert, cert and key paths in hitspec.yaml resolve against the directory of the file; a bad or missing file exits with code 3. See TLS, cookies and HTTP options.

Headers

Option	Type	Default	Description
`headers`	map	`null`	Default headers added to every request

headers:
  User-Agent: "hitspec/1.0"
  Accept: "application/json"
  X-Custom-Header: "value"

Headers defined in individual requests override config-level headers with the same name.

Output

Option	Type	Default	Description
`reporters`	string[]	`["console"]`	Reports `hitspec run` writes: `console`, `json`, `junit`, `tap`, `html` (names are case-insensitive)
`outputDir`	string	`""`	Directory for the report files, relative to this file. Created when a report is written there

Execution

Option	Type	Default	Description
`parallel`	boolean	`false`	Run independent requests in parallel
`concurrency`	integer	`5`	Max concurrent requests in parallel mode
`bail`	boolean	`false`	Stop on first failure
`verbose`	boolean	`false`	Enable verbose output
`noColor`	boolean	`false`	Disable colored terminal output

verbose: true is applied by hitspec run and means -v. A -v, -vv or -vvv flag wins over it, and --verbose=0 turns it off. The key must be a boolean. noColor: true is applied by hitspec run too: --no-color (or --no-color=false) on the command line wins, then HITSPEC_NO_COLOR, then the file. The NO_COLOR environment variable is also honored and can only turn colors off.

Reporters and outputDir

hitspec run writes one report per entry of reporters. console always goes to stdout. With outputDir set, every other reporter writes a file there, replaced on each run (and on each --watch pass):

Reporter	File in `outputDir`
`json`	`hitspec-results.json`
`junit`	`hitspec-junit.xml`
`tap`	`hitspec-results.tap`
`html`	`hitspec-report.html`

reporters:
  - console
  - junit
outputDir: reports

A relative outputDir is relative to the directory of the config file that sets it, not to the working directory. hitspec creates it before the run when at least one reporter writes a file there.
Without outputDir, every reporter writes to stdout, so only one is allowed. reporters: [junit] is the same as -o junit. Listing two or more exits with code 3.
An unknown reporter name exits with code 3. Duplicates are ignored. An empty list means ["console"].
-o/--output or --output-file on the command line, or a non-empty HITSPEC_OUTPUT or HITSPEC_OUTPUT_FILE, replace both keys: they are not read at all.
--quiet drops the report on stdout. The files are still written.
When no report goes to stdout (for example reporters: [junit] with outputDir: reports), the failed requests are listed on stderr, as with --quiet.
--stress and --dry-run ignore both keys.

Environments

Define per-environment variables inline:

environments:
  dev:
    baseUrl: "http://localhost:3000"
    dbUrl: "sqlite://./dev.db"
  staging:
    baseUrl: "https://staging.api.example.com"
    dbUrl: "postgres://user:pass@staging-db:5432/app"
  prod:
    baseUrl: "https://api.example.com"

Select the active environment with --env:

hitspec run tests/ --env staging

Variables defined in the active environment are available via {{variableName}} interpolation in your test files.

Stress Testing Profiles

Define reusable stress test profiles:

stress:
  profiles:
    load:
      duration: "5m"       # Test duration
      rate: 100            # Requests per second
      thresholds:
        p95: "200ms"       # 95th percentile must be under 200ms
        errors: "1%"       # Error rate must be under 1%
    vuser:
      duration: "2m"
      vus: 50              # Virtual users (alternative to rate)
      maxVUs: 100          # Max concurrent requests
      thinkTime: "1s"      # Pause between requests per VU
      rampUp: "30s"        # Time to ramp up to target VUs

Profile Option	Type	Description
`duration`	string	Test duration (e.g., `"30s"`, `"5m"`, `"1h"`)
`rate`	float	Target requests per second
`vus`	integer	Number of virtual users
`maxVUs`	integer	Maximum concurrent requests
`thinkTime`	string	Pause between requests per VU
`rampUp`	string	Ramp-up time to reach target
`thresholds`	map	Pass/fail thresholds (e.g., `p95: "200ms"`, `errors: "1%"`). A value may start with an operator (`p95: "<=250ms"`, `rps: ">=100"`); without one, `rps` means greater than and everything else less than. `errors: "0%"` means no request may fail

Use a profile with the --profile flag:

hitspec run api.http --stress --profile load

Config File Search

hitspec picks the config file in this order:

the path given with --config (or HITSPEC_CONFIG) — used as is;
otherwise the nearest hitspec.yaml (then hitspec.yml) found by looking in the working directory and then in each parent directory.

The search is bounded. It stops at the first directory that contains .git (your project root, after checking that directory itself), it never reads a config file from your home directory or from anything above it, and it stops at the filesystem root. If nothing is found, all default values are used. The working directory is where you ran the command for hitspec run, hitspec validate and hitspec contract verify, and the workspace directory for hitspec studio and hitspec serve. hitspec mcp serve never looks outside its workspace: a hitspec.yaml above the workspace root is ignored. Run hitspec run -v to print the config file in use on stderr. A config file that cannot be parsed stops the command with exit code 3 and a file:line message. An unknown key is only a warning:

warning: hitspec.yaml:3: unknown key "tiemout" (did you mean "timeout"?)

The run goes ahead with the keys it understands. hitspec validate --strict turns the warning into an error (exit code 2), which makes it a good CI check.

Precedence

Every command that sends requests — hitspec run (including --stress), hitspec contract verify, hitspec studio and hitspec serve --api-only — resolves a setting the same way. From highest to lowest priority:

a command-line flag (for example --timeout),
a HITSPEC_* environment variable,
hitspec.yaml,
the built-in default.

The flags, and the --env / HITSPEC_ENV pair, belong to hitspec run. The other commands read the same variables for everything except the environment name.

Setting	Flag	Environment variable	`hitspec.yaml` key	Built-in default
Environment	`--env`	`HITSPEC_ENV`	`defaultEnvironment`	`dev`
Request timeout	`--timeout`	`HITSPEC_TIMEOUT`	`timeout`	`30s`
Proxy	`--proxy`	`HITSPEC_PROXY`	`proxy`	none
Skip certificate validation	`--insecure`	`HITSPEC_INSECURE`	`validateSSL: false`	validate
CA bundle	`--cacert`	`HITSPEC_CACERT`	`cacert`	system roots
Client certificate	`--cert`	`HITSPEC_CERT`	`cert`	none
Client key	`--key`	`HITSPEC_KEY`	`key`	none
HTTP/1.1 only	`--http1.1`	`HITSPEC_HTTP1`	`http1: true`	HTTP/2
Cookie jar	`--cookies`	`HITSPEC_COOKIES`	`cookies: true`	off
Response size limit	`--max-response-bytes`	`HITSPEC_MAX_RESPONSE_BYTES`	`maxResponseBytes`	`104857600`
Forward headers on redirects	`--redirect-forward-headers`	`HITSPEC_REDIRECT_FORWARD_HEADERS`	`redirectForwardHeaders: true`	off
Parallel requests	`--parallel`	`HITSPEC_PARALLEL`	`parallel`	`false`
Parallel limit	`--concurrency`	`HITSPEC_CONCURRENCY`	`concurrency`	`5`
Stop on first failure	`--bail`	`HITSPEC_BAIL`	`bail`	`false`
Retries			`retries`	`0`
Retry delay			`retryDelay`	`1000` ms
Follow redirects			`followRedirects`	`true`
Redirect limit			`maxRedirects`	`10`
Default headers			`headers`	none

A @retry or @retryDelay annotation on a request overrides retries and retryDelay for that request, and a request’s own headers override headers. A number at or below zero in hitspec.yaml counts as “not set” (use followRedirects: false rather than maxRedirects: 0). The exception is maxResponseBytes, where 0 means the default and -1 means no limit. hitspec studio, hitspec serve --api-only and hitspec contract verify have no run flags. They read HITSPEC_TIMEOUT, HITSPEC_PROXY, HITSPEC_INSECURE, HITSPEC_PARALLEL, HITSPEC_CONCURRENCY and HITSPEC_BAIL, plus the TLS and HTTP variables from the table above (HITSPEC_CACERT, HITSPEC_CERT, HITSPEC_KEY, HITSPEC_HTTP1, HITSPEC_COOKIES, HITSPEC_MAX_RESPONSE_BYTES, HITSPEC_REDIRECT_FORWARD_HEADERS), then hitspec.yaml, then the defaults. Studio and serve choose the environment with their own --env (else defaultEnvironment, else dev) and ignore HITSPEC_ENV. contract verify finds hitspec.yaml from the current directory upward (or uses the path in HITSPEC_CONFIG) and has no environment of its own.

CLI Overrides

CLI flags always override config file values:

# Config says timeout: 30000, but this overrides to 60s
hitspec run tests/ --timeout 60s

# Config says parallel: true, but this turns it off
hitspec run tests/ --parallel=false

# Config says parallel: false, but this enables it
hitspec run tests/ --parallel --concurrency 10

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Configuration Reference

Creating a Config File

Full Configuration Reference

Options Reference

General

Network

Headers

Output

Execution

Reporters and outputDir

Environments

Stress Testing Profiles

Config File Search

Precedence

CLI Overrides