# Assertions
Source: https://hitspec.dev/concepts/assertions

Validate HTTP responses with 26 assertion operators covering equality, strings, types, arrays, schemas, and snapshots.

Assertions let you validate every aspect of an HTTP response -- status codes, headers, body content, response times, and more. hitspec provides 26 operators grouped into six categories.

## Assertion Block Syntax

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

```http theme={null}
GET {{baseUrl}}/users

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

Each line inside the block follows this pattern:

```
expect <subject> <operator> <value>
```

When the operator is `==`, you can omit it, as long as the value starts like a value (a number, a quoted string, `true`, `false`, `null`, `[` or `{`):

```http theme={null}
>>>
expect status 200          # shorthand for: expect status == 200
expect status == 200       # explicit form
<<<
```

A trailing `# comment` is allowed on any line (the `#` must follow whitespace and be followed by whitespace or the end of the line). Blank lines and lines starting with `#` or `//` inside the block are ignored. Any other line that does not start with `expect` is an error.

### Mistakes are errors, not guesses

hitspec refuses assertion lines it would otherwise have to guess at. `hitspec run` and `hitspec validate` report them with `file:line:column` and exit with code 2:

```
api.http:6:18: unknown operator "contians" (did you mean "contains"?)
```

* An unknown operator (`contians`, `=`, `===`, `equals`) is an error. A bare word after the subject is never read as "== word": write `expect body.name == Jane` or `expect body.name "Jane"`.
* An operator without a value (`expect body.name ==`) is an error. It no longer reads the next line as its value.
* Extra values are an error: `expect status 200 201` fails with a hint to write `expect status in [200, 201]`.
* `expect` misspelt (`expcet status 200`) is an error, so a line can never silently assert nothing.

### Expected Values

Every operator that takes a value reads it with one rule. The value is either:

1. a **JSON literal**: a string (`"Jane Doe"` or `'Jane Doe'`), a number, `true`, `false`, `null`, a list `[1, "a", b]`, or an object `{"a": 1}`; or
2. a **regular expression** `/pattern/flags` after `matches` (flags `i`, `m`, `s`, `U`; `g` is accepted and ignored); or
3. otherwise, **the rest of the line, trimmed, exactly as written**, as a string.

```http theme={null}
>>>
expect body.name == Jane Doe          # the string "Jane Doe", no quotes needed
expect body.path == ./files/x         # ./files/x, $HOME, ^start, @handle, #fff are all fine
expect body.msg == "line\nbreak"      # JSON escapes work inside quotes
expect body.address == {"city": "Oslo", "zip": "0150"}
expect status in [200, 201]
<<<
```

Quoted strings use JSON escapes; if the text is not valid JSON (a regex such as `"\d+"`), it is used as written. In a list, each element follows the same rule. `{{variable}}` references are filled in before comparing. Text after a closing quote is an error (`"Jane" Doe`), so quote the whole value or none of it.

For `contains`, `!contains`, `startsWith` and `endsWith` the value is always text: a quoted string is decoded, anything else is used exactly as written (`expect body startsWith {`, `expect body.price contains 1.50`).

## Assertion Subjects

| Subject | Description | Example |
| - | - | - |
| `status` | HTTP status code | `expect status 200` |
| `duration` | Response time in milliseconds | `expect duration < 1000` |
| `header <name>` | Response header value | `expect header Content-Type contains json` |
| `body` | Full response body (parsed when JSON, text otherwise) | `expect body contains "success"` |
| `body.<path>` | Path into a JSON body (gjson syntax: `.#` counts, `.#(...)` queries) | `expect body.user.name == "John"` |
| `body[n]` | Array index | `expect body[0].id exists` |
| `jsonpath $.<path>` | JSONPath expression (`$.a.b`, `$.a[0]`, `$.a[*].b`) | `expect jsonpath $.users[0].id exists` |

A body path needs a JSON response: `application/json`, `text/json` and any `+json` type such as `application/problem+json`, with or without `; charset=...`. On any other response, `body.x` fails with "response body is not JSON" instead of quietly matching; only the whole `body` can be read. See [Assertion Subjects](/reference/assertion-subjects).

***

## Equality and Comparison

Compare values using standard comparison operators.

| Operator | Syntax | Description |
| - | - | - |
| `==` | `expect status == 200` | Equals |
| `!=` | `expect body.error != null` | Not equals |
| `>` | `expect body.count > 0` | Greater than |
| `>=` | `expect body.count >= 1` | Greater than or equal |
| `<` | `expect duration < 1000` | Less than |
| `<=` | `expect duration <= 500` | Less than or equal |

```http theme={null}
### Verify response timing and pagination
GET {{baseUrl}}/users?page=1&limit=20

>>>
expect status == 200
expect duration < 500
expect body.total > 0
expect body.page == 1
expect body.perPage >= 20
<<<
```

<Tip>
  Use `expect status 200` as shorthand for `expect status == 200`. The `==` operator is implied when omitted.
</Tip>

`==` and `!=` compare objects and arrays **deeply**, as JSON: key order does not matter, `1` equals `1.0`, and `["a b"]` is not `["a", "b"]`:

```http theme={null}
>>>
expect body.address == {"city": "Oslo", "zip": "0150"}
expect body.ids == [1, 2, 3]
<<<
```

Scalars are compared loosely: `"42"` and `42` are equal. `null` only equals `null` (see [null versus absent](#null-versus-absent)).

***

## String Operators

Match, search, and compare string values.

| Operator | Syntax | Description |
| - | - | - |
| `contains` | `expect body contains "success"` | Contains substring |
| `!contains` | `expect body !contains "error"` | Does not contain substring |
| `startsWith` | `expect body.url startsWith "https"` | Starts with prefix |
| `endsWith` | `expect body.email endsWith ".com"` | Ends with suffix |
| `matches` | `expect body.id matches /^\d+$/` | Matches regular expression |

```http theme={null}
### Check user profile fields
GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.email endsWith "@example.com"
expect body.website startsWith "https"
expect body.bio !contains "<script>"
expect body.phone matches /^\+?[\d\s\-()]+$/
<<<
```

<Note>
  Regular expressions in `matches` are enclosed in forward slashes: `/pattern/` or `/pattern/i` (flags `i`, `m`, `s`, `U`). The pattern uses Go's regexp syntax. A value without slashes (`matches "^a"`) is used as the pattern as written.
</Note>

The string operators work on text. On the whole `body` of a JSON response they see the response's raw JSON text; on an object or array they see its JSON encoding (never Go's `map[...]` form); numbers appear without an exponent:

```http theme={null}
>>>
expect body contains "\"name\":\"Jane\""
expect body.address contains "\"city\":\"Oslo\""
expect body.tags endsWith "]"
<<<
```

***

## Existence and Type

Check whether values exist and validate their types.

| Operator | Syntax | Description |
| - | - | - |
| `exists` | `expect body.id exists` | Value is present and not null |
| `!exists` | `expect body.error !exists` | Value is absent or null |
| `type` | `expect body.items type array` | Check value type |

Supported types for the `type` operator: `null`, `boolean`, `number`, `string`, `array`, `object`. Anything else is an error (`type strng` suggests `string`).

### null versus absent

A field that is missing and a field that is `null` are different, and the operators treat them differently:

| Body | `exists` | `!exists` | `== null` | `!= null` | `type null` |
| - | - | - | - | - | - |
| `{"x": 5}` | pass | fail | fail | pass | fail |
| `{"x": null}` | fail | pass | pass | fail | pass |
| `{}` (x is absent) | fail | pass | fail | fail | fail |

`== null` needs a real JSON `null`, and `!= null` needs a present, non-null value, so a misspelt path cannot pass either. To accept "absent or null", use `!exists`. Every other operator fails on an absent path, except the negated ones (`!=`, `!contains`, `!includes`, `!in`), which hold because nothing is there to match.

```http theme={null}
### Validate response structure
GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id exists
expect body.name type string
expect body.age type number
expect body.active type boolean
expect body.tags type array
expect body.address type object
expect body.deletedAt !exists
<<<
```

***

## Length and Arrays

Validate array lengths and check array contents.

| Operator | Syntax | Description |
| - | - | - |
| `length` | `expect body.items length 10` | Length equals exact value (strings count characters, not bytes) |
| `length >` | `expect body.items length > 0` | Length greater than |
| `length >=` | `expect body.items length >= 1` | Length greater than or equal |
| `length <` | `expect body.items length < 100` | Length less than |
| `length <=` | `expect body.items length <= 50` | Length less than or equal |
| `includes` | `expect body.tags includes "admin"` | Array contains value |
| `!includes` | `expect body.tags !includes "test"` | Array does not contain value |
| `in` | `expect status in [200, 201, 204]` | Value is one of the listed values |
| `!in` | `expect status !in [400, 404, 500]` | Value is not one of the listed values |
| `each` | `expect body.items each type object` | Apply an assertion to every element |

```http theme={null}
### Validate paginated list
GET {{baseUrl}}/users?role=admin

>>>
expect status 200
expect body.users length > 0
expect body.users length <= 100
expect body.users each type object
<<<
```

### The `each` Operator

`each` applies an assertion to every element in an array. It is useful for validating the shape of list responses. After `each` write an operator and value, optionally preceded by a path inside the element (`body` or a leading `.` means the element itself):

```http theme={null}
>>>
expect body.users each type object
expect body.users each body.id exists
expect body.users each email matches /^.+@.+\..+$/
expect body.scores each > 0
expect body.users each {"operator": "type", "value": "object"}
<<<
```

A failure names the element: `item[2]: expected type string, got number`. An empty array passes (nothing to check); add `length > 0` to require elements.

### The `in` Operator

`in` checks whether a value is a member of a set. List values in square brackets:

```http theme={null}
>>>
expect status in [200, 201]
expect body.role in ["admin", "editor", "viewer"]
<<<
```

### The `includes` Operator

`includes` checks whether an array contains a specific value:

```http theme={null}
>>>
expect body.permissions includes "read"
expect body.permissions includes "write"
expect body.permissions !includes "superadmin"
<<<
```

***

## Schema Validation

Validate the entire response body against a JSON Schema file.

| Operator | Syntax | Description |
| - | - | - |
| `schema` | `expect body schema ./schema.json` | Validate against JSON Schema |

```http theme={null}
GET {{baseUrl}}/users/1

>>>
expect status 200
expect body schema ./schemas/user.json
<<<
```

Where `schemas/user.json` contains a standard JSON Schema:

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "user", "guest"] }
  }
}
```

<Note>
  Schema file paths are resolved relative to the `.http` file that references them.
</Note>

***

## Snapshot Testing

Compare the response body against a previously saved baseline. A snapshot is never created by a plain run: the first run fails with "snapshot does not exist (run with --update-snapshots to create)". Run once with `--update-snapshots` to save the baseline, then later runs compare against it.

| Operator | Syntax | Description |
| - | - | - |
| `snapshot` | `expect body snapshot "name"` | Compare against saved snapshot |

```http theme={null}
GET {{baseUrl}}/config

>>>
expect status 200
expect body snapshot "app-config"
<<<
```

Snapshots are stored in a `__snapshots__` directory next to your test file. Create them the first time, and update them when the response intentionally changes:

```bash theme={null}
hitspec run tests/ --update-snapshots
```

<Tip>
  Snapshot testing works well for responses that should remain stable over time, such as configuration endpoints or reference data.
</Tip>

***

## Combining Assertions

A single assertion block can mix operators from any category:

```http theme={null}
### Full response validation
POST {{baseUrl}}/orders
Content-Type: application/json

{
  "productId": "prod-123",
  "quantity": 2
}

>>>
expect status 201
expect duration < 1000
expect header Content-Type contains json
expect body.id exists
expect body.id type string
expect body.status == "pending"
expect body.items length 2
expect body.items each type object
expect body.total > 0
expect body schema ./schemas/order.json
<<<
```

## Header Assertions

Assert on response headers using the `header <name>` subject:

```http theme={null}
>>>
expect header Content-Type contains "application/json"
expect header X-Request-Id exists
expect header X-RateLimit-Remaining > 0
expect header Cache-Control contains "no-cache"
<<<
```

## Reading a failure

When a request fails, the console output alone says why: the failed assertions with their expected and actual values, then the request as it was sent, the response status line with its duration, and an excerpt of the response body.

```text theme={null}
  ✗ getUser (12ms)
    → status == (line 5)
      Expected: 200
      Actual:   404
      expected 200, got 404
    → body.id == (line 6)
      Expected: 1
      Actual:   42
      expected 1, got 42
    Request:  GET https://api.example.com/users/42?api_key=[REDACTED]
    Response: 404 Not Found (9ms)
    Body:
      {
        "error": "user not found",
        "id": 42
      }
```

JSON bodies are pretty-printed and the excerpt is capped at about 2 KB or 30 lines; a note says how much was cut, and `-vvv` prints the whole body. Credentials are redacted: header values such as `Authorization` and `Cookie`, the password in `user:password@host`, and query parameters named like `api_key` or `access_token`. If a request errored before any response arrived (connection refused, timeout), you get the request line and the error. See [output formats](/reference/output-formats) for `-v`, `-vv` and `-vvv`.

## Testing Error Responses

Assertions are equally useful for verifying error behavior:

<CodeGroup>
  ```http 401 Unauthorized theme={null}
  ### Missing authentication
  GET {{baseUrl}}/admin/users

  >>>
  expect status 401
  expect body.error exists
  expect body.message contains "unauthorized"
  <<<
  ```

  ```http 404 Not Found theme={null}
  ### Non-existent resource
  GET {{baseUrl}}/users/99999999

  >>>
  expect status 404
  expect body.error exists
  <<<
  ```

  ```http 400 Validation Error theme={null}
  ### Invalid input
  POST {{baseUrl}}/users
  Content-Type: application/json

  {"email": "not-an-email"}

  >>>
  expect status 400
  expect body.errors type array
  expect body.errors length > 0
  <<<
  ```
</CodeGroup>


# Captures
Source: https://hitspec.dev/concepts/captures

Extract values from HTTP responses and use them in subsequent requests.

Captures extract values from HTTP responses -- body fields, headers, status codes, and timing -- and store them as variables for use in later requests. This is the foundation for building multi-step test flows like authentication, CRUD operations, and workflow testing.

## Capture Block Syntax

Wrap capture definitions in `>>>capture` and `<<<` markers:

```http theme={null}
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
<<<
```

Each line follows this pattern:

```
<variableName> from <source>
```

Capture lines are read as written, so a path may contain quotes and spaces (`items.#(name=="Jane Doe").id`). A trailing `# comment` is allowed. A line that is not `<name> from <source>` is a parse error, and a capture block must be closed with `<<<`.

## Capture Sources

hitspec can capture values from these parts of the response:

| Source | Syntax | Description |
| - | - | - |
| Body (JSON path) | `token from body.access_token` | Extract a value from the JSON response body |
| Whole body | `doc from body` | The whole body: parsed JSON, or the text of a non-JSON response |
| JSONPath | `token from jsonpath $.data.token` | A JSONPath expression (`$.a.b`, `$.a[0]`, `$.a[*].b`) |
| Header | `contentType from header Content-Type` | Extract a response header value |
| Status | `code from status` | Capture the HTTP status code |
| Duration | `time from duration` | Capture the response time in milliseconds |

### Body Captures

Use dot notation and array indexing to reach into the JSON response:

```http theme={null}
>>>capture
id from body.id
name from body.user.name
firstTag from body.tags[0]
nestedValue from body.data.items[0].metadata.key
<<<
```

Body paths use [GJSON](https://github.com/tidwall/gjson) syntax, so the full GJSON
path language is available -- including `.#` for array length and queries:

```http theme={null}
>>>capture
itemCount from body.items.#
firstAdminName from body.users.#(role=="admin").name
<<<
```

<Note>
  Assertions and captures share one path normalizer, so the same paths work in
  `expect body.<path>` assertions: you can assert on `body.items.#` (array length)
  directly too. Bracket notation works in both (`body.items[0].name`,
  `body[2].id`, `body.items[*].id`).
</Note>

Body paths need a JSON response (`application/json`, or any `+json` type such as
`application/problem+json`, with or without `; charset=...`). On a non-JSON
response only the whole `body` can be captured.

### Captures that find nothing

A capture whose path matches nothing (a typo, an error response with a different
shape, a missing header) is left out and reported on stderr, once per run:

```
warning: capture "token" (line 9) captured nothing: the path "access_tokn" matches nothing in the response body
```

Without the warning the problem only appeared later as an unresolved
`{{variable}}` in another request. A capture whose path contains spaces outside
`(...)` (a note glued to the path instead of after `#`) is flagged by
`hitspec validate` because it can never match.

### Header Captures

```http theme={null}
>>>capture
requestId from header X-Request-Id
rateLimit from header X-RateLimit-Remaining
location from header Location
<<<
```

### Status and Duration Captures

```http theme={null}
>>>capture
statusCode from status
responseTime from duration
<<<
```

## Using Captured Values

Captured values are referenced using the `{{requestName.captureName}}` pattern. The `requestName` is the value of the `@name` directive on the capturing request.

```http theme={null}
### Step 1: Login
# @name login

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

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

>>>
expect status 200
<<<

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

### Step 2: Access protected resource
# @depends login

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

>>>
expect status 200
expect body.id == "{{login.userId}}"
<<<
```

### How values are inserted

A captured value is inserted into the next request exactly as the response had it:

* Strings are inserted as-is.
* Numbers keep their exact JSON digits, so `1000000` stays `1000000` and `123456789012` is not rounded or written as `1e+06`.
* Booleans are `true` or `false`, and `null` is `null`.
* Objects and arrays are inserted as compact JSON, for example `{"id":1,"tags":["x","y"]}`.

Captured values are data, not templates. If a response contains `{{HOME}}` or `{{$env(SECRET)}}`, that text is sent literally and never expanded.

<Warning>
  Three things are required for captures to work across requests:

  1. The source request must have a `# @name` directive.
  2. The source request must have a `>>>capture` block.
  3. The consuming request must declare `# @depends` on the source request to guarantee execution order.
</Warning>

## Real-World Examples

### Authentication Flow

```http theme={null}
@baseUrl = https://api.example.com

### Login
# @name login
# @tags auth

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

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

>>>
expect status 200
expect body.token exists
expect body.refreshToken exists
<<<

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

### Access protected endpoint
# @name getProfile
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/me

>>>
expect status 200
expect body.id == "{{login.userId}}"
<<<

### Refresh the token
# @name refresh
# @depends login

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

{
  "refreshToken": "{{login.refreshToken}}"
}

>>>
expect status 200
expect body.token exists
<<<

>>>capture
newToken from body.token
<<<
```

### CRUD Workflow

```http theme={null}
@baseUrl = https://api.example.com

### Create a post
# @name createPost

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

{
  "title": "Test Post {{$uuid()}}",
  "body": "Created at {{$now()}}",
  "status": "draft"
}

>>>
expect status 201
expect body.id exists
<<<

>>>capture
postId from body.id
<<<

### Read the post
# @name getPost
# @depends createPost

GET {{baseUrl}}/posts/{{createPost.postId}}
Authorization: Bearer {{login.token}}

>>>
expect status 200
expect body.id == "{{createPost.postId}}"
expect body.status == "draft"
<<<

### Update the post
# @name updatePost
# @depends createPost

PUT {{baseUrl}}/posts/{{createPost.postId}}
Content-Type: application/json
Authorization: Bearer {{login.token}}

{
  "status": "published"
}

>>>
expect status 200
expect body.status == "published"
<<<

### Delete the post
# @name deletePost
# @depends updatePost

DELETE {{baseUrl}}/posts/{{createPost.postId}}
Authorization: Bearer {{login.token}}

>>>
expect status 204
<<<
```

### Capturing Headers for Pagination

```http theme={null}
### Get first page
# @name firstPage

GET {{baseUrl}}/items?page=1&limit=10
Authorization: Bearer {{token}}

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

>>>capture
totalCount from header X-Total-Count
nextPage from header X-Next-Page
<<<

### Get second page
# @depends firstPage

GET {{baseUrl}}/items?page={{firstPage.nextPage}}&limit=10
Authorization: Bearer {{token}}

>>>
expect status 200
<<<
```

## Captures and Assertions Together

A request can have both assertion and capture blocks. Assertions are evaluated first; if they fail, captures are still performed (allowing dependent requests to attempt execution):

```http theme={null}
POST {{baseUrl}}/auth/login
Content-Type: application/json

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

>>>
expect status 200
expect body.token exists
expect body.expiresIn > 0
<<<

>>>capture
token from body.token
expiresIn from body.expiresIn
<<<
```

<Tip>
  Place assertion blocks before capture blocks for readability. Both blocks belong to the same request -- their order does not affect behavior.
</Tip>


# Dependencies
Source: https://hitspec.dev/concepts/dependencies

Control execution order with @depends, topological sorting, and request chaining.

By default, hitspec executes requests in the order they appear in the file. The `@depends` directive lets you declare explicit dependencies between requests, ensuring that prerequisite requests run first regardless of file order.

## Basic Usage

Add `# @depends <requestName>` to any request that relies on another:

```http theme={null}
### Login
# @name login

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

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

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

### Get profile
# @name getProfile
# @depends login

GET {{baseUrl}}/me
Authorization: Bearer {{login.token}}

>>>
expect status 200
<<<
```

The `getProfile` request will always execute after `login`, even if you run tests in parallel mode or filter to a specific request.

## Multiple Dependencies

A request can depend on multiple other requests. Separate names with commas:

```http theme={null}
### Setup database
# @name setupDb

POST {{baseUrl}}/test/seed
Content-Type: application/json

{"fixture": "users"}

>>>
expect status 200
<<<

### Login
# @name login

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

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

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

### Run protected operation
# @name protectedOp
# @depends setupDb, login

POST {{baseUrl}}/admin/report
Authorization: Bearer {{login.token}}

>>>
expect status 200
<<<
```

All listed dependencies must complete before the dependent request runs. The dependencies themselves can run in any order (or in parallel, when `--parallel` is enabled).

## How It Works

### Topological Sort

hitspec builds a directed acyclic graph (DAG) from the `@depends` declarations and performs a topological sort to determine execution order. This means:

* Dependencies always run before the requests that need them
* Independent requests can run in any order
* With `--parallel`, independent requests run concurrently

Given this dependency graph:

```
login ──────────┐
                ├──> getProfile
setupDb ────────┘
                ├──> createPost ──> verifyPost
login ──────────┘
```

hitspec determines that `login` and `setupDb` can run in parallel, `getProfile` and `createPost` must wait for their dependencies, and `verifyPost` runs last.

### Cycle Detection

hitspec detects circular dependencies at parse time and reports an error:

```http theme={null}
### Request A
# @name a
# @depends b

GET {{baseUrl}}/a

### Request B
# @name b
# @depends a

GET {{baseUrl}}/b
```

This produces an error:

```
Error: circular dependency detected: a -> b -> a
```

<Warning>
  Circular dependencies are always a configuration error. Restructure your tests so the dependency chain flows in one direction.
</Warning>

## Cross-File Dependencies

Dependencies work across files within the same test run. If `login` is defined in `auth.http` and `createPost` in `posts.http`, you can still declare:

```http theme={null}
# In posts.http
### Create a post
# @name createPost
# @depends login

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

{"title": "Hello"}
```

As long as both files are included in the test run:

```bash theme={null}
hitspec run auth.http posts.http
# or
hitspec run tests/    # if both files are in tests/
```

## Implicit Dependencies via Captures

Using a captured variable implicitly requires the capturing request to run first, but hitspec does not infer this automatically. You must always declare `@depends` explicitly:

```http theme={null}
### Login
# @name login

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

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

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

### Get data (WRONG -- missing @depends)
GET {{baseUrl}}/data
Authorization: Bearer {{login.token}}

### Get data (CORRECT)
# @depends login
GET {{baseUrl}}/data
Authorization: Bearer {{login.token}}
```

<Note>
  Without `@depends`, hitspec may execute requests in any order (especially with `--parallel`), causing captured variable references to resolve to empty strings.
</Note>

## Dependency Chains

Dependencies are transitive. If A depends on B and B depends on C, then A implicitly waits for both B and C:

```http theme={null}
### Step 1: Create org
# @name createOrg

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

{"name": "Test Org"}

>>>capture
orgId from body.id
<<<

### Step 2: Create team (depends on org)
# @name createTeam
# @depends createOrg

POST {{baseUrl}}/orgs/{{createOrg.orgId}}/teams
Content-Type: application/json

{"name": "Engineering"}

>>>capture
teamId from body.id
<<<

### Step 3: Add member (depends on team, which depends on org)
# @name addMember
# @depends createTeam

POST {{baseUrl}}/teams/{{createTeam.teamId}}/members
Content-Type: application/json

{"userId": "user-123"}

>>>
expect status 201
<<<
```

You do not need to write `# @depends createOrg, createTeam` on `addMember` -- depending on `createTeam` is sufficient because `createTeam` already depends on `createOrg`.

## Parallel Execution with Dependencies

When you run tests with `--parallel`, hitspec respects all `@depends` constraints while maximizing concurrency for independent requests:

```bash theme={null}
hitspec run tests/ --parallel --concurrency 5
```

In this mode:

* Requests with no dependencies start immediately
* Requests with satisfied dependencies start as soon as their prerequisites complete
* The `--concurrency` flag limits how many requests run simultaneously

## Filtered Execution

When you filter tests by name or tag, hitspec automatically includes any dependency that the filtered request needs:

```bash theme={null}
# Runs "login" automatically because getProfile depends on it
hitspec run tests/ --name getProfile
```

```bash theme={null}
# Runs any dependencies of smoke-tagged requests
hitspec run tests/ --tags smoke
```

## Common Patterns

### Setup and Teardown

```http theme={null}
### Seed test data
# @name setup
# @tags setup

POST {{baseUrl}}/test/seed

>>>
expect status 200
<<<

>>>capture
testUserId from body.userId
<<<

### Run test
# @name mainTest
# @depends setup

GET {{baseUrl}}/users/{{setup.testUserId}}

>>>
expect status 200
<<<

### Clean up
# @name teardown
# @depends mainTest

DELETE {{baseUrl}}/test/cleanup

>>>
expect status 200
<<<
```

### Fan-Out Pattern

Multiple requests depend on a single setup step:

```http theme={null}
### Login
# @name login

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

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

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

### Test users endpoint
# @depends login

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

>>>
expect status 200
<<<

### Test posts endpoint
# @depends login

GET {{baseUrl}}/posts
Authorization: Bearer {{login.token}}

>>>
expect status 200
<<<

### Test comments endpoint
# @depends login

GET {{baseUrl}}/comments
Authorization: Bearer {{login.token}}

>>>
expect status 200
<<<
```

With `--parallel`, the three test requests run concurrently after `login` completes.


# Environments
Source: https://hitspec.dev/concepts/environments

Configure variables for dev, staging, and production with hitspec.yaml, .env files, and system variables.

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:

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

<Note>
  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.
</Note>

## Inline Variables

Define variables directly in your test file:

```http theme={null}
@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:

```yaml theme={null}
# 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`):

```bash theme={null}
# 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:

```http theme={null}
GET {{baseUrl}}/users
Authorization: Bearer {{token}}

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

hitspec searches for config files in this order:

1. `hitspec.yaml`
2. `hitspec.yml`

You can also specify a config file explicitly:

```bash theme={null}
hitspec run tests/ --config ./config/hitspec.yaml
```

<Note>
  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.
</Note>

## .env Files

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

```bash theme={null}
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:

```http theme={null}
# 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.

<Warning>
  The dotted form `{{$env.VAR}}` is **not** supported. Use `{{$VAR}}` or
  `{{$env(VAR)}}`.
</Warning>

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

```yaml theme={null}
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 |

```bash theme={null}
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):

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

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

<Note>
  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.
</Note>

## 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`:

```gitignore theme={null}
.env
.env.*
```

Commit a template instead:

```
# .env.example
API_TOKEN=YOUR_TOKEN_HERE
DB_PASSWORD=YOUR_DB_PASSWORD_HERE
```

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

### Use System Variables in CI/CD

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    env:
      API_BASE_URL: https://staging.api.example.com
      API_TOKEN: ${{ secrets.API_TOKEN }}

    steps:
      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: ci
          env-file: .env.ci
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Shared Base Configuration

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

```yaml theme={null}
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:

```yaml theme={null}
environments:
  dev:
    baseUrl: http://localhost:3000
    timeout: "30000"
    retries: "3"
  prod:
    baseUrl: https://api.example.com
    timeout: "5000"
    retries: "0"
```

```http theme={null}
# @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

<Accordion title="Variable not found">
  ```
  Error: variable "baseUrl" not found
  ```

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

<Accordion title="Environment not found">
  ```
  Error: environment "staging" not found
  ```

  1. Add a `staging:` key under `environments:` in `hitspec.yaml`.
  2. Check for typos in the environment name.
</Accordion>

<Accordion title="System variable not set">
  ```
  Error: environment variable "API_TOKEN" not set
  ```

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


# The .http file format for API tests
Source: https://hitspec.dev/concepts/file-format

Anatomy of a hitspec .http file: requests, headers, bodies, variables, assertions, captures, dependencies, and directives — plain text you can diff and commit.

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:

```http theme={null}
GET https://api.example.com/health

>>>
expect status 200
<<<
```

## File Structure

A typical `.http` file follows this structure:

```http theme={null}
@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.

```http theme={null}
### First request
GET https://api.example.com/posts

>>>
expect status 200
<<<

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

>>>
expect status 200
<<<
```

<Note>
  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.
</Note>

## Variables

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

```http theme={null}
@baseUrl = https://api.example.com
@apiVersion = v1
@timeout = 5000
```

Reference them anywhere in the file with double curly braces:

```http theme={null}
GET {{baseUrl}}/{{apiVersion}}/users
```

See [Variables](/concepts/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:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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.

```http theme={null}
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.

<Warning>
  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.
</Warning>

## Request Body

### JSON

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
POST {{baseUrl}}/graphql
Content-Type: application/json

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

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

### XML

```http theme={null}
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`:

```http theme={null}
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:

```http theme={null}
POST {{baseUrl}}/import
Content-Type: application/json

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

## Query Parameters

Inline with the URL:

```http theme={null}
GET {{baseUrl}}/search?query=test&limit=10
```

Or use the explicit `?` prefix syntax for readability:

```http theme={null}
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:

```http theme={null}
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](/concepts/assertions) for all 26 operators.

## Capture Blocks

Capture response values for use in later requests:

```http theme={null}
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](/concepts/captures) for the full capture system.

## Metadata Directives

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

```http theme={null}
### 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).

```http theme={null}
### 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:

```http theme={null}
### Run only in CI
# @if {{CI}}

POST {{baseUrl}}/deploy
```

```http theme={null}
### 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):

```http theme={null}
### Only against production
# @if {{env}} == "prod"

POST {{baseUrl}}/deploy
```

```http theme={null}
### 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:

```http theme={null}
### 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:

```http theme={null}
# 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:

<CodeGroup>
  ```http Bearer Token theme={null}
  # @auth bearer {{token}}

  GET {{baseUrl}}/me
  ```

  ```http Basic Auth theme={null}
  # @auth basic {{username}}, {{password}}

  GET {{baseUrl}}/admin
  ```

  ```http API Key (Header) theme={null}
  # @auth apiKey X-API-Key, {{apiKey}}

  GET {{baseUrl}}/data
  ```

  ```http API Key (Query) theme={null}
  # @auth apiKeyQuery api_key, {{apiKey}}

  GET {{baseUrl}}/data
  ```

  ```http Digest Auth theme={null}
  # @auth digest {{username}}, {{password}}

  GET {{baseUrl}}/secure
  ```

  ```http AWS Signature v4 theme={null}
  # @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}

  GET {{baseUrl}}/s3/object
  ```

  ```http AWS Signature v4 (temporary credentials) theme={null}
  # @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}, {{sessionToken}}

  GET {{baseUrl}}/s3/object
  ```

  ```http OAuth2 Client Credentials theme={null}
  # @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2

  GET {{baseUrl}}/protected
  ```

  ```http OAuth2 Password theme={null}
  # @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2

  GET {{baseUrl}}/protected
  ```
</CodeGroup>

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


# Variable Interpolation
Source: https://hitspec.dev/concepts/variable-interpolation

Deep-dive into hitspec's {{var}} syntax, $env() references, capture chains, and resolution order.

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:

```http theme={null}
@baseUrl = https://api.example.com
@token = my-secret-token
@version = v2
```

### Environment Variables

From `hitspec.yaml` environments section:

```yaml theme={null}
environments:
  dev:
    baseUrl: http://localhost:3000
    token: dev-token
```

### System Environment Variables

Using the `$env()` function:

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

### Built-in Functions

Dynamic values generated at runtime:

```http theme={null}
{
  "id": "{{$uuid()}}",
  "timestamp": {{$timestamp()}},
  "email": "{{$randomEmail()}}"
}
```

### Captured Values

Values extracted from prior responses:

```http theme={null}
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):

1. **Config environments** -- `hitspec.yaml` `environments` section for the active `--env`
2. **Inline variables** -- `@variable = value` in the file
3. **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:

```http theme={null}
### 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:

```http theme={null}
@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.

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


# Variables
Source: https://hitspec.dev/concepts/variables

Define variables, use built-in functions, reference environment values, and interpolate captured data.

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:

```http theme={null}
@baseUrl = https://api.example.com
@token = my-api-token
@userId = 42
```

## Interpolation

Reference variables anywhere in your requests using double curly braces:

```http theme={null}
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

```http theme={null}
@baseUrl = https://api.example.com
@apiPath = {{baseUrl}}/v1

### Create user
# @timeout 5000
# @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

| Function | Description | Example Output |
| - | - | - |
| `{{$uuid()}}` | Generate a UUID v4 | `550e8400-e29b-41d4-a716-446655440000` |
| `{{$random(min, max)}}` | Random integer in range | `42` |
| `{{$randomString(len)}}` | Random alphanumeric string | `aB3kL9mN` |
| `{{$randomAlphanumeric(len)}}` | Random alphanumeric string | `K8mNp2qRsT` |
| `{{$randomEmail()}}` | Random email address | `user_abc123@example.com` |

### Date and Time

| Function | Description | Example Output |
| - | - | - |
| `{{$timestamp()}}` | Unix timestamp in seconds | `1705612800` |
| `{{$timestampMs()}}` | Unix timestamp in milliseconds | `1705612800000` |
| `{{$now()}}` | Current datetime in RFC 3339 | `2024-01-18T12:00:00Z` |
| `{{$date(format)}}` | Custom date format (Go layout, default: `2006-01-02`) | `2024-01-18` |

<Note>
  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`.
</Note>

### Encoding and Hashing

| Function | Description | Example Output |
| - | - | - |
| `{{$base64(value)}}` | Base64 encode | `aGVsbG8=` |
| `{{$base64Decode(value)}}` | Base64 decode | `hello` |
| `{{$md5(value)}}` | MD5 hash | `5d41402abc4b2a76...` |
| `{{$sha256(value)}}` | SHA256 hash | `2cf24dba5fb0a30e...` |
| `{{$urlEncode(value)}}` | URL-encode a string | `hello%20world` |
| `{{$urlDecode(value)}}` | URL-decode a string | `hello world` |

### Utilities

| Function | Description | Example Output |
| - | - | - |
| `{{$json(value)}}` | JSON passthrough | `{"key": "value"}` |
| `{{$env(VAR, default)}}` | System environment variable with optional default | *(value of \$VAR)* |

### Practical Examples

<Tabs>
  <Tab title="Unique test data">
    ```http theme={null}
    POST {{baseUrl}}/users
    Content-Type: application/json

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

  <Tab title="Authentication headers">
    ```http theme={null}
    @username = admin
    @password = secret

    GET {{baseUrl}}/api/data
    Authorization: Basic {{$base64({{username}}:{{password}})}}
    X-Request-Id: {{$uuid()}}
    X-Timestamp: {{$timestamp()}}
    ```
  </Tab>

  <Tab title="URL construction">
    ```http theme={null}
    @searchTerm = hello world
    @startDate = {{$date(2006-01-02)}}

    GET {{baseUrl}}/search
    ? q = {{$urlEncode({{searchTerm}})}}
    ? since = {{startDate}}
    ? limit = 20
    ```
  </Tab>
</Tabs>

## System Environment Variables

Access system environment variables with `$env()`:

```http theme={null}
@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 `hitspec.yaml` environments using
shell-style `${VAR}` syntax:

```yaml theme={null}
environments:
  prod:
    baseUrl: https://api.example.com
    token: "${API_TOKEN}"
    dbPassword: "${DB_PASSWORD}"
```

## Capture References

When a request captures values from its response, subsequent requests can reference them using the `{{requestName.captureName}}` pattern:

```http theme={null}
### 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}}"
<<<
```

<Warning>
  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.
</Warning>

See [Captures](/concepts/captures) and [Dependencies](/concepts/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. **hitspec.yaml environments** -- values from the `environments` section for the active `--env`
2. **Inline variables** -- `@variable = value` in the `.http` file
3. **Captured values** -- `{{requestName.captureName}}` from prior responses

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

When an inline variable references its own name, the reference resolves against the layers below it (the `hitspec.yaml` environment, then `.env` files, then the OS environment) instead of being treated as a loop. This lets a file default to whatever the environment provides:

```http theme={null}
@baseUrl = {{baseUrl}}
```

If no lower layer defines the name, the reference stays literal. A loop between two different variables (`@a = {{b}}`, `@b = {{a}}`) is still an error.

<Tip>
  Inline variables (`@var = value`) override `hitspec.yaml` environment values. This is useful for local overrides during development, but be careful not to accidentally shadow environment-specific configuration.
</Tip>

## 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 the `environments` section of `hitspec.yaml`) are global and available to all files in the test run.


# hitspec Studio desktop — a native GUI for .http files
Source: https://hitspec.dev/desktop

hitspec Studio is the Electron desktop client for hitspec: file tree, source editor, tabbed response viewer, history, stress, mock, record and imports over your existing .http files.

`hitspec Studio` is the desktop companion to `hitspec studio`: the same
keyboard-friendly workflow in a native window instead of a terminal. It edits
and runs the exact same plain-text `.http` files, so what you click in the app
is what CI executes.

<Note>
  The desktop app is developed in this repository under `apps/desktop`. There
  are **no published installers yet**: signed and notarized builds need
  Apple and Windows signing credentials that are not set up, so nothing is
  attached to the GitHub releases. Today you run it from source (below) or
  package an unsigned build yourself ([Package it](#package-it)). It also needs
  hitspec v2.20.0 or newer: the app warns when the CLI it launches is older.
</Note>

## Run it from source

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    task desktop:install        # npm install in apps/desktop (+ Electron binary)
    ```
  </Step>

  <Step title="Build the CLI it drives">
    ```bash theme={null}
    task build                  # produces bin/hitspec
    ```
  </Step>

  <Step title="Launch">
    ```bash theme={null}
    task desktop:dev            # or: task desktop:dev -- ./tests
    ```
  </Step>
</Steps>

Open a workspace with `cmd/ctrl+O`, by dropping a folder on the app icon, or by
passing a directory on the command line. Recent workspaces are remembered on
the welcome screen.

## What you get

* **Workspace browser** -- file tree with request counts, fuzzy filter, and a
  per-file request list with pass/fail dots from the last run.
* **Request inspector** -- method, URL, headers, query params, body,
  assertions, captures and metadata (`@timeout`, `@depends`, `@auth`, ...).
* **Runner** -- run one request (`cmd/ctrl+enter`) or the whole file
  (`cmd/ctrl+shift+enter`) with live per-request progress, then a tabbed
  response viewer: pretty-printed JSON body, headers, assertion results,
  timing, captures and SSE events.
* **Source editor** -- line numbers plus `.http` syntax highlighting, save
  (`cmd/ctrl+s`), revert, and automatic reload when the file changes on disk.
* **Environments** -- switch from the toolbar or edit variables in a grid that
  writes straight back to `hitspec.yaml`.
* **History** -- the persistent SQLite run history with per-run drill-down.
* **Stress, mock, record** -- the same engines as the CLI, with live metrics
  charts, route tables and recording export to `.http`.
* **Import** -- curl, OpenAPI and Insomnia sources previewed as `.http` before
  you save them into the workspace.
* **Command palette** (`cmd/ctrl+k`) and five themes shared with the terminal UI.

## How it works

The app spawns `hitspec serve --api-only` as a child process on a random
loopback port with a freshly generated bearer token (handed over through the
child's environment, never its command line), then drives the REST and
WebSocket API from `packages/serve`. The renderer never talks to the network
and never sees the token: every call crosses a small IPC bridge in the main
process, and file writes outside the workspace are only allowed for paths you
picked in a native save dialog.

```
Electron main ── spawns ─▶ hitspec serve --api-only (127.0.0.1:<random>)
     ▲                            │ REST + WebSocket
     └── IPC bridge ◀── renderer ─┘
```

Because it reuses the API server, every capability added to `packages/serve`
becomes available to the desktop app without new native code.

### Safety rails

* The renderer is treated as untrusted: only the app's own page can call the
  main process, and REST calls are limited to the endpoints the UI uses.
* Shell execution (`--allow-shell`) can only be switched on through a native
  confirmation dialog for the current workspace, and the approval lasts until
  you quit the app.
* Unsaved editor changes are guarded when you switch files, close the window,
  quit or open another workspace, and saving asks before overwriting a file that
  changed on disk since you opened it.
* The API server is started with `--parent-pid`, so it shuts itself down within
  a second when the app dies without cleaning up (a crash or `kill -9`). A
  hitspec CLI older than that flag is started without it; the next launch then
  stops the leftover server instead, after checking its command line and port
  so an unrelated process that reused the pid is never touched.
* Launching the app again with a folder (`hitspec-studio ./other-project`, or
  "Open With" in Finder) opens that folder in the running window, asking first
  if there are unsaved edits.
* "Read-only" in Settings protects the workspace and `hitspec.yaml`: saving,
  creating or deleting files and editing settings are refused, while running
  requests, stress, mock and history reads keep working.

## Package it

```bash theme={null}
task desktop:dist        # electron-builder: dmg/zip, nsis/zip, AppImage/deb
```

`task desktop:dist` packages for the operating system you run it on (mac:
arm64 and x64, Windows: x64, Linux: x64). It first cross-compiles one CLI per
architecture into `apps/desktop/build/bin/<os>-<arch>/` and bundles the one that
matches each target, so the Intel build never carries the Apple-silicon binary.
Installers land in `apps/desktop/release/`.

Local builds are unsigned unless your machine has a signing certificate
(`CSC_LINK`, or a "Developer ID Application" certificate in your keychain);
set `CSC_IDENTITY_AUTO_DISCOVERY=false` to force an unsigned build. Clear the
quarantine flag after installing an unsigned build on macOS:

```bash theme={null}
xattr -dr com.apple.quarantine "/Applications/hitspec Studio.app"
```

CI (`.github/workflows/desktop.yml`) packages all three platforms on every
change to the app and verifies the bundled CLI and the hardened Electron fuses.
Signed installers and release publishing run only when the signing credentials
exist in the repository secrets; until then they are skipped.

## Testing

```bash theme={null}
task desktop:test        # unit tests + headless API integration + Playwright e2e
```

The e2e suite launches the real app with Playwright against a throwaway
workspace and an in-process HTTP target, so the whole stack -- window, IPC,
Go server, runner -- is exercised on every run.


# Editor Setup
Source: https://hitspec.dev/editor-setup

Configure syntax highlighting, snippets, and shell completions for hitspec.

## VSCode Extension

The hitspec VSCode extension (v0.2.0, not yet on the Marketplace) provides syntax highlighting, snippets, and language configuration for `.http` and `.hitspec` files.

### Features

* Full syntax highlighting via TextMate grammar
* 45 code snippets covering requests, assertions, captures, annotations, blocks, and built-in functions
* Comment toggling (`#`)
* Bracket matching and auto-closing for `{}`, `[]`, `()`, `""`, `''`, `{{}}`, and `>>>` / `<<<`
* Code folding for request separators (`###`) and assertion blocks

### Syntax Highlighting

The TextMate grammar highlights these elements:

* **HTTP methods** -- GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, CONNECT
* **Request separators** -- `###` lines
* **Annotations** -- `@name`, `@tags`, `@auth`, `@depends`, `@if`, `@unless`, `@retryOn`, `@stress.*`, `@contract.*`, and others
* **Headers** -- key-value pairs like `Content-Type: application/json`
* **Assertion blocks** (`>>>` / `<<<`) -- `expect` keyword, comparison operators (`==`, `!=`, `>`, `<`, `>=`, `<=`), matchers (`contains`, `matches`, `exists`, `type`, `schema`, `snapshot`, etc.), and subjects (`status`, `body`, `header`, `duration`)
* **Typed blocks** -- `>>>capture`, `>>>graphql`, `>>>db`, `>>>shell`, `>>>mock`, `>>>multipart`, `>>>variables`
* **Variable interpolation** -- `{{variable}}`
* **Built-in functions** -- `$uuid()`, `$timestamp()`, `$env()`, `$random()`, and others
* **File includes** -- `< ./path/to/file`
* **Query parameters** -- `? key = value` and `& key = value`
* **Strings, numbers, booleans, null**

### Installation

<Steps>
  <Step title="Build the extension">
    ```bash theme={null}
    cd apps/vscode
    npm install
    npm run package
    ```

    This generates a `.vsix` file in the `apps/vscode` directory. (The `VS Code extension` GitHub workflow builds the same file; publishing to the Marketplace and Open VSX needs the maintainer's tokens and is not set up yet.)
  </Step>

  <Step title="Install in VSCode">
    1. Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux)
    2. Run **Extensions: Install from VSIX...**
    3. Select the generated `.vsix` file
  </Step>
</Steps>

<Note>
  The extension is declarative-only -- no IntelliSense or autocomplete beyond snippets. The [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension is an alternative for basic `.http` support, but it does not highlight assertion blocks, typed blocks, or annotations.
</Note>

## Neovim

The hitspec Neovim plugin provides syntax highlighting, filetype detection, buffer settings, and optional LuaSnip snippets for `.http` and `.hitspec` files.

### Features

* Syntax highlighting via Vim syntax file (not TreeSitter)
* Filetype detection for `.http` and `.hitspec`
* Buffer settings: `commentstring` (`# %s`), 2-space indentation
* 55 LuaSnip snippets (optional) covering HTTP methods, assertion/capture blocks, annotations, built-in functions, and a complete request template

### Installation

The plugin lives in the `apps/nvim/` subdirectory of the hitspec repository, so
the plugin manager must add that subdirectory to `runtimepath`. Listing
`"abdul-hamid-achik/hitspec"` on its own installs the repository but loads nothing.

<Tabs>
  <Tab title="lazy.nvim">
    ```lua theme={null}
    {
      "abdul-hamid-achik/hitspec",
      config = function(plugin)
        vim.opt.rtp:append(plugin.dir .. "/apps/nvim")
        require("hitspec").setup()
      end,
    }
    ```
  </Tab>

  <Tab title="packer.nvim">
    ```lua theme={null}
    use {
      "abdul-hamid-achik/hitspec",
      rtp = "apps/nvim",
      config = function()
        require("hitspec").setup()
      end,
    }
    ```
  </Tab>

  <Tab title="Manual">
    Clone the repository and add the subdirectory to `runtimepath`:

    ```bash theme={null}
    git clone https://github.com/abdul-hamid-achik/hitspec.git ~/.local/share/hitspec
    ```

    ```lua theme={null}
    vim.opt.rtp:append(vim.fn.expand("~/.local/share/hitspec/apps/nvim"))
    require("hitspec").setup()
    ```
  </Tab>
</Tabs>

<Tip>
  Snippets require [LuaSnip](https://github.com/L3MON4D3/LuaSnip). Call `require("hitspec").setup()` in your config to register them. If LuaSnip is not installed, snippets are silently skipped.
</Tip>

## Shell Completions

hitspec can generate completion scripts for your shell, giving you tab completion for commands and flags.

<CodeGroup>
  ```bash Bash theme={null}
  hitspec completion bash > /etc/bash_completion.d/hitspec
  ```

  ```bash Zsh theme={null}
  hitspec completion zsh > "${fpath[1]}/_hitspec"
  ```

  ```bash Fish theme={null}
  hitspec completion fish > ~/.config/fish/completions/hitspec.fish
  ```

  ```powershell PowerShell theme={null}
  hitspec completion powershell > hitspec.ps1
  ```
</CodeGroup>

After installing completions, restart your shell or source the completion file for changes to take effect.

<Tip>
  On macOS with Homebrew, Bash completions are typically loaded from `/opt/homebrew/etc/bash_completion.d/`. For Zsh, you may need to add the completions directory to your `fpath` in `~/.zshrc` before `compinit` is called.
</Tip>


# Auth Flow
Source: https://hitspec.dev/examples/auth-flow

Login to get a token, capture it, and use it in authenticated requests with @auth bearer and @depends.

Most APIs require authentication. This tutorial demonstrates a common pattern: log in to get an access token, capture it, and pass it to all subsequent requests. You will use captures, dependencies, and the `@auth` directive.

## Prerequisites

* hitspec installed ([Installation](/installation))
* Familiarity with the [Basic CRUD](/examples/basic-crud) example

## The Complete Test File

Create a file called `auth-flow.http`:

```http auth-flow.http theme={null}
@baseUrl = https://httpbin.org

### Login and get a token
# @name login
# @tags auth

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

{
  "username": "testuser",
  "password": "secret123"
}

>>>
expect status 200
expect body.json.username == "testuser"
<<<

>>>capture
token from body.json.username
userId from body.json.username
<<<

### Access a protected resource
# @name getProfile
# @tags auth, profile
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/bearer

>>>
expect status 200
expect body.authenticated == true
expect body.token exists
<<<

>>>capture
bearerToken from body.token
<<<

### Access another protected endpoint
# @name getSettings
# @tags auth, settings
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/headers

>>>
expect status 200
expect header Content-Type contains "application/json"
expect body.headers.Authorization exists
expect body.headers.Authorization startsWith "Bearer"
<<<

### Update profile with auth
# @name updateProfile
# @tags auth, profile
# @depends getProfile
# @auth bearer {{login.token}}

PUT {{baseUrl}}/put
Content-Type: application/json

{
  "displayName": "Test User",
  "email": "testuser@example.com"
}

>>>
expect status 200
expect body.json.displayName == "Test User"
expect body.json.email endsWith "@example.com"
<<<

### Basic auth request
# @name basicAuthRequest
# @tags auth
# @auth basic testuser, testpass

GET {{baseUrl}}/basic-auth/testuser/testpass

>>>
expect status 200
expect body.authenticated == true
expect body.user == "testuser"
<<<
```

## Step-by-Step Breakdown

<Steps>
  <Step title="Login and capture the token">
    The first request simulates a login and captures credentials from the response.

    ```http theme={null}
    ### Login and get a token
    # @name login
    # @tags auth

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

    {
      "username": "testuser",
      "password": "secret123"
    }

    >>>
    expect status 200
    expect body.json.username == "testuser"
    <<<

    >>>capture
    token from body.json.username
    userId from body.json.username
    <<<
    ```

    The `>>>capture` block extracts values from the response body. These become available as `{{login.token}}` and `{{login.userId}}` in later requests.

    <Note>
      In a real API, you would capture from a path like `body.access_token` or `body.data.token`. This example uses httpbin.org which echoes back the posted JSON.
    </Note>
  </Step>

  <Step title="Use the token with @auth bearer">
    The `@auth bearer` directive automatically adds an `Authorization: Bearer <token>` header.

    ```http theme={null}
    ### Access a protected resource
    # @name getProfile
    # @tags auth, profile
    # @depends login
    # @auth bearer {{login.token}}

    GET {{baseUrl}}/bearer

    >>>
    expect status 200
    expect body.authenticated == true
    expect body.token exists
    <<<
    ```

    Key points:

    * `# @depends login` ensures this runs after the login request
    * `# @auth bearer {{login.token}}` injects the captured token
    * httpbin.org's `/bearer` endpoint validates the Bearer token and returns `authenticated: true`

    This is equivalent to manually writing the header:

    ```http theme={null}
    Authorization: Bearer {{login.token}}
    ```

    But `@auth bearer` is cleaner and makes the intent explicit.
  </Step>

  <Step title="Chain multiple authenticated requests">
    Multiple requests can depend on the same login and reuse the token.

    ```http theme={null}
    ### Access another protected endpoint
    # @name getSettings
    # @tags auth, settings
    # @depends login
    # @auth bearer {{login.token}}

    GET {{baseUrl}}/headers

    >>>
    expect status 200
    expect header Content-Type contains "application/json"
    expect body.headers.Authorization exists
    expect body.headers.Authorization startsWith "Bearer"
    <<<
    ```

    The `startsWith` operator checks that the Authorization header was sent correctly.
  </Step>

  <Step title="Dependent chain: login -> getProfile -> updateProfile">
    You can create multi-level dependency chains.

    ```http theme={null}
    ### Update profile with auth
    # @name updateProfile
    # @tags auth, profile
    # @depends getProfile
    # @auth bearer {{login.token}}

    PUT {{baseUrl}}/put
    Content-Type: application/json

    {
      "displayName": "Test User",
      "email": "testuser@example.com"
    }

    >>>
    expect status 200
    expect body.json.displayName == "Test User"
    expect body.json.email endsWith "@example.com"
    <<<
    ```

    `updateProfile` depends on `getProfile`, which depends on `login`. hitspec resolves the full dependency graph automatically.
  </Step>

  <Step title="Basic authentication">
    hitspec supports multiple auth types. Here is Basic auth:

    ```http theme={null}
    ### Basic auth request
    # @name basicAuthRequest
    # @tags auth
    # @auth basic testuser, testpass

    GET {{baseUrl}}/basic-auth/testuser/testpass

    >>>
    expect status 200
    expect body.authenticated == true
    expect body.user == "testuser"
    <<<
    ```

    The `@auth basic` directive base64-encodes the credentials and sends them as `Authorization: Basic <encoded>`.
  </Step>

  <Step title="Run the auth tests">
    Run all auth tests:

    ```bash theme={null}
    hitspec run auth-flow.http
    ```

    Run only profile-related tests:

    ```bash theme={null}
    hitspec run auth-flow.http --tags profile
    ```

    Expected output:

    ```
      login (245ms)
      getProfile (132ms)
      getSettings (118ms)
      updateProfile (156ms)
      basicAuthRequest (189ms)

    5 passed, 0 failed
    ```
  </Step>
</Steps>

## Supported Auth Types

hitspec supports eight authentication methods. Here are the most common:

| Type | Syntax | Header Sent |
| - | - | - |
| Bearer | `@auth bearer {{token}}` | `Authorization: Bearer <token>` |
| Basic | `@auth basic user, pass` | `Authorization: Basic <base64>` |
| API Key (header) | `@auth apiKey X-API-Key, {{key}}` | `X-API-Key: <key>` |
| API Key (query) | `@auth apiKeyQuery api_key, {{key}}` | `?api_key=<key>` |
| Digest | `@auth digest user, pass` | Digest authentication |
| AWS Sig v4 | `@auth aws {{access}}, {{secret}}, {{region}}, {{service}}` | AWS Signature v4 |

## Real-World Pattern

In practice, an auth flow test file typically looks like this:

```http theme={null}
@baseUrl = https://api.yourservice.com

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

{
  "email": "{{$randomEmail()}}",
  "password": "testPassword123"
}

>>>
expect status 200
expect body.access_token exists
expect body.expires_in > 0
<<<

>>>capture
accessToken from body.access_token
refreshToken from body.refresh_token
<<<

### Use the token
# @depends login
# @auth bearer {{login.accessToken}}
GET {{baseUrl}}/me

>>>
expect status 200
expect body.email exists
<<<
```

## Next Steps

<Columns>
  <Card title="Captures" icon="link" href="/concepts/captures">
    Learn all capture sources: body, headers, status, and duration.
  </Card>

  <Card title="Dependencies" icon="arrow-right" href="/concepts/dependencies">
    Understand how hitspec resolves the dependency graph.
  </Card>
</Columns>


# Basic CRUD
Source: https://hitspec.dev/examples/basic-crud

Walk through a complete CRUD test file that covers GET, POST, PUT, and DELETE operations against a REST API.

This tutorial builds a test file that exercises all four CRUD operations against the [JSONPlaceholder](https://jsonplaceholder.typicode.com) API. You will learn how to define variables, write assertions, capture response values, and chain requests with dependencies.

## Prerequisites

* hitspec installed ([Installation](/installation))
* A terminal

## The Complete Test File

Here is the full test file you will build step by step. Create a file called `crud.http`:

```http crud.http theme={null}
@baseUrl = https://jsonplaceholder.typicode.com

### List all posts
# @name listPosts
# @tags smoke, read

GET {{baseUrl}}/posts

>>>
expect status 200
expect body type array
expect body[0].id exists
expect body[0].title exists
expect body[0].userId exists
<<<

### Get a single post
# @name getPost
# @tags read

GET {{baseUrl}}/posts/1

>>>
expect status 200
expect body.id == 1
expect body.title exists
expect body.userId type number
expect duration < 2000
<<<

### Create a post
# @name createPost
# @tags write

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

{
  "title": "Testing with hitspec",
  "body": "Plain text API tests. No magic.",
  "userId": 1
}

>>>
expect status 201
expect body.id exists
expect body.title == "Testing with hitspec"
expect body.userId == 1
<<<

>>>capture
newPostId from body.id
<<<

### Update the post
# @name updatePost
# @tags write
# @depends createPost

PUT {{baseUrl}}/posts/{{createPost.newPostId}}
Content-Type: application/json

{
  "id": {{createPost.newPostId}},
  "title": "Updated with hitspec",
  "body": "This post has been updated.",
  "userId": 1
}

>>>
expect status 200
expect body.title == "Updated with hitspec"
<<<

### Delete the post
# @name deletePost
# @tags write
# @depends updatePost

DELETE {{baseUrl}}/posts/{{createPost.newPostId}}

>>>
expect status 200
<<<
```

## Step-by-Step Breakdown

<Steps>
  <Step title="Define variables">
    The `@baseUrl` variable at the top of the file stores the API base URL. Reference it anywhere with `{{baseUrl}}`.

    ```http theme={null}
    @baseUrl = https://jsonplaceholder.typicode.com
    ```

    Variables reduce duplication and make it easy to switch environments. You can override them per-environment in `hitspec.yaml` and select one with the `--env` flag.
  </Step>

  <Step title="List all posts (GET collection)">
    The first request fetches all posts and validates the response shape.

    ```http theme={null}
    ### List all posts
    # @name listPosts
    # @tags smoke, read

    GET {{baseUrl}}/posts

    >>>
    expect status 200
    expect body type array
    expect body[0].id exists
    expect body[0].title exists
    expect body[0].userId exists
    <<<
    ```

    Key concepts:

    * `###` separates requests within a file
    * `# @name listPosts` gives the request an identifier for captures and dependencies
    * `# @tags smoke, read` lets you filter with `--tags smoke`
    * The `>>> ... <<<` block contains assertions
    * `expect body type array` checks the response is a JSON array
    * `expect body[0].id exists` checks nested fields using JSON path syntax
  </Step>

  <Step title="Get a single post (GET by ID)">
    This request fetches a specific post and adds a response time assertion.

    ```http theme={null}
    ### Get a single post
    # @name getPost
    # @tags read

    GET {{baseUrl}}/posts/1

    >>>
    expect status 200
    expect body.id == 1
    expect body.title exists
    expect body.userId type number
    expect duration < 2000
    <<<
    ```

    * `expect body.id == 1` checks an exact value
    * `expect body.userId type number` validates the JSON type
    * `expect duration < 2000` fails if the response takes more than 2 seconds
  </Step>

  <Step title="Create a post (POST with JSON body)">
    This request creates a new resource and captures its ID for later use.

    ```http theme={null}
    ### Create a post
    # @name createPost
    # @tags write

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

    {
      "title": "Testing with hitspec",
      "body": "Plain text API tests. No magic.",
      "userId": 1
    }

    >>>
    expect status 201
    expect body.id exists
    expect body.title == "Testing with hitspec"
    expect body.userId == 1
    <<<

    >>>capture
    newPostId from body.id
    <<<
    ```

    The `>>>capture ... <<<` block extracts `body.id` from the response and stores it as `newPostId`. Later requests reference it as `{{createPost.newPostId}}` (request name dot capture name).
  </Step>

  <Step title="Update the post (PUT with dependency)">
    This request depends on `createPost` and uses the captured ID.

    ```http theme={null}
    ### Update the post
    # @name updatePost
    # @tags write
    # @depends createPost

    PUT {{baseUrl}}/posts/{{createPost.newPostId}}
    Content-Type: application/json

    {
      "id": {{createPost.newPostId}},
      "title": "Updated with hitspec",
      "body": "This post has been updated.",
      "userId": 1
    }

    >>>
    expect status 200
    expect body.title == "Updated with hitspec"
    <<<
    ```

    `# @depends createPost` ensures this request runs after `createPost` completes, even in parallel mode.
  </Step>

  <Step title="Delete the post (DELETE)">
    The final request deletes the resource. It depends on `updatePost` to preserve execution order.

    ```http theme={null}
    ### Delete the post
    # @name deletePost
    # @tags write
    # @depends updatePost

    DELETE {{baseUrl}}/posts/{{createPost.newPostId}}

    >>>
    expect status 200
    <<<
    ```
  </Step>

  <Step title="Run the tests">
    Run all requests:

    ```bash theme={null}
    hitspec run crud.http
    ```

    Run only read operations:

    ```bash theme={null}
    hitspec run crud.http --tags read
    ```

    Run only write operations:

    ```bash theme={null}
    hitspec run crud.http --tags write
    ```

    Expected output:

    ```
      listPosts (142ms)
      getPost (98ms)
      createPost (201ms)
      updatePost (156ms)
      deletePost (113ms)

    5 passed, 0 failed
    ```
  </Step>
</Steps>

## Key Concepts Used

| Concept | Syntax | Purpose |
| - | - | - |
| Variables | `@baseUrl = ...` | Reusable values |
| Request names | `# @name createPost` | Identify requests for captures and dependencies |
| Tags | `# @tags smoke, read` | Filter which requests to run |
| Assertions | `expect status 200` | Validate responses |
| Captures | `newPostId from body.id` | Extract values from responses |
| Dependencies | `# @depends createPost` | Control execution order |

## Next Steps

<Columns>
  <Card title="Auth Flow" icon="lock" href="/examples/auth-flow">
    Chain login and authenticated requests with token capture.
  </Card>

  <Card title="Environments" icon="server" href="/concepts/environments">
    Use different base URLs and variables per environment.
  </Card>
</Columns>


# CI/CD Integration
Source: https://hitspec.dev/examples/ci-cd

Run hitspec tests in GitHub Actions with JUnit output, environment variables, and pass/fail exit codes.

hitspec is designed for CI/CD. It produces JUnit XML output, uses standard exit codes, and has an official GitHub Action. This tutorial walks through setting up API tests in a GitHub Actions workflow.

## Prerequisites

* A GitHub repository
* hitspec test files in your repo (see [Basic CRUD](/examples/basic-crud))

## Quick Setup with the Official Action

The fastest way to run hitspec in CI is with the official GitHub Action.

<Steps>
  <Step title="Add test files to your repo">
    Create a `tests/` directory with your `.http` files:

    ```http tests/api.http theme={null}
    @baseUrl = https://jsonplaceholder.typicode.com

    ### Health check
    # @name healthCheck
    # @tags smoke

    GET {{baseUrl}}/posts/1

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

    ### List posts
    # @name listPosts
    # @tags smoke

    GET {{baseUrl}}/posts

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

    ### Create post
    # @name createPost
    # @tags write

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

    {
      "title": "CI Test Post",
      "body": "Created during CI pipeline",
      "userId": 1
    }

    >>>
    expect status 201
    expect body.id exists
    <<<
    ```
  </Step>

  <Step title="Create the workflow file">
    Create `.github/workflows/api-tests.yml`:

    ```yaml .github/workflows/api-tests.yml theme={null}
    name: API Tests

    on:
      push:
        branches: [main]
      pull_request:
        branches: [main]

    jobs:
      api-tests:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v6

          - name: Run API tests
            uses: abdul-hamid-achik/hitspec@v2
            with:
              files: tests/
              output: junit
              output-file: test-results.xml

          - name: Upload test results
            uses: actions/upload-artifact@v7
            if: always()
            with:
              name: test-results
              path: test-results.xml
    ```

    The `if: always()` on the upload step ensures test results are uploaded even when tests fail, so you can inspect failures in the GitHub UI.
  </Step>

  <Step title="Verify the results">
    When the workflow runs, it:

    1. Installs the latest hitspec binary
    2. Runs all `.http` files in the `tests/` directory
    3. Produces JUnit XML output at `test-results.xml`
    4. Exits with code 0 on success, 1 on failure
    5. Uploads the XML as a build artifact

    GitHub Actions natively understands JUnit XML and will show test results in the PR checks tab.
  </Step>
</Steps>

## Workflow Recipes

### Run only smoke tests

Filter by tags to run a fast subset in CI:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    tags: smoke
    output: junit
    output-file: smoke-results.xml
```

### Run tests against staging

Use the `env` input to select an environment defined in the `environments` section of your `hitspec.yaml`:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    env: staging
    output: junit
    output-file: test-results.xml
```

### Pass secrets via environment file

Create a `.env` file at runtime from GitHub secrets:

```yaml theme={null}
- name: Create env file
  run: |
    echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci
    echo "API_BASE_URL=${{ secrets.STAGING_URL }}" >> .env.ci

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    env-file: .env.ci
    output: junit
    output-file: test-results.xml
```

### Parallel execution

Run independent tests concurrently for faster feedback:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    parallel: true
    output: junit
    output-file: test-results.xml
```

### Fail fast on first error

Use `bail` to stop at the first failure:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    bail: true
    output: junit
    output-file: test-results.xml
```

### Stress testing in CI

Run load tests with pass/fail thresholds as a quality gate:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/api.http
    stress: true
    duration: 2m
    rate: 50
    threshold: "p95<500ms,errors<1%"
```

The workflow fails if the p95 latency exceeds 500ms or the error rate exceeds 1%.

## Manual Installation (Without the Action)

If you prefer to install hitspec yourself:

```yaml theme={null}
name: API Tests (manual setup)

on:
  push:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install hitspec
        run: |
          # Choose a published version from the Releases page:
          # https://github.com/abdul-hamid-achik/hitspec/releases/latest
          VERSION=2.18.0
          curl -fsSL "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_linux_amd64.tar.gz" | tar xz
          sudo mv hitspec /usr/local/bin/

      - name: Run tests
        run: hitspec run tests/ -o junit --output-file test-results.xml

      - name: Upload results
        uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results
          path: test-results.xml
```

## Exit Codes

hitspec uses standard exit codes for CI integration:

| Code | Meaning |
| - | - |
| `0` | All tests passed |
| `1` | One or more tests failed |
| `2` | A file could not be loaded (syntax error) |
| `3` | Configuration error |
| `4` | A request got no response (connection error) |

See [Exit Codes](/reference/exit-codes) for the full list. CI platforms treat any non-zero exit code as a failure, so hitspec works out of the box with GitHub Actions, GitLab CI, CircleCI, Jenkins, and others.

## Environment Variables

All CLI flags can be set via environment variables with the `HITSPEC_` prefix. This is useful for CI where you want to configure hitspec without modifying the workflow:

```yaml theme={null}
env:
  HITSPEC_ENV: staging
  HITSPEC_TIMEOUT: 60s
  HITSPEC_BAIL: "true"
  HITSPEC_OUTPUT: junit
  HITSPEC_OUTPUT_FILE: results.xml
```

| Variable | CLI Flag | Description |
| - | - | - |
| `HITSPEC_ENV` | `--env` | Environment to use |
| `HITSPEC_ENV_FILE` | `--env-file` | Path to .env file |
| `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_TIMEOUT` | `--timeout` | Request timeout |

## Complete Production Workflow

Here is a full workflow that runs smoke tests on every push, full tests on PRs, and stress tests on merge to main:

```yaml .github/workflows/api-tests-full.yml theme={null}
name: API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  smoke:
    name: Smoke Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          tags: smoke
          bail: true
          output: junit
          output-file: smoke-results.xml
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: smoke-results
          path: smoke-results.xml

  full:
    name: Full Test Suite
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    needs: smoke
    steps:
      - uses: actions/checkout@v6
      - name: Create env file
        run: |
          echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci
      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: staging
          env-file: .env.ci
          parallel: true
          output: junit
          output-file: full-results.xml
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: full-results
          path: full-results.xml

  stress:
    name: Load Test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: smoke
    steps:
      - uses: actions/checkout@v6
      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/api.http
          tags: smoke
          stress: true
          duration: 2m
          rate: 100
          threshold: "p95<500ms,errors<0.5%"
```

## Next Steps

<Columns>
  <Card title="Output Formats" icon="table" href="/integrations/output-formats">
    Learn about JUnit, JSON, TAP, and HTML output options.
  </Card>

  <Card title="Stress Testing" icon="bolt" href="/examples/stress-testing">
    Configure load tests with profiles and thresholds.
  </Card>
</Columns>


# Contract Testing
Source: https://hitspec.dev/examples/contract-testing

Example: Define and verify API contracts between services.

This example shows a consumer-driven contract for a User Service API.

## Contract File

```http theme={null}
# contracts/user-service.http
@baseUrl = {{baseUrl}}

### List users
# @name listUsers
# @contract.provider UserService

GET {{baseUrl}}/users

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

### Get user by ID
# @name getUserById
# @contract.provider UserService
# @contract.state "user with id 1 exists"

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id == 1
expect body.name type string
expect body.email type string
expect body.email matches /^.+@.+\..+$/
<<<

### Create user
# @name createUser
# @contract.provider UserService

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

{
  "name": "New User",
  "email": "new@example.com"
}

>>>
expect status 201
expect body.id exists
expect body.id type number
expect body.name == "New User"
<<<

### User not found
# @name userNotFound
# @contract.provider UserService
# @contract.state "no users exist"

GET {{baseUrl}}/users/999

>>>
expect status 404
<<<
```

## State Handler

```bash theme={null}
#!/bin/bash
# setup-states.sh
case "$1" in
  "user with id 1 exists")
    curl -s -X POST localhost:3000/test/seed \
      -H "Content-Type: application/json" \
      -d '{"id":1,"name":"John","email":"john@example.com"}'
    ;;
  "no users exist")
    curl -s -X POST localhost:3000/test/reset
    ;;
esac
```

## Verify

```bash theme={null}
hitspec contract verify contracts/ \
  --provider http://localhost:3000 \
  --state-handler ./setup-states.sh
```


# Database Assertions
Source: https://hitspec.dev/examples/database-assertions

Example: Verify API side effects with database queries.

This example shows how to use database assertions to verify that API calls produce the expected database changes.

<Warning>
  Run with `--allow-db` to enable database assertions: `hitspec run tests/ --allow-db`
</Warning>

## Setup

```http theme={null}
@baseUrl = http://localhost:3000
@dbUrl = sqlite://./test.db
```

## Create and Verify

```http theme={null}
### Create a user
# @name createUser
# @tags db
# @db {{dbUrl}}

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

{
  "name": "John Doe",
  "email": "john@example.com"
}

>>>
expect status 201
expect body.id exists
<<<

>>>capture
userId from body.id
<<<

>>>db
SELECT name, email FROM users WHERE id = {{createUser.userId}}
expect name == "John Doe"
expect email == "john@example.com"
<<<
```

## Update and Verify

```http theme={null}
### Update user email
# @name updateUser
# @depends createUser
# @tags db
# @db {{dbUrl}}

PUT {{baseUrl}}/users/{{createUser.userId}}
Content-Type: application/json

{
  "email": "john.doe@newdomain.com"
}

>>>
expect status 200
<<<

>>>db
SELECT email FROM users WHERE id = {{createUser.userId}}
expect email == "john.doe@newdomain.com"
<<<
```

## Delete and Verify

```http theme={null}
### Delete user
# @depends updateUser
# @tags db
# @db {{dbUrl}}

DELETE {{baseUrl}}/users/{{createUser.userId}}

>>>
expect status 204
<<<

>>>db
SELECT COUNT(*) as count FROM users WHERE id = {{createUser.userId}}
expect count == 0
<<<
```

## Run It

```bash theme={null}
hitspec run examples/database-assertions.http --allow-db --env dev
```


# GraphQL
Source: https://hitspec.dev/examples/graphql

Query a GraphQL API with variables, test nested response fields, and chain mutations with captures.

hitspec has first-class support for GraphQL. Instead of manually constructing JSON bodies, you write queries in a `>>>graphql` block and variables in a `>>>variables` block. hitspec handles the rest.

## Prerequisites

* hitspec installed ([Installation](/installation))
* Familiarity with [captures and dependencies](/concepts/captures)

## The Complete Test File

This example tests the [Countries GraphQL API](https://countries.trevorblades.com/), a free public GraphQL endpoint.

Create a file called `graphql.http`:

```http graphql.http theme={null}
@baseUrl = https://countries.trevorblades.com

### Get a country by code
# @name getCountry
# @tags smoke

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

>>>graphql
query GetCountry($code: ID!) {
  country(code: $code) {
    name
    capital
    currency
    emoji
    languages {
      name
      code
    }
    continent {
      name
    }
  }
}

>>>variables
{
  "code": "US"
}
<<<

>>>
expect status 200
expect body.data.country.name == "United States"
expect body.data.country.capital == "Washington D.C."
expect body.data.country.currency contains "USD"
expect body.data.country.emoji exists
expect body.data.country.languages type array
expect body.data.country.languages length > 0
expect body.data.country.languages[0].name == "English"
expect body.data.country.continent.name == "North America"
<<<

>>>capture
countryName from body.data.country.name
continentName from body.data.country.continent.name
<<<

### List all continents
# @name listContinents
# @tags smoke

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

>>>graphql
query {
  continents {
    code
    name
  }
}
<<<

>>>
expect status 200
expect body.data.continents type array
expect body.data.continents length 7
expect body.data.continents[0].code exists
expect body.data.continents[0].name exists
<<<

### Get countries in a continent
# @name countriesInContinent
# @tags continent
# @depends getCountry

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

>>>graphql
query GetContinent($code: ID!) {
  continent(code: $code) {
    name
    countries {
      name
      capital
      emoji
    }
  }
}

>>>variables
{
  "code": "NA"
}
<<<

>>>
expect status 200
expect body.data.continent.name == "North America"
expect body.data.continent.countries type array
expect body.data.continent.countries length > 0
<<<

>>>capture
countryCount from body.data.continent.countries.#
<<<

### Get languages
# @name getLanguages
# @tags language

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

>>>graphql
query GetLanguage($code: ID!) {
  language(code: $code) {
    name
    native
    rtl
  }
}

>>>variables
{
  "code": "en"
}
<<<

>>>
expect status 200
expect body.data.language.name == "English"
expect body.data.language.native == "English"
expect body.data.language.rtl == false
<<<

### Query with multiple filters
# @name filteredCountries
# @tags filter

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

>>>graphql
query FilterCountries($filter: CountryFilterInput) {
  countries(filter: $filter) {
    name
    code
    capital
    continent {
      name
    }
  }
}

>>>variables
{
  "filter": {
    "continent": {
      "eq": "NA"
    }
  }
}
<<<

>>>
expect status 200
expect body.data.countries type array
expect body.data.countries length > 0
expect body.data.countries each type object
<<<
```

## Step-by-Step Breakdown

<Steps>
  <Step title="Write a GraphQL query with variables">
    The `>>>graphql` block contains the query, and `>>>variables` provides the variable values as JSON.

    ```http theme={null}
    POST {{baseUrl}}/
    Content-Type: application/json

    >>>graphql
    query GetCountry($code: ID!) {
      country(code: $code) {
        name
        capital
        currency
      }
    }

    >>>variables
    {
      "code": "US"
    }
    <<<
    ```

    hitspec converts this into the standard GraphQL JSON format:

    ```json theme={null}
    {
      "query": "query GetCountry($code: ID!) { country(code: $code) { name capital currency } }",
      "variables": { "code": "US" }
    }
    ```

    You write the query naturally and hitspec handles the serialization.
  </Step>

  <Step title="Assert nested response fields">
    GraphQL responses have a `data` wrapper. Use dot notation to reach nested fields.

    ```http theme={null}
    >>>
    expect status 200
    expect body.data.country.name == "United States"
    expect body.data.country.capital == "Washington D.C."
    expect body.data.country.currency contains "USD"
    expect body.data.country.languages type array
    expect body.data.country.languages[0].name == "English"
    expect body.data.country.continent.name == "North America"
    <<<
    ```

    The JSON path syntax supports:

    * Dot notation: `body.data.country.name`
    * Array indexing: `body.data.country.languages[0].name`
    * Length via gjson: `body.data.country.languages.#`
  </Step>

  <Step title="Capture values from GraphQL responses">
    Captures work the same way as with REST responses. Extract values for use in later requests.

    ```http theme={null}
    >>>capture
    countryName from body.data.country.name
    continentName from body.data.country.continent.name
    <<<
    ```

    These values are accessible as `{{getCountry.countryName}}` and `{{getCountry.continentName}}` in subsequent requests.
  </Step>

  <Step title="Query without variables">
    For queries with no variables, you can omit the `>>>variables` block.

    ```http theme={null}
    POST {{baseUrl}}/
    Content-Type: application/json

    >>>graphql
    query {
      continents {
        code
        name
      }
    }
    <<<
    ```
  </Step>

  <Step title="Use the each operator for collections">
    The `each` operator applies an assertion to every element in an array.

    ```http theme={null}
    >>>
    expect status 200
    expect body.data.countries type array
    expect body.data.countries each type object
    <<<
    ```

    This verifies that every item in the `countries` array is a JSON object.
  </Step>

  <Step title="Run the GraphQL tests">
    ```bash theme={null}
    hitspec run graphql.http
    ```

    Run only smoke-tagged queries:

    ```bash theme={null}
    hitspec run graphql.http --tags smoke
    ```

    Expected output:

    ```
      getCountry (312ms)
      listContinents (198ms)
      countriesInContinent (245ms)
      getLanguages (167ms)
      filteredCountries (223ms)

    5 passed, 0 failed
    ```
  </Step>
</Steps>

## GraphQL Error Handling

GraphQL APIs return errors in a `data.errors` array. You can assert on these:

```http theme={null}
POST {{baseUrl}}/
Content-Type: application/json

>>>graphql
query {
  nonExistentField {
    id
  }
}
<<<

>>>
expect status 200
expect body.errors exists
expect body.errors type array
expect body.errors length > 0
expect body.errors[0].message exists
<<<
```

<Tip>
  GraphQL APIs typically return HTTP 200 even for query errors. Always check `body.errors` in addition to the status code.
</Tip>

## Next Steps

<Columns>
  <Card title="Multipart and GraphQL" icon="code" href="/features/multipart-graphql">
    Full reference for GraphQL blocks and multipart uploads.
  </Card>

  <Card title="Assertions" icon="check" href="/concepts/assertions">
    All 26 assertion operators available in hitspec.
  </Card>
</Columns>


# Mock Server
Source: https://hitspec.dev/examples/mock-server

Example: Generate mock servers from your hitspec test files.

hitspec can generate a mock HTTP server from your `.http` files. The mock server uses request definitions and assertions to create realistic responses.

## Define Endpoints

```http theme={null}
# api.http
@baseUrl = http://localhost:3000

### List users
# @name listUsers

GET {{baseUrl}}/users

>>>
expect status 200
expect body type array
expect body[0].id type number
expect body[0].name type string
<<<

### Get user by ID
# @name getUser

GET {{baseUrl}}/users/{{id}}

>>>
expect status 200
expect body.id type number
expect body.name type string
expect body.email type string
<<<

### Create user
# @name createUser

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

{
  "name": "John Doe",
  "email": "john@example.com"
}

>>>
expect status 201
expect body.id exists
expect body.name == "John Doe"
<<<
```

## Start the Mock Server

```bash theme={null}
hitspec mock api.http --port 3000
```

The mock server:

* Parses your `.http` files to extract routes
* Generates responses from assertions and explicit mock blocks
* Supports path parameters (`/users/{{id}}`)

## With Delay

Simulate network latency:

```bash theme={null}
hitspec mock api.http --port 3000 --delay 100ms
```

## From a Directory

```bash theme={null}
hitspec mock ./tests/ --port 3000 --verbose
```

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--port` | `-p` | Server port | `3000` |
| `--delay` | `-d` | Response delay | `0` |
| `--verbose` | `-v` | Verbose logging | `false` |

## Use Cases

* **Frontend development** -- mock the API while the backend is in progress
* **Integration testing** -- replace external services with mocks
* **Demos** -- show API behavior without a running backend
* **Offline development** -- work without network access


# Stress Testing
Source: https://hitspec.dev/examples/stress-testing

Load test your APIs with configurable rate, virtual users, ramp-up phases, and pass/fail thresholds.

hitspec includes a built-in stress testing engine. You do not need a separate tool -- the same `.http` files you use for functional tests can drive load tests. This tutorial covers rate-based testing, virtual user mode, multi-phase profiles, and threshold-based pass/fail.

## Prerequisites

* hitspec installed ([Installation](/installation))
* A test file to stress test (see [Basic CRUD](/examples/basic-crud))

## Quick Start

The simplest way to stress test is with CLI flags:

```bash theme={null}
hitspec run api.http --stress --duration 30s --rate 10
```

This sends 10 requests per second for 30 seconds against the requests defined in `api.http`.

<Steps>
  <Step title="Create a test file for stress testing">
    Create `stress.http` with a simple request:

    ```http stress.http theme={null}
    @baseUrl = https://httpbin.org

    ### Health check
    # @name healthCheck
    # @tags smoke

    GET {{baseUrl}}/get

    >>>
    expect status 200
    expect duration < 2000
    <<<

    ### Create item
    # @name createItem
    # @tags write

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

    {
      "name": "Load test item",
      "timestamp": "{{$timestamp()}}"
    }

    >>>
    expect status 200
    <<<
    ```

    <Tip>
      Use `{{$timestamp()}}` or `{{$uuid()}}` to generate unique values on every request. This avoids caching effects and simulates realistic traffic.
    </Tip>
  </Step>

  <Step title="Run a rate-based stress test">
    Rate mode sends a fixed number of requests per second:

    ```bash theme={null}
    hitspec run stress.http --stress --duration 1m --rate 20
    ```

    This runs for 1 minute at 20 requests per second. hitspec distributes the load across all requests in the file.

    Output:

    ```
    Stress test: rate=20 rps, duration=1m0s

      Requests:  1200 total, 1195 passed, 5 failed
      Duration:  1m0.2s
      RPS:       19.92 avg

      Latency:
        p50:   45ms
        p95:   123ms
        p99:   287ms
        max:   412ms

      Error Rate: 0.42%
    ```
  </Step>

  <Step title="Run a virtual user stress test">
    VU mode simulates concurrent users, each sending requests sequentially:

    ```bash theme={null}
    hitspec run stress.http --stress --duration 1m --vus 10 --think-time 500ms
    ```

    This creates 10 virtual users, each waiting 500ms between requests. Unlike rate mode, VU mode models real user behavior where each user completes a request before starting the next.
  </Step>

  <Step title="Add ramp-up">
    Ramp up gradually to avoid overwhelming the server at startup:

    ```bash theme={null}
    hitspec run stress.http --stress --duration 2m --rate 50 --ramp-up 30s
    ```

    The rate increases linearly from 0 to 50 rps over the first 30 seconds, then holds at 50 for the remaining 90 seconds.
  </Step>

  <Step title="Set pass/fail thresholds">
    Thresholds let you define success criteria. The test exits with code 1 if any threshold is violated:

    ```bash theme={null}
    hitspec run stress.http --stress --duration 1m --rate 20 \
      --threshold "p95<200ms,errors<1%,rps>15"
    ```

    Available threshold metrics:

    | Metric | Operator | Example | Description |
    | - | - | - | - |
    | `p50` | `<`, `<=` | `p50<100ms` | 50th percentile latency |
    | `p95` | `<`, `<=` | `p95<200ms` | 95th percentile latency |
    | `p99` | `<`, `<=` | `p99<500ms` | 99th percentile latency |
    | `max` | `<`, `<=` | `max<1s` | Maximum latency |
    | `errors` | `<`, `<=` | `errors<1%` | Error rate percentage (transport errors and non-2xx responses, not assertion failures) |
    | `assertions` | `<`, `<=` | `assertions<1%` | Share of checked responses that failed an `expect` assertion |
    | `rps` | `>`, `>=` | `rps>50` | Minimum requests per second |

    Combine multiple thresholds with commas. In a `hitspec.yaml` profile a threshold value may also start with an operator (`p95: "<=250ms"`); `errors: "0%"` means no request may fail. See [Stress Testing](/features/stress-testing#thresholds-in-profiles).
  </Step>
</Steps>

## Configuration File

For repeatable stress test configurations, define profiles in `hitspec.yaml`.

### Rate-based Profile

```yaml hitspec.yaml theme={null}
stress:
  profiles:
    smoke:
      duration: 30s
      rate: 5
      thresholds:
        p95: "500ms"
        errors: "0%"

    load:
      duration: 5m
      rate: 50
      rampUp: 1m
      maxVUs: 200
      thresholds:
        p95: "200ms"
        p99: "500ms"
        errors: "1%"
        rps: "45"

    spike:
      duration: 2m
      rate: 200
      rampUp: 10s
      maxVUs: 500
      thresholds:
        p99: "1s"
        errors: "5%"
```

Run a specific profile:

```bash theme={null}
hitspec run stress.http --stress --profile load
```

### Virtual User Profile

```yaml hitspec.yaml theme={null}
stress:
  profiles:
    realistic:
      duration: 10m
      vus: 50
      thinkTime: 1s
      rampUp: 2m
      maxVUs: 100
      thresholds:
        p95: "300ms"
        errors: "0.5%"
```

VU mode is better for simulating real user behavior, where each user thinks between requests. Rate mode is better for measuring raw throughput.

## Profile Strategies

Each snippet below is one entry under `stress.profiles` in `hitspec.yaml`; the profile name (`smoke`, `load`, ...) is what you pass to `--profile`.

### Smoke Test

Verify the system handles minimal load without errors. Run this on every deploy.

```yaml theme={null}
smoke:
  duration: 30s
  rate: 5
  thresholds:
    errors: "0%"
    p95: "500ms"
```

### Load Test

Sustained normal traffic levels. Verify performance under expected conditions.

```yaml theme={null}
load:
  duration: 10m
  rate: 100
  rampUp: 2m
  thresholds:
    p95: "200ms"
    p99: "500ms"
    errors: "0.5%"
```

### Stress Test

Push beyond normal limits to find the breaking point.

```yaml theme={null}
stress:
  duration: 5m
  rate: 500
  rampUp: 1m
  maxVUs: 1000
  thresholds:
    errors: "5%"
```

### Spike Test

Sudden traffic surge to test auto-scaling and recovery.

```yaml theme={null}
spike:
  duration: 3m
  rate: 1000
  rampUp: 5s
  thresholds:
    p99: "2s"
    errors: "10%"
```

## Per-Request Configuration

You can control how individual requests participate in stress tests using metadata:

```http theme={null}
### Setup: create test data
# @name setup
# @stress.setup true

POST {{baseUrl}}/test-data
Content-Type: application/json

{"name": "stress test fixture"}

>>>
expect status 201
<<<

### Main endpoint under test
# @name getItems
# @stress.weight 3

GET {{baseUrl}}/items

>>>
expect status 200
expect duration < 500
<<<

### Secondary endpoint
# @name getItem
# @stress.weight 1

GET {{baseUrl}}/items/1

>>>
expect status 200
<<<

### Teardown: clean up
# @name teardown
# @stress.teardown true

DELETE {{baseUrl}}/test-data

>>>
expect status 200
<<<
```

| Directive | Description |
| - | - |
| `@stress.weight N` | Relative frequency (default 1). A weight of 3 means 3x more requests. |
| `@stress.think N` | Think time in ms after this request (VU mode). |
| `@stress.skip` | Exclude this request from stress testing. |
| `@stress.setup` | Run once before the stress test starts. |
| `@stress.teardown` | Run once after the stress test ends. |

## Stress Testing in CI

Combine stress profiles with the GitHub Action for automated performance gates:

```yaml .github/workflows/stress.yml theme={null}
name: Stress Tests

on:
  push:
    branches: [main]

jobs:
  stress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Smoke load test
        uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/api.http
          stress: true
          duration: 1m
          rate: 10
          threshold: "p95<500ms,errors<0.5%"
```

See the [CI/CD example](/examples/ci-cd) for complete workflow patterns.

## Reading the Output

A stress test run produces a summary like this:

```
Stress test: rate=50 rps, duration=2m0s, rampUp=30s

  Requests:  5847 total, 5812 passed, 35 failed
  Duration:  2m0.1s
  RPS:       48.72 avg

  Latency:
    p50:   32ms
    p95:   156ms
    p99:   342ms
    max:   891ms

  Error Rate: 0.60%

  Thresholds:
    p95 < 200ms .... PASS (156ms)
    p99 < 500ms .... PASS (342ms)
    errors < 1% .... PASS (0.60%)
    rps > 40 ....... PASS (48.72)

4/4 thresholds passed
```

If any threshold fails, the exit code is 1 and the failing threshold is marked:

```
  Thresholds:
    p95 < 200ms .... FAIL (267ms)
    errors < 1% .... PASS (0.60%)

1/2 thresholds passed
```

## Next Steps

<Columns>
  <Card title="Stress Testing Reference" icon="bolt" href="/features/stress-testing">
    Full reference for all stress testing options.
  </Card>

  <Card title="CI/CD Integration" icon="circle-check" href="/examples/ci-cd">
    Run stress tests in your CI pipeline.
  </Card>
</Columns>


# API Coverage
Source: https://hitspec.dev/features/api-coverage

Measure how much of your API is covered by tests using OpenAPI spec comparison and coverage reports.

API coverage tracking compares your test files against an OpenAPI specification
to show which endpoints have tests and which do not. This helps identify gaps in
your test suite.

## Usage

Enable coverage with the `--coverage` flag and point to your OpenAPI spec:

```bash theme={null}
hitspec run tests/ --coverage --openapi api-spec.yaml
```

The `--openapi` flag is required when `--coverage` is set. Coverage runs after
your tests complete and the report is printed to the console.

## What Coverage Tracks

The coverage report shows:

* **Overall coverage percentage** -- the ratio of tested endpoints to total endpoints in the spec
* **Covered endpoints** -- endpoints that have at least one test request matching the method and path
* **Uncovered endpoints** -- endpoints defined in the spec with no matching test
* **Coverage by tag/category** -- grouped by OpenAPI tags if present

## Flags

| Flag | Description |
| - | - |
| `--coverage` | Enable API coverage tracking (requires `--openapi`) |
| `--openapi` | Path to the OpenAPI/Swagger specification file (YAML or JSON) |

## Example

Given an OpenAPI spec with 20 endpoints and tests covering 15 of them:

```bash theme={null}
$ hitspec run tests/ --coverage --openapi spec.yaml

Tests: 15 passed, 0 failed
Coverage: 15/20 endpoints (75%)

Uncovered:
  GET  /api/admin/settings
  PUT  /api/admin/settings
  POST /api/reports/generate
  GET  /api/reports/{id}/download
  DELETE /api/users/{id}/sessions
```

## CI/CD Integration

Use coverage reporting in your CI pipeline to track coverage over time:

```yaml theme={null}
- name: Run API tests with coverage
  run: |
    hitspec run tests/ \
      --coverage \
      --openapi api-spec.yaml \
      --output junit \
      --output-file results.xml
```

<Tip>
  Run coverage checks locally before pushing to catch missing tests early. Pair
  coverage with the [OpenAPI import command](/reference/import-export) to
  generate test stubs for uncovered endpoints.
</Tip>


# Authentication for API tests (@auth)
Source: https://hitspec.dev/features/authentication

Configure authentication for API requests with the @auth directive. hitspec supports 8 auth methods: Bearer, Basic, API Key, Digest, AWS Sig v4, and OAuth2.

hitspec supports 8 authentication methods through the `@auth` metadata directive. Instead of manually setting `Authorization` headers, declare your auth strategy once per request and hitspec handles the rest.

## Bearer Token

The most common method for API authentication. Sends an `Authorization: Bearer <token>` header.

```http theme={null}
### Access protected resource
# @name getProfile
# @auth bearer {{token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<
```

## Basic Auth

Sends a Base64-encoded `Authorization: Basic <credentials>` header.

```http theme={null}
### Login with Basic Auth
# @name basicLogin
# @auth basic {{username}}, {{password}}

GET {{baseUrl}}/admin/dashboard

>>>
expect status 200
<<<
```

## API Key (Header)

Sends the API key as a custom request header. Specify the header name and value.

```http theme={null}
### Access with API key in header
# @name apiKeyRequest
# @auth apiKey X-API-Key, {{apiKey}}

GET {{baseUrl}}/data

>>>
expect status 200
<<<
```

## API Key (Query String)

Appends the API key as a query parameter instead of a header.

```http theme={null}
### Access with API key in query string
# @name apiKeyQueryRequest
# @auth apiKeyQuery api_key, {{apiKey}}

GET {{baseUrl}}/data

>>>
expect status 200
<<<
```

## Digest Auth

HTTP Digest authentication. hitspec handles the challenge-response handshake automatically.

```http theme={null}
### Digest auth request
# @name digestRequest
# @auth digest {{username}}, {{password}}

GET {{baseUrl}}/secure/resource

>>>
expect status 200
<<<
```

## AWS Signature v4

Signs requests using AWS Signature Version 4 for authenticating with AWS services or compatible APIs.

```http theme={null}
### AWS signed request
# @name awsRequest
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}

GET https://{{service}}.{{region}}.amazonaws.com/resource

>>>
expect status 200
<<<
```

The parameters are:

1. **Access Key ID** - Your AWS access key
2. **Secret Access Key** - Your AWS secret key
3. **Region** - AWS region (e.g., `us-east-1`)
4. **Service** - AWS service name (e.g., `s3`, `execute-api`)
5. **Session token** (optional) - The token that goes with temporary credentials (STS, SSO, assumed roles)

With a session token, hitspec sends it as `X-Amz-Security-Token` and includes that header in the signature:

```http theme={null}
### AWS request with temporary credentials
# @name awsTemporary
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}, {{sessionToken}}

GET https://{{service}}.{{region}}.amazonaws.com/resource

>>>
expect status 200
<<<
```

If you leave the fifth parameter out and the access key equals `$AWS_ACCESS_KEY_ID`, hitspec uses `$AWS_SESSION_TOKEN` when it is set.

The signature covers the exact bytes that are sent, including a `>>>multipart` body.

## OAuth2 Client Credentials

Automatically fetches an access token using the OAuth2 Client Credentials grant before sending the request.

```http theme={null}
### Access with OAuth2 client credentials
# @name oauth2ClientRequest
# @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2

GET {{baseUrl}}/api/resource

>>>
expect status 200
<<<
```

Parameters in order:

1. **Token URL** - The OAuth2 token endpoint
2. **Client ID** - Your application's client ID
3. **Client Secret** - Your application's client secret
4. **Scopes** - Comma-separated list of scopes (optional)

## OAuth2 Password Grant

Fetches an access token using the OAuth2 Resource Owner Password Credentials grant.

```http theme={null}
### Access with OAuth2 password grant
# @name oauth2PasswordRequest
# @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2

GET {{baseUrl}}/api/resource

>>>
expect status 200
<<<
```

Parameters in order:

1. **Token URL** - The OAuth2 token endpoint
2. **Client ID** - Your application's client ID
3. **Client Secret** - Your application's client secret
4. **Username** - Resource owner's username
5. **Password** - Resource owner's password
6. **Scopes** - Comma-separated list of scopes (optional)

## Using Auth with Captures

A common pattern is to capture a token from a login request and use it in subsequent requests:

```http theme={null}
### Login
# @name login

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

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

>>>
expect status 200
expect body.token exists
<<<

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

### Access protected resource
# @name protected
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<
```

## Auth Syntax Reference

| Method | Syntax |
| - | - |
| Bearer | `# @auth bearer <token>` |
| Basic | `# @auth basic <username>, <password>` |
| API Key (Header) | `# @auth apiKey <headerName>, <value>` |
| API Key (Query) | `# @auth apiKeyQuery <paramName>, <value>` |
| Digest | `# @auth digest <username>, <password>` |
| AWS Signature v4 | `# @auth aws <accessKey>, <secretKey>, <region>, <service>[, <sessionToken>]` |
| OAuth2 Client Credentials | `# @auth oauth2 client_credentials <tokenUrl>, <clientId>, <clientSecret>, <scopes>` |
| OAuth2 Password | `# @auth oauth2 password <tokenUrl>, <clientId>, <clientSecret>, <username>, <password>, <scopes>` |

<Tip>
  All auth parameters support variable interpolation with `{{variableName}}` syntax, so you can store credentials in your environment configuration and keep them out of your test files.
</Tip>


# Contract Testing
Source: https://hitspec.dev/features/contract-testing

Verify API contracts against live providers with hitspec's built-in contract testing support.

Contract testing verifies that an API provider honors the agreements (contracts) defined by its consumers. hitspec supports consumer-driven contract testing using standard `.http` files annotated with contract metadata.

## How It Works

1. Define expected interactions in `.http` files with contract annotations
2. Run `hitspec contract verify` against a live provider
3. hitspec sends each request and validates the response against your assertions

## Contract Annotations

Add contract metadata to your requests using custom annotations:

```http theme={null}
### Get user by ID
# @name getUserById
# @contract.provider UserService
# @contract.state "user exists with id 1"

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id == 1
expect body.name type string
expect body.email type string
<<<
```

| Annotation | Description |
| - | - |
| `@contract.provider` | Name of the provider service |
| `@contract.state` | Provider state that must be set up before the interaction |

## Running Contract Verification

```bash theme={null}
# Verify contracts against a provider
hitspec contract verify contracts/ --provider http://localhost:3000

# With a state handler script
hitspec contract verify contracts/ \
  --provider http://localhost:3000 \
  --state-handler ./setup-states.sh

# Verbose output
hitspec contract verify contracts/ --provider http://localhost:3000 -v
```

## State Handlers

A state handler is an executable script that sets up the provider's state before each interaction. hitspec calls it with the state description as an argument:

```bash theme={null}
#!/bin/bash
# setup-states.sh
case "$1" in
  "user exists with id 1")
    curl -s -X POST http://localhost:3000/test/seed-user -d '{"id": 1, "name": "John"}' > /dev/null
    ;;
  "no users exist")
    curl -s -X POST http://localhost:3000/test/clear-users > /dev/null
    ;;
esac
```

On Windows, a script that is not a `.exe`, `.bat`, `.cmd` or `.com` file runs through `sh` from Git for Windows, so the same `.sh` handler works there when Git is installed.

## CLI Reference

```bash theme={null}
hitspec contract verify <contracts-dir> [flags]
```

| Flag | Short | Description | Required |
| - | - | - | - |
| `--provider` | `-p` | Provider URL | Yes |
| `--state-handler` | | Path to state handler script | No |
| `--verbose` | `-v` | Verbose output | No |

## Example Contract File

```http theme={null}
@baseUrl = {{baseUrl}}

### List all users
# @name listUsers
# @contract.provider UserService

GET {{baseUrl}}/users

>>>
expect status 200
expect body type array
expect body length >= 0
<<<

### Create a user
# @name createUser
# @contract.provider UserService
# @contract.state "database is empty"

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

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

>>>
expect status 201
expect body.id exists
expect body.name == "Jane Doe"
<<<
```

<Tip>
  Keep contract files in a dedicated `contracts/` directory, separate from your integration tests. This makes it clear which tests define API agreements vs. which tests validate behavior.
</Tip>


# Database assertions after HTTP requests
Source: https://hitspec.dev/features/database-assertions

Verify database state after HTTP requests with SQL queries and assertions. Use >>>db blocks to check side effects in PostgreSQL, MySQL, and SQLite.

<Warning>
  Database assertions are an **experimental** feature. The syntax and behavior may change in future releases.
</Warning>

Database assertions let you verify that an HTTP request produced the expected side effects in your database. After sending a request, hitspec runs a SQL query and asserts on the results.

## Security

<Warning>
  Database assertion blocks execute SQL queries against your database. You must pass the `--allow-db` flag to enable them. Without this flag, `>>>db` blocks are skipped.
</Warning>

```bash theme={null}
hitspec run tests/ --allow-db
```

## Basic Usage

Use the `@db` annotation to specify a database connection and a `>>>db` block for queries and assertions:

```http theme={null}
### Create a user and verify in database
# @name createUser
# @db sqlite://./test.db

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

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

>>>
expect status 201
<<<

>>>db
query SELECT COUNT(*) as count FROM users WHERE email = 'jane@example.com'
expect count == 1
<<<
```

## Connection Strings

Specify the database connection using the `@db` annotation:

| Database | Connection String |
| - | - |
| SQLite | `sqlite://./test.db` or `sqlite:./test.db` |
| PostgreSQL | `postgres://user:pass@localhost:5432/dbname` |
| MySQL | `mysql://user:pass@localhost:3306/dbname` |

```http theme={null}
### PostgreSQL example
# @db postgres://testuser:testpass@localhost:5432/testdb

GET {{baseUrl}}/users/1

### MySQL example
# @db mysql://root:password@localhost:3306/myapp

GET {{baseUrl}}/users/1

### SQLite example
# @db sqlite://./test.db

GET {{baseUrl}}/users/1
```

## Query and Assert Syntax

Inside a `>>>db` block, use `query` to run SQL and `expect` to assert on the result columns:

```http theme={null}
>>>db
query SELECT name, email, active FROM users WHERE id = 1
expect name == "Jane Doe"
expect email == "jane@example.com"
expect active == true
<<<
```

### Supported Operators

| Operator | Example | Description |
| - | - | - |
| `==` | `expect count == 5` | Equals |
| `!=` | `expect status != "deleted"` | Not equals |
| `>` | `expect count > 0` | Greater than |
| `>=` | `expect count >= 1` | Greater than or equal |
| `<` | `expect age < 100` | Less than |
| `<=` | `expect score <= 10` | Less than or equal |
| `contains` | `expect name contains "Jane"` | Contains substring |
| `exists` | `expect email exists` | Value is not null |
| `!exists` | `expect deleted_at !exists` | Value is null |

<Note>
  If you omit the operator, hitspec defaults to `==` (exact match). So
  `expect active true` is equivalent to `expect active == true`.
</Note>

## Examples

### Verify Record Creation

```http theme={null}
### Create order
# @name createOrder
# @db postgres://{{dbUser}}:{{dbPass}}@localhost:5432/{{dbName}}

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

{
  "product_id": 42,
  "quantity": 3
}

>>>
expect status 201
expect body.id exists
<<<

>>>capture
orderId from body.id
<<<

>>>db
query SELECT product_id, quantity, status FROM orders WHERE id = {{createOrder.orderId}}
expect product_id == 42
expect quantity == 3
expect status == "pending"
<<<
```

### Verify Record Deletion

```http theme={null}
### Delete user
# @name deleteUser
# @depends createUser
# @db sqlite://./test.db

DELETE {{baseUrl}}/api/users/{{createUser.userId}}

>>>
expect status 204
<<<

>>>db
query SELECT COUNT(*) as count FROM users WHERE id = {{createUser.userId}}
expect count == 0
<<<
```

### Verify Aggregates

```http theme={null}
### Bulk import
# @name bulkImport
# @db postgres://{{dbUser}}:{{dbPass}}@localhost:5432/{{dbName}}

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

{
  "file": "data.csv"
}

>>>
expect status 200
<<<

>>>db
query SELECT COUNT(*) as total FROM imports WHERE batch_id IS NOT NULL
expect total > 0
<<<
```

<Note>
  Variable interpolation works inside `>>>db` blocks. You can use captured values, environment variables, and built-in functions in your SQL queries.
</Note>

<Tip>
  For CI/CD, use environment variables for database credentials and pass the `--allow-db` flag explicitly in your pipeline configuration.
</Tip>


# Hooks
Source: https://hitspec.dev/features/hooks

Run setup and teardown scripts before and after HTTP requests using @before and @after annotations.

Hooks let you run shell scripts before and after individual requests. Use `@before` for setup (seeding data, starting services) and `@after` for cleanup (removing test data, stopping services).

## Security

<Warning>
  Hooks execute shell scripts on your system. You must pass the `--allow-shell` flag to enable them. Without this flag, `@before` and `@after` hooks are skipped.
</Warning>

```bash theme={null}
hitspec run tests/ --allow-shell
```

## Basic Usage

```http theme={null}
### Test with setup and teardown
# @name testWithHooks
# @before ./scripts/setup.sh
# @after ./scripts/cleanup.sh

GET {{baseUrl}}/api/test

>>>
expect status 200
<<<
```

## @before Hooks

`@before` hooks run before the HTTP request is sent. Use them to prepare test data, start services, or set up preconditions.

```http theme={null}
### Test user creation
# @name testCreateUser
# @before ./scripts/seed-db.sh
# @before ./scripts/clear-cache.sh

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

{
  "name": "Test User"
}

>>>
expect status 201
<<<
```

Multiple `@before` hooks execute in the order they are declared.

## @after Hooks

`@after` hooks run after the request completes and assertions are evaluated. They always run, even if the request or assertions fail. This makes them reliable for cleanup.

```http theme={null}
### Test that requires cleanup
# @name testWithCleanup
# @after ./scripts/remove-test-data.sh
# @after ./scripts/reset-state.sh

DELETE {{baseUrl}}/api/test-resources/123

>>>
expect status 204
<<<
```

Multiple `@after` hooks also execute in declaration order.

<Note>
  `@after` hooks always run, even when the request fails or assertions do not pass. This guarantees cleanup happens regardless of test outcome.
</Note>

## Variable Resolution

Variables are resolved in hook paths and commands:

```http theme={null}
### Dynamic hook paths
# @name envSpecificTest
# @before ./scripts/setup-{{env}}.sh
# @after ./scripts/cleanup-{{env}}.sh

GET {{baseUrl}}/api/health

>>>
expect status 200
<<<
```

## Execution Details

| Behavior | Detail |
| - | - |
| Execution engine | `sh -c` (on Windows, `sh` from Git for Windows when it is installed, otherwise `cmd /C`) |
| Working directory | Location of the `.http` file |
| Multiple hooks | Executed in declaration order |
| `@before` failure | Request is not sent; `@after` hooks still run |
| `@after` timing | Always runs, even on request failure |
| Variable support | `{{variables}}` are resolved before execution |

## Example: Database Seed and Cleanup

```http theme={null}
### Verify user list after seeding
# @name verifyUsers
# @before ./scripts/seed-users.sh
# @after ./scripts/truncate-users.sh

GET {{baseUrl}}/api/users

>>>
expect status 200
expect body type array
expect body length > 0
<<<
```

`scripts/seed-users.sh`:

```bash theme={null}
#!/bin/bash
psql $DATABASE_URL -c "INSERT INTO users (name, email) VALUES ('Test', 'test@example.com');"
```

`scripts/truncate-users.sh`:

```bash theme={null}
#!/bin/bash
psql $DATABASE_URL -c "TRUNCATE TABLE users CASCADE;"
```

## Example: Service Health Check

```http theme={null}
### Wait for service and test
# @name serviceTest
# @before ./scripts/start-service.sh
# @after ./scripts/stop-service.sh

GET http://localhost:8080/api/health

>>>
expect status 200
expect body.status == "ok"
<<<
```

<Tip>
  For simple command execution after a request (without needing a separate script file), consider using [shell command blocks](/features/shell-commands) with the `>>>shell` syntax instead.
</Tip>


# Metrics Export
Source: https://hitspec.dev/features/metrics-export

Export test metrics to Prometheus, DataDog, or JSON for monitoring and dashboards.

hitspec can export test execution metrics to external monitoring systems. This is especially useful for stress testing, where you want to track latency, error rates, and throughput over time.

## Supported Formats

| Format | Flag | Description |
| - | - | - |
| Prometheus | `--metrics prometheus` | Exposes metrics on an HTTP endpoint |
| DataDog | `--metrics datadog` | Sends metrics to DataDog API |
| JSON | `--metrics json` | Writes metrics to a file or stdout |

<Note>
  Metrics export is part of stress testing: it exports the summary of a `--stress` run. `--metrics` without `--stress` exports nothing and prints a warning on stderr (`--metrics only applies with --stress`); the run itself is unaffected.
</Note>

## Prometheus

Exposes metrics on an HTTP endpoint (default port 9090) for Prometheus to scrape.

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics prometheus \
  --metrics-port 9090
```

Metrics are available at `http://localhost:9090/metrics` while the test runs, and are updated every second, so a scrape during the run sees the current totals. The JSON and DataDog exporters are written once, when the run ends.

| Flag | Env Var | Default | Description |
| - | - | - | - |
| `--metrics-port` | `HITSPEC_METRICS_PORT` | `9090` | Port for the metrics endpoint |
| `--metrics-host` | `HITSPEC_METRICS_HOST` | `127.0.0.1` | Interface to bind; `0.0.0.0` exposes the endpoint to the network |

The endpoint is bound before the test starts. If the port is already in use, the command prints the error and exits `3` without sending any request.

## DataDog

Sends metrics directly to the DataDog API.

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics datadog \
  --datadog-api-key "$DD_API_KEY"
```

| Flag | Env Var | Default | Description |
| - | - | - | - |
| `--datadog-api-key` | `DD_API_KEY` | | DataDog API key (required) |
| `--datadog-site` | `DD_SITE` | `datadoghq.com` | DataDog site |
| `--datadog-tags` | `DD_TAGS` | | Comma-separated tags |

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics datadog \
  --datadog-api-key "$DD_API_KEY" \
  --datadog-site "datadoghq.eu" \
  --datadog-tags "env:staging,service:api"
```

## JSON

Writes aggregate metrics to a file or stdout.

```bash theme={null}
# Write to file
hitspec run api.http --stress -d 1m -r 50 \
  --metrics json \
  --metrics-file metrics.json

# Write to stdout
hitspec run api.http --stress -d 1m -r 50 \
  --metrics json
```

| Flag | Env Var | Description |
| - | - | - |
| `--metrics-file` | `HITSPEC_METRICS_FILE` | Output file (defaults to stdout) |

## Multiple Exporters

Export to multiple formats simultaneously:

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics prometheus,json \
  --metrics-port 9090 \
  --metrics-file metrics.json
```

## Exported Metrics

The metrics include:

| Metric | Description |
| - | - |
| Total requests | Number of requests sent |
| Success count | Number of successful responses |
| Failure count | Number of failed responses |
| Total duration | Overall test duration |
| Min/Max/Avg latency | Latency statistics |
| P50/P95/P99 latency | Percentile latencies |
| Status codes | Count of responses per HTTP status code (requests that got no response, such as timeouts, are not listed) |
| Per-test breakdown | Metrics for each named request |


# Mock server from .http files
Source: https://hitspec.dev/features/mock-server

Start a mock HTTP server from your .http test files for frontend development and integration testing — no separate mock tool or fixtures to maintain.

<Warning>
  The mock server is an **experimental** feature. The syntax and behavior may change in future releases.
</Warning>

hitspec can start a mock HTTP server that serves responses based on your `.http` test files. This is useful for frontend development, integration testing, and working offline without a live backend.

## Basic Usage

```bash theme={null}
# Start mock server on port 3000
hitspec mock api.http --port 3000

# From a directory of .http files
hitspec mock tests/ --port 8080
```

The mock server reads your test files and creates endpoints that return responses matching the expected assertions.

## How It Works

hitspec inspects the requests defined in your `.http` files and creates one route
per request, matched by **method** and **path** (path variables like
`/users/{{id}}` become wildcards that match any value). When an incoming request
matches a route, the server builds the response from, in order of precedence:

1. **A `>>>mock` block** -- if present, its content is returned verbatim as the response body.
2. **Assertions** -- otherwise the body is inferred from the request's assertions.

In both cases the **status code** comes from `expect status <code>` (default
`200`) and the **Content-Type** is `application/json`.

## Custom Mock Responses

Add a `>>>mock` block to define the exact response body the server should return.
This is the most direct way to mock a response -- including shapes that assertions
can't express, like arrays:

```http theme={null}
### Get user by ID
# @name getUser

GET {{baseUrl}}/users/1

>>>mock
{
  "id": 1,
  "name": "Ada Lovelace",
  "roles": ["admin", "user"]
}
<<<

>>>
expect status 200
<<<
```

A GET request to `/users/1` returns the `>>>mock` body verbatim with status `200`.

<Note>
  The mock body is returned **verbatim** -- `{{variable}}` placeholders are not
  interpolated. The block ends at the first line that begins with `<<<`, so the
  body can contain `>>>`/`<<<` mid-line (for example inside a JSON string).
</Note>

## Inferring the Response from Assertions

If a request has no `>>>mock` block, the server builds the body from its assertions:

* `expect body.<field> == <value>` assertions are assembled into a JSON object of those fields.
* `expect body == <value>` returns that value verbatim as the body.
* With no body assertions, the server returns `{"status": "ok"}`.

For example:

```http theme={null}
### Get a product
# @name getProduct

GET {{baseUrl}}/products/1

>>>
expect status 200
expect body.id == 1
expect body.name == "Mock User"
expect body.email == "mock@example.com"
<<<
```

A GET request to `/products/1` matches this route and returns:

```json theme={null}
{
  "id": 1,
  "name": "Mock User",
  "email": "mock@example.com"
}
```

## Flags

| Flag | Description | Default |
| - | - | - |
| `--port` | Server port | `3000` |
| `--host` | Address to bind (`0.0.0.0` to expose the server) | `127.0.0.1` |
| `--cors` | Answer CORS preflights and add `Access-Control-Allow-*` headers | off |
| `--delay` | Artificial response delay | `0` |

## Network Access

The mock server listens on `127.0.0.1`, so it is reachable only from your own machine. To reach it from another machine, a phone on your network, or a container, bind all interfaces:

```bash theme={null}
hitspec mock api.http --host 0.0.0.0
```

<Warning>
  Binding `0.0.0.0` makes the mock server reachable by anything on the network. When you run it in Docker, pass `--host 0.0.0.0` (and publish the port) or the published port will not connect.
</Warning>

If the port is already taken, `hitspec mock` prints the error and exits non-zero instead of reporting a server that is not running.

## Methods, HEAD and CORS

* A path that exists but not for the request's method gets `405 Method Not Allowed` with an `Allow` header listing the methods it does have. Unknown paths still get `404`.
* `HEAD` is answered from the `GET` route of the same path (status and headers, no body).
* With `--cors`, every response carries `Access-Control-Allow-Origin: *` and friends, and `OPTIONS` preflights are answered with `204`. CORS is off by default.

## Adding Artificial Delay

Simulate network latency with the `--delay` flag:

```bash theme={null}
hitspec mock api.http --port 3000 --delay 100ms
```

This adds a 100ms delay before every response, which is useful for testing loading states in frontend applications.

## Example

Given this test file:

```http theme={null}
@baseUrl = http://localhost:3000

### Get single user
# @name getUser

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id == 1
expect body.name == "Alice"
expect body.email == "alice@example.com"
<<<

### Create user
# @name createUser

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

{
  "name": "Charlie"
}

>>>
expect status 201
expect body.id == 3
expect body.name == "Charlie"
<<<
```

Start the mock server:

```bash theme={null}
hitspec mock api.http --port 3000
```

Then test against it:

```bash theme={null}
curl http://localhost:3000/users/1
# {"id": 1, "name": "Alice", "email": "alice@example.com"}

curl -X POST http://localhost:3000/users -d '{"name":"Charlie"}'
# {"id": 3, "name": "Charlie"}
```

<Tip>
  The mock server is especially useful during frontend development. Point your frontend at the mock server and develop against stable, predictable responses without needing a live backend.
</Tip>


# Multipart and GraphQL
Source: https://hitspec.dev/features/multipart-graphql

Send multipart form data with file uploads and execute GraphQL queries using dedicated block syntax.

hitspec provides dedicated block syntax for multipart form data and GraphQL requests, so you do not need to manually construct complex request bodies.

## Multipart Form Data

Use the `>>>multipart` block to send multipart/form-data requests. This is the standard format for file uploads and mixed form submissions.

```http theme={null}
### Upload a profile photo
# @name uploadPhoto

POST {{baseUrl}}/upload

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

>>>
expect status 200
expect body.uploaded == true
<<<
```

The `Content-Type: multipart/form-data` header is set automatically. Do not set it manually.

### Field Syntax

Each line in a `>>>multipart` block is either a field or a file:

| Type | Syntax | Description |
| - | - | - |
| Text field | `field name = value` | Sends a form text field |
| File upload | `file @./path/to/file` | Uploads a file from disk as the form field `file` |
| Named file upload | `file avatar @./path/to/file` | Uploads a file from disk as the form field `avatar` |

### Naming a File Field

Servers read an uploaded file by its form field name. Put the name before the `@` path; without one the field is called `file`:

```http theme={null}
### Upload an avatar and a CV
POST {{baseUrl}}/profile

>>>multipart
file avatar @./photo.jpg
file cv @./resume.pdf
field name = John Doe
<<<

>>>
expect status 200
<<<
```

The uploaded file name (the `filename` of the part) is the base name of the path. A file that does not exist fails the request with an error naming the path; nothing is sent.

### Multiple Fields and Files

You can include any combination of fields and files:

```http theme={null}
### Submit a report with attachments
# @name submitReport

POST {{baseUrl}}/reports

>>>multipart
field title = Monthly Report
field department = Engineering
field priority = high
file @./report.pdf
file @./data.csv
<<<

>>>
expect status 201
expect body.id exists
<<<
```

### Variable Interpolation

Variables are resolved in both field values and file paths:

```http theme={null}
>>>multipart
field name = {{userName}}
field token = {{authToken}}
file @{{uploadPath}}
<<<
```

<Note>
  File paths in `file @` directives are relative to the `.http` file location.
</Note>

## GraphQL

Use the `>>>graphql` block to write GraphQL queries and mutations. Optionally add a `>>>variables` block for query variables.

### Basic Query

```http theme={null}
### Get all users
# @name getUsers

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

>>>graphql
query {
  users {
    id
    name
    email
  }
}
<<<

>>>
expect status 200
expect body.data.users type array
expect body.errors !exists
<<<
```

### Query with Variables

Use the `>>>variables` block to pass variables to your GraphQL query:

```http theme={null}
### Get user by ID
# @name getUser

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

>>>graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      title
    }
  }
}

>>>variables
{
  "id": "123"
}
<<<

>>>
expect status 200
expect body.data.user.id == "123"
expect body.data.user.name exists
expect body.errors !exists
<<<
```

### Mutations

```http theme={null}
### Create a new user
# @name createUser

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

>>>graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
  }
}

>>>variables
{
  "input": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
}
<<<

>>>
expect status 200
expect body.data.createUser.id exists
expect body.errors !exists
<<<

>>>capture
newUserId from body.data.createUser.id
<<<
```

### Variables with Interpolation

hitspec variables work inside the `>>>variables` block:

```http theme={null}
>>>variables
{
  "id": "{{login.userId}}",
  "limit": {{pageSize}}
}
<<<
```

<Tip>
  hitspec automatically wraps your GraphQL query and variables into the standard JSON format (`{"query": "...", "variables": {...}}`) before sending the request. You only need to set `Content-Type: application/json`.
</Tip>

### Asserting GraphQL Responses

GraphQL responses follow a standard structure. Use JSON path assertions to validate both data and errors:

```http theme={null}
>>>
# Verify the query succeeded
expect status 200
expect body.errors !exists

# Validate response data
expect body.data.users type array
expect body.data.users length > 0
expect body.data.users[0].id exists
expect body.data.users[0].email matches /^.+@.+\..+$/
<<<
```

To test for expected GraphQL errors:

```http theme={null}
>>>
expect status 200
expect body.errors type array
expect body.errors[0].message contains "not found"
<<<
```


# Notifications
Source: https://hitspec.dev/features/notifications

Send test results to Slack and Microsoft Teams via webhooks.

hitspec can send notifications to Slack and Microsoft Teams when tests complete. This is especially useful for CI/CD pipelines to alert teams about test failures.

## Supported Services

| Service | Flag | Webhook Variable |
| - | - | - |
| Slack | `--notify slack` | `SLACK_WEBHOOK` |
| Microsoft Teams | `--notify teams` | `TEAMS_WEBHOOK` |

## Quick Start

```bash theme={null}
# Notify Slack on failure
hitspec run tests/ \
  --notify slack \
  --slack-webhook "$SLACK_WEBHOOK"

# Notify Teams on failure
hitspec run tests/ \
  --notify teams \
  --teams-webhook "$TEAMS_WEBHOOK"
```

## Notification Triggers

Control when notifications are sent with `--notify-on`:

| Value | Description |
| - | - |
| `failure` | Send only when tests fail (default) |
| `always` | Send on every run |
| `success` | Send only when all tests pass |
| `recovery` | Send on failure and when tests recover from a previous failure |

```bash theme={null}
# Always notify
hitspec run tests/ --notify slack --slack-webhook "$SLACK_WEBHOOK" --notify-on always

# Notify on recovery (useful for monitoring)
hitspec run tests/ --notify slack --slack-webhook "$SLACK_WEBHOOK" --notify-on recovery
```

## Slack Configuration

| Flag | Env Var | Description |
| - | - | - |
| `--slack-webhook` | `SLACK_WEBHOOK` | Slack incoming webhook URL (required) |
| `--slack-channel` | `SLACK_CHANNEL` | Override the default channel |

The Slack notification includes:

* Pass/fail summary with test counts
* Duration
* Environment name
* Failed test details (names, files, errors)

## Teams Configuration

| Flag | Env Var | Description |
| - | - | - |
| `--teams-webhook` | `TEAMS_WEBHOOK` | Teams incoming webhook URL (required) |

The Teams notification uses Adaptive Cards and includes the same information as Slack notifications.

## Multiple Services

Send to both Slack and Teams simultaneously:

```bash theme={null}
hitspec run tests/ \
  --notify slack,teams \
  --slack-webhook "$SLACK_WEBHOOK" \
  --teams-webhook "$TEAMS_WEBHOOK"
```

## CI/CD Example

```yaml theme={null}
# GitHub Actions
- name: Run API tests
  run: |
    hitspec run tests/ \
      --env staging \
      --output junit \
      --output-file results.xml \
      --notify slack \
      --notify-on failure
  env:
    SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
```

<Tip>
  Store webhook URLs in environment variables or CI/CD secrets. Never commit them to your repository.
</Tip>


# Parallel Execution
Source: https://hitspec.dev/features/parallel-execution

Run independent API tests concurrently for faster test suites.

Parallel execution runs independent requests concurrently, reducing total test suite time. Requests with dependencies (`@depends`) always run sequentially.

## Enabling Parallel Mode

```bash theme={null}
hitspec run tests/ --parallel
```

Short form:

```bash theme={null}
hitspec run tests/ -p
```

## Concurrency Limit

Control the maximum number of simultaneous requests:

```bash theme={null}
hitspec run tests/ --parallel --concurrency 10
```

| Flag | Default | Description |
| - | - | - |
| `--parallel` | hitspec.yaml `parallel`, else `false` | Enable parallel execution |
| `--concurrency` | hitspec.yaml `concurrency`, else `5` | Maximum concurrent requests |

## Configuration

Set parallel mode in `hitspec.yaml` to avoid passing flags every time:

```yaml theme={null}
parallel: true
concurrency: 10
```

## How Dependencies Work

hitspec respects the dependency graph when running in parallel:

```http theme={null}
### Create user
# @name createUser
POST {{baseUrl}}/users
Content-Type: application/json

{"name": "John"}

>>>capture
userId from body.id
<<<

### Get user (depends on createUser)
# @name getUser
# @depends createUser

GET {{baseUrl}}/users/{{createUser.userId}}

>>>
expect status 200
<<<

### List products (independent)
# @name listProducts

GET {{baseUrl}}/products

>>>
expect status 200
<<<
```

In this example, `listProducts` runs concurrently with `createUser`. But `getUser` waits for `createUser` to complete because of the `@depends` directive.

<Warning>
  Captured variables from parallel requests are not shared. Only use captures across requests connected by `@depends`.
</Warning>

## Environment Variables

| Variable | Flag | Default |
| - | - | - |
| `HITSPEC_PARALLEL` | `--parallel` | hitspec.yaml `parallel`, else `false` |
| `HITSPEC_CONCURRENCY` | `--concurrency` | hitspec.yaml `concurrency`, else `5` |


# Recording Proxy
Source: https://hitspec.dev/features/recording-proxy

Capture HTTP traffic and auto-generate hitspec test files using the recording proxy.

The recording proxy captures HTTP requests and responses flowing through it, then exports them as `.http` files. It is a fast way to bootstrap tests from existing API traffic.

## How It Works

1. Start the proxy pointing at your target server
2. Send requests through the proxy (manually or from your app)
3. Stop the proxy (Ctrl+C)
4. hitspec exports all captured traffic as a `.http` file

## Quick Start

```bash theme={null}
# Start recording proxy
hitspec record --port 8080 --target https://api.example.com

# In another terminal, send requests through the proxy
curl http://localhost:8080/users
curl -X POST http://localhost:8080/users -d '{"name":"John"}'

# Press Ctrl+C to stop and export
```

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--port` | `-p` | Port to run the proxy on | `8080` |
| `--host` | | Address to bind (`0.0.0.0` to expose the proxy) | `127.0.0.1` |
| `--no-redact` | | Keep secrets in the recording instead of redacting them | `false` |
| `--target` | `-t` | Target URL to proxy to (required) | |
| `--output` | `-o` | Output file path (default: stdout) | |
| `--exclude` | | Paths to exclude (comma-separated) | |
| `--verbose` | `-v` | Enable verbose logging | `false` |
| `--dedupe` | | Skip duplicate requests (same method+path) | `false` |
| `--json` | | Export as JSON instead of `.http` format | `false` |

## Examples

<CodeGroup>
  ```bash Basic recording theme={null}
  hitspec record --target https://api.example.com -o recorded.http
  ```

  ```bash Exclude health checks theme={null}
  hitspec record \
    --target https://api.example.com \
    --exclude "/health,/metrics" \
    -o recorded.http
  ```

  ```bash Deduplicate requests theme={null}
  hitspec record \
    --target https://api.example.com \
    --dedupe \
    -o recorded.http
  ```

  ```bash JSON export theme={null}
  hitspec record \
    --target https://api.example.com \
    --json \
    -o recorded.json
  ```
</CodeGroup>

## Network Access

The proxy listens on `127.0.0.1` and forwards to whatever `--target` says, so it is not reachable from the network unless you ask: `--host 0.0.0.0` binds all interfaces. If the port is already in use, `hitspec record` exits `3`.

## What Gets Recorded

The proxy captures:

* HTTP method and full URL, including a path prefix from `--target` (`--target https://api.example.com/v2` records `https://api.example.com/v2/users`)
* Request headers
* Request body
* Response status code, headers and body

Responses are streamed to your client as they arrive, so server-sent events and chunked responses work through the proxy. The recording keeps up to 1 MiB of each body and is stored when the response ends (or the client disconnects).

## What Gets Redacted

Unless you pass `--no-redact`, the proxy replaces secrets with `{{PLACEHOLDER}}` references:

* Headers: `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key` and `Api-Key` (for example `{{AUTHORIZATION}}`)
* JSON fields named `password`, `secret`, `token` or `apiKey` in request and response bodies, including names that end in one of those such as `access_token` or `clientSecret` (the value becomes `"{{ACCESS_TOKEN}}"`)

Define those variables in your environment to replay the recording. Other bodies, such as form data, are recorded as they are.

## Output Format

The exported `.http` file follows standard hitspec format:

```http theme={null}
### GET /users
# @name get_users

GET https://api.example.com/users
Accept: application/json

>>>
expect status == 200
<<<

### POST /users
# @name post_users

POST https://api.example.com/users
Content-Type: application/json

{
  "name": "John"
}

>>>
expect status == 200
<<<
```

<Tip>
  After recording, edit the generated file to add meaningful assertions, replace hardcoded values with variables, and add `@depends` directives for request ordering.
</Tip>


# Shell Commands
Source: https://hitspec.dev/features/shell-commands

Run shell commands after HTTP requests for post-processing, notifications, and custom validation.

Shell command blocks let you run arbitrary shell commands after an HTTP request completes. This is useful for post-processing, triggering external scripts, or performing validation that goes beyond HTTP assertions.

## Security

<Warning>
  Shell command blocks execute arbitrary commands on your system. You must pass the `--allow-shell` flag to enable them. Without this flag, `>>>shell` blocks are skipped.
</Warning>

```bash theme={null}
hitspec run tests/ --allow-shell
```

## Basic Usage

Add a `>>>shell` block after your request and assertions:

```http theme={null}
### Process data
# @name processData

POST {{baseUrl}}/api/process
Content-Type: application/json

{
  "action": "generate-report"
}

>>>
expect status 200
<<<

>>>shell
echo "Processing complete"
./scripts/notify.sh
<<<
```

Shell commands execute after the HTTP assertions have been evaluated.

## Variable Interpolation

Variables are resolved in shell commands before execution. You can use environment variables, captured values, and built-in functions:

```http theme={null}
### Create resource
# @name createResource

POST {{baseUrl}}/api/resources
Content-Type: application/json

{
  "name": "test-resource"
}

>>>
expect status 201
<<<

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

>>>shell
echo "Created resource: {{createResource.resourceId}}"
curl -s {{baseUrl}}/api/resources/{{createResource.resourceId}} | jq .
<<<
```

## Error Handling

By default, if a shell command fails (returns a non-zero exit code), the test fails. Prefix a command with `-` to ignore its exit code:

```http theme={null}
>>>shell
echo "This must succeed"
-rm temp-file-that-may-not-exist.txt
echo "Continues even if rm failed"
<<<
```

| Prefix | Behavior |
| - | - |
| (none) | Fail the test if the command returns non-zero |
| `-` | Ignore the exit code and continue |

## Execution Details

* Commands run via `sh -c`. On Windows they run through `sh` from Git for Windows when it is installed, otherwise through `cmd /C` (where POSIX syntax does not work)
* Working directory is the `.http` file location
* Commands execute sequentially in the order they appear
* Each line is a separate command
* Standard output and standard error are captured

## Examples

### Verify a File Was Created

```http theme={null}
### Export data
# @name exportData

POST {{baseUrl}}/api/export

>>>
expect status 200
<<<

>>>shell
test -f ./output/export.csv
wc -l ./output/export.csv
<<<
```

### Run a Cleanup Script

```http theme={null}
### Integration test
# @name integrationTest

POST {{baseUrl}}/api/test-data
Content-Type: application/json

{
  "seed": true
}

>>>
expect status 200
<<<

>>>shell
./scripts/verify-test-data.sh
-./scripts/cleanup.sh
<<<
```

### Chain with External Tools

```http theme={null}
### Get API response
# @name getResponse

GET {{baseUrl}}/api/data

>>>
expect status 200
<<<

>>>shell
echo '{{getResponse.body}}' | jq '.items | length'
<<<
```

<Note>
  Shell blocks are meant for tasks that cannot be expressed as HTTP assertions. For most validation needs, use the built-in assertion operators instead.
</Note>


# Snapshot testing for API responses
Source: https://hitspec.dev/features/snapshot-testing

Capture API response bodies as baselines and automatically detect regressions with snapshot comparison. Update baselines on purposeful changes.

Snapshot testing captures a response body and saves it to disk. On subsequent runs, hitspec compares the current response against the saved snapshot and reports any differences. This is useful for detecting unexpected changes in API responses.

## How It Works

1. **First run** -- hitspec saves the response body to a snapshot file.
2. **Subsequent runs** -- hitspec compares the current response against the saved snapshot.
3. **Mismatch** -- if the response has changed, the test fails with a diff.
4. **Update** -- use `--update-snapshots` to accept the new response as the baseline.

## Basic Usage

Add the `snapshot` assertion operator in your expect block:

```http theme={null}
### Get user details
# @name getUser

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body snapshot "getUserResponse"
<<<
```

The string `"getUserResponse"` is the snapshot name. It must be unique within the test file.

## Snapshot Files

Snapshots are stored in a `__snapshots__/` directory next to your test file. Each
test file gets a single `<filename>.snap.json` file that holds all of that file's
named snapshots:

```
tests/
  api.http
  __snapshots__/
    api.snap.json
```

So `tests/api.http` stores its snapshots in `tests/__snapshots__/api.snap.json`,
keyed by the snapshot names you give in `expect body snapshot "..."`. Snapshots
group by test file, not one file per snapshot.

In `hitspec studio` and `hitspec serve`, the snapshot file must stay inside the workspace: a `__snapshots__` directory (or snapshot file) that is a symlink pointing outside it fails the assertion instead of being read or written. `hitspec run` follows symlinks as before.

<Tip>
  Commit your `__snapshots__/` directories to version control. This allows your team to review snapshot changes in pull requests and catch unexpected API changes.
</Tip>

## Updating Snapshots

When an API response changes intentionally (new fields, updated values), update the snapshots:

```bash theme={null}
hitspec run tests/ --update-snapshots
```

This overwrites all existing snapshot files with the current responses. Review the changes in your version control diff to confirm they are expected.

## Workflow

A typical snapshot testing workflow:

1. **Write the test** with `expect body snapshot "name"`
2. **Run once** to generate the initial snapshot
3. **Commit** the snapshot file alongside your test
4. **CI runs** compare responses against the committed snapshots
5. **When the API changes**, run `--update-snapshots` locally, review the diff, and commit

## Combining with Other Assertions

Snapshot testing works alongside other assertion operators:

```http theme={null}
>>>
expect status 200
expect body.id exists
expect body.items type array
expect body snapshot "fullResponse"
<<<
```

The snapshot assertion captures the entire response body. Other assertions run independently and can validate specific fields or structure.

<Note>
  Snapshots compare the full response body. If your API returns dynamic values (timestamps, UUIDs, etc.), those will cause snapshot mismatches on every run. Use field-level assertions for dynamic values and reserve snapshots for stable response shapes.
</Note>

## Example: API Regression Detection

```http theme={null}
@baseUrl = https://api.example.com

### List products
# @name listProducts
# @tags regression

GET {{baseUrl}}/products?category=electronics

>>>
expect status 200
expect body type array
expect body length > 0
expect body snapshot "productList"
<<<

### Product detail
# @name productDetail
# @tags regression

GET {{baseUrl}}/products/1

>>>
expect status 200
expect body.id == 1
expect body snapshot "productDetail"
<<<
```

Running these tests in CI will catch any unexpected changes to the product listing or detail endpoints.


# Server-Sent Events (SSE)
Source: https://hitspec.dev/features/sse

Test Server-Sent Events endpoints with hitspec.

hitspec can test Server-Sent Events (SSE) endpoints. SSE is a standard for servers to push real-time updates to clients over a single HTTP connection.

When hitspec detects a `text/event-stream` Content-Type in a response, it automatically parses the SSE events and makes them available in the test results. Events are shown in verbose console output and returned in JSON/API results.

## Basic Usage

Connect to an SSE endpoint and assert on the events received:

```http theme={null}
### Listen to event stream
# @name eventStream

GET {{baseUrl}}/events
Accept: text/event-stream

>>>
expect status 200
expect header Content-Type contains "text/event-stream"
<<<
```

## How It Works

1. hitspec sends the HTTP request normally (the `Accept: text/event-stream` header is set by your test file).
2. The server responds with `Content-Type: text/event-stream` and a body containing SSE-formatted events.
3. hitspec detects the content type and parses the response body into structured events.
4. Each event has optional `id`, `type`, and `data` fields per the SSE specification.
5. Parsed events appear in verbose output and in the JSON/API result under `sseEvents`.

## Configuration

Control how long hitspec listens for events using the `@timeout` directive:

```http theme={null}
### Listen for 5 seconds
# @name longStream
# @timeout 5000

GET {{baseUrl}}/events
Accept: text/event-stream

>>>
expect status 200
<<<
```

## Verbose Output

Run with `--verbose` to see parsed SSE events in the console:

```
  ✓ eventStream (234ms)
    SSE Events: 3 received
      [1] message: hello
      [2] update: {"count":42}
      [3] message: goodbye
```

## Multi-line Data

SSE events with multiple `data:` lines are joined with newlines, per the SSE specification:

```http theme={null}
### Multi-line event data

GET {{baseUrl}}/events
Accept: text/event-stream

>>>
expect status 200
<<<
```

A server response like:

```
data: line one
data: line two
data: line three

```

Produces a single event with `data` equal to `"line one\nline two\nline three"`.


# Load and stress test APIs with hitspec
Source: https://hitspec.dev/features/stress-testing

Load test APIs with hitspec — configurable rate, virtual users, ramp-up, and pass/fail thresholds. No separate tool; export metrics to Prometheus or Datadog.

hitspec includes built-in stress testing. Add `--stress` to your run command and your functional tests become load tests -- no separate tool required.

## Quick Start

```bash theme={null}
# Send 100 requests per second for 1 minute
hitspec run api.http --stress --duration 1m --rate 100
```

## Two Modes

### Rate Mode

Controls throughput by setting a target number of requests per second:

```bash theme={null}
hitspec run api.http --stress --duration 1m --rate 50
```

### Virtual Users (VU) Mode

Simulates concurrent users, each making sequential requests with optional think time between them:

```bash theme={null}
hitspec run api.http --stress --duration 2m --vus 50 --think-time 1s
```

## Ramp-Up

Gradually increase load instead of starting at full capacity:

```bash theme={null}
hitspec run api.http --stress --duration 5m --rate 200 --ramp-up 30s
```

This linearly increases the request rate from 0 to 200 over the first 30 seconds, then holds at 200 for the remaining duration.

## Thresholds

Set pass/fail criteria for CI/CD pipelines. If any threshold is exceeded, the command exits with a non-zero code:

```bash theme={null}
hitspec run api.http --stress -d 1m -r 100 --threshold "p95<200ms,errors<0.1%"
```

Available threshold metrics:

| Metric | Example | Description |
| - | - | - |
| `p50` | `p50<100ms` | Median response time |
| `p95` | `p95<200ms` | 95th percentile response time |
| `p99` | `p99<500ms` | 99th percentile response time |
| `max` | `max<2s` | Slowest response time |
| `errors` | `errors<0.1%` | Error rate: transport errors and non-2xx responses. Assertion failures are not counted here. `errors<0` (or `0%`) means no request may fail |
| `assertions` | `assertions<1%` | Share of checked responses that failed an assertion. `assertions<0%` means no assertion may fail |
| `rps` | `rps>50` | Minimum throughput in completed requests per second (uses `>` or `>=`) |

### Thresholds in profiles

In a `hitspec.yaml` stress profile, a threshold value may start with an operator: `p95: "<=250ms"`, `rps: ">=100"`, `errors: "<=0"`. Without one, latency, error and assertion thresholds mean "less than" and `rps` means "greater than". Quote values that start with an operator.

```yaml theme={null}
stress:
  profiles:
    gate:
      duration: 1m
      rate: 100
      thresholds:
        p95: "<=250ms"
        rps: ">=95"
        errors: "0%"
```

## Assertions, Errors and Incomplete Requests

Requests that have `expect` assertions are checked in stress mode too. The results are kept apart so each threshold means one thing:

* **Errors** (`errors<...`) are requests that failed in transport (connection refused, a client timeout, ...) or came back with a non-2xx status. A non-2xx status that the request's own `expect status` accepts (`expect status 404` and the response is a 404) is expected, so it is not an error.
* **Assertion failures** (`assertions<...`) are responses where at least one `expect` did not hold. A `200` whose body assertion fails is a success for `errors` and a failure for `assertions`. The summary prints `Assertions: N checked, M failed`, and `--stress-json` reports `checked`, `failed` and `failureRate`. `snapshot` assertions are skipped under load.
* **Incomplete** requests were still in flight when the duration ended. They are reported on their own line and are not counted as requests, successes or errors, so a slow tail at the end of the window no longer inflates your error rate.

<Warning>
  A run that falls more than 10% short of its target `--rate` prints a warning. When the server (or `--max-vus`) cannot keep up, the test sends less load than you asked for and the latencies understate what clients arriving on schedule would see, so do not read them as "the server handled N req/s".
</Warning>

You can also assert on percentile latencies in your expect blocks:

```http theme={null}
>>>
expect p95 < 200
expect p99 < 500
<<<
```

## Stress Testing Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--stress` | | Enable stress testing mode | `false` |
| `--duration` | `-d` | Test duration (e.g., `30s`, `2m`, `1h`) | `30s` |
| `--rate` | `-r` | Target requests per second | `10` |
| `--vus` | | Number of virtual users | |
| `--max-vus` | | Maximum concurrent requests | `100` |
| `--think-time` | | Delay between requests per VU | |
| `--ramp-up` | | Time to reach target rate/VUs | |
| `--threshold` | | Pass/fail thresholds | |
| `--profile` | | Load stress profile from config file | |
| `--no-progress` | | Disable real-time progress display | `false` |
| `--stress-json` | | Output stress results as JSON | `false` |

## Per-Request Annotations

Control how individual requests behave during stress tests:

```http theme={null}
### Main API endpoint
# @name apiCall
# @stress.weight 10
# @stress.think 500

GET {{baseUrl}}/api/data

>>>
expect status 200
<<<
```

### Available Annotations

| Annotation | Description |
| - | - |
| `@stress.weight <n>` | Relative weight for request selection. Higher weight means more frequent execution. |
| `@stress.think <ms>` | Per-request think time in milliseconds (e.g., `500`, `2000`). |
| `@stress.skip` | Exclude this request from stress testing. |
| `@stress.setup` | Run this request once before the stress test starts. |
| `@stress.teardown` | Run this request once after the stress test ends. |

### Setup and Teardown

Use `@stress.setup` and `@stress.teardown` for one-time operations:

```http theme={null}
### Initialize test data (runs once before stress test)
# @name setup
# @stress.setup

POST {{baseUrl}}/api/init
Content-Type: application/json

{"seed": true}

>>>
expect status 200
<<<

>>>capture
testToken from body.token
<<<

### Main request (repeated during stress test)
# @name mainRequest
# @stress.weight 10

GET {{baseUrl}}/api/data
Authorization: Bearer {{setup.testToken}}

>>>
expect status 200
<<<

### Clean up (runs once after stress test)
# @name teardown
# @stress.teardown

POST {{baseUrl}}/api/cleanup

>>>
expect status 200
<<<
```

## Stress Profiles

Define reusable stress configurations in `hitspec.yaml`:

```yaml theme={null}
stress:
  profiles:
    smoke:
      duration: 30s
      rate: 10
      maxVUs: 5
    load:
      duration: 5m
      rate: 100
      maxVUs: 50
      rampUp: 30s
    spike:
      duration: 10m
      vus: 200
      thinkTime: 1s
      thresholds:
        p95: 500ms
        errors: 1%
    conservative:
      duration: 60s
      rate: 1.5
      maxVUs: 2
```

Run a profile:

```bash theme={null}
hitspec run api.http --stress --profile load --env staging
```

A flag you pass on the command line overrides the profile, even when it equals the flag's default (`--rate 10` wins over a profile's `rate: 100`). Settings you do not pass come from the profile.

### Using Profiles from studio

The [hitspec studio](/guides/api-client-manager) stress screen runs a saved profile by name. Type it in the `profile` field and start the test: the profile's duration, rate, VUs and thresholds apply, and any other field you fill in overrides it. The idle screen lists the profiles saved in `hitspec.yaml`. The desktop app can also create, edit, and delete profiles; changes are persisted to `hitspec.yaml` automatically.

## Results Panel

After a stress test completes (either naturally or via stop), studio displays a results view with:

* **Summary cards** -- Total requests, average RPS, success rate, and error count
* **Latency percentiles** -- Min, P50, P95, P99, Max, Mean, and Standard Deviation (all in fractional milliseconds)
* **Per-request breakdown** -- A table showing each request's count, success/error split, and individual latency metrics (avg, min, max, P50, P95, P99)
* **Threshold indicators** -- Pass/fail badges for each configured threshold

Click **Run Again** to return to the configuration view and start another test.

The results are also available programmatically via the [`GET /api/v1/stress/result`](/reference/rest-api#get-stress-test-result) endpoint.

## Testing Directories and Multiple Files

Stress testing works with directories and multiple files:

```bash theme={null}
# All files in a directory
hitspec run tests/ --stress --duration 1m --rate 100

# Multiple specific files
hitspec run api.http users.http --stress -d 1m -r 100
```

## Understanding Rate Limits

Your server may have its own rate limits. High failure rates often indicate you are exceeding them.

| Server Limit | Equivalent | Safe `--rate` value |
| - | - | - |
| 100 req/min | \~1.67 req/s | `--rate 1.5` |
| 600 req/min | 10 req/s | `--rate 8` |
| 1000 req/min | \~16.7 req/s | `--rate 15` |

<Tip>
  Start with a low rate and increase gradually. If you see high failure rates (above 10%), reduce `--rate` and `--max-vus`. Exactly N successes in 60 seconds often reveals a server-side rate limit of N req/min.
</Tip>

## CI/CD Integration

Use stress testing in GitHub Actions with thresholds:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: api.http
    stress: true
    duration: 2m
    rate: 100
    threshold: 'p95<200ms,errors<0.5%'
```

## Metrics Export

Export stress test metrics to monitoring systems:

```bash theme={null}
# Prometheus endpoint (updated every second while the test runs)
hitspec run api.http --stress --metrics prometheus --metrics-port 9090

# JSON file
hitspec run api.http --stress --metrics json --metrics-file metrics.json

# DataDog
hitspec run api.http --stress --metrics datadog --datadog-api-key $DD_API_KEY
```

See the [CI/CD integration guide](/integrations/github-actions) for more details.


# TLS, cookies and HTTP options
Source: https://hitspec.dev/features/tls-and-cookies

Trust a private CA, present a client certificate, turn off HTTP/2, keep cookies between requests, bound response size and control redirect headers.

These options control how hitspec's HTTP client behaves for a whole run. Each one is a `hitspec run` flag, a `HITSPEC_*` environment variable and a `hitspec.yaml` key; the same keys apply when the client is driven by `hitspec studio`, `hitspec serve`, `--stress` and `hitspec contract`.

Precedence is the usual one: flag, then environment variable, then `hitspec.yaml`, then the default.

| Setting | Flag | Environment variable | `hitspec.yaml` | Default |
| - | - | - | - | - |
| Extra CA bundle | `--cacert <pem>` | `HITSPEC_CACERT` | `cacert` | system roots only |
| Client certificate | `--cert <pem>` | `HITSPEC_CERT` | `cert` | none |
| Client key | `--key <pem>` | `HITSPEC_KEY` | `key` | none |
| Disable HTTP/2 | `--http1.1` | `HITSPEC_HTTP1` | `http1: true` | HTTP/2 over TLS |
| Cookie jar | `--cookies` | `HITSPEC_COOKIES` | `cookies: true` | off |
| Response size limit | `--max-response-bytes <n>` | `HITSPEC_MAX_RESPONSE_BYTES` | `maxResponseBytes` | 104857600 (100 MiB) |
| Keep headers on cross-origin redirects | `--redirect-forward-headers` | `HITSPEC_REDIRECT_FORWARD_HEADERS` | `redirectForwardHeaders: true` | off |

## Private CAs

`--cacert` adds a PEM bundle to the system roots, so an API served with a company or test CA is verified instead of being run with `--insecure`.

```bash theme={null}
hitspec run api.http --cacert ./certs/ca.pem
```

## Mutual TLS

Give both halves of the client certificate:

```bash theme={null}
hitspec run api.http --cacert ./certs/ca.pem --cert ./certs/client.pem --key ./certs/client-key.pem
```

A certificate without a key (or the reverse), or a file that is missing or is not valid PEM, stops the run before any request is sent. hitspec prints the error, naming the file, and exits with code 3.

## In hitspec.yaml

```yaml theme={null}
cacert: certs/ca.pem
cert: certs/client.pem
key: certs/client-key.pem
http1: false
cookies: true
maxResponseBytes: 5242880
redirectForwardHeaders: false
```

Relative paths for `cacert`, `cert` and `key` are resolved against the directory of the `hitspec.yaml` they are written in, not the directory you run hitspec from. Paths given as flags or environment variables are relative to the working directory.

## HTTP/1.1 only

By default hitspec negotiates HTTP/2 over TLS. `--http1.1` turns that off, which helps when a proxy or server misbehaves on HTTP/2 or when you want to reproduce an HTTP/1.1 client.

```bash theme={null}
hitspec run api.http --http1.1
```

## Cookies

Cookies are off by default: a `Set-Cookie` response header is not sent back on later requests. `--cookies` gives the run a cookie jar, so a login request can start a session that the requests after it use. The jar is shared by every file in the run and starts empty each time you run hitspec. With `--watch` the same jar is kept across re-runs, so a session started by one run is still there in the next.

```http theme={null}
### Log in
# @name login
POST {{baseUrl}}/login
Content-Type: application/json

{"user": "alice", "password": "{{password}}"}

>>>
expect status 200
<<<

### Read the session
GET {{baseUrl}}/me

>>>
expect status 200
expect body.user == "alice"
<<<
```

```bash theme={null}
hitspec run session.http --cookies
```

Turn it back off for one run with `--cookies=false` when `hitspec.yaml` enables it.

## Response size limit

A response body larger than 100 MiB fails the request. `--max-response-bytes` changes the limit; `-1` removes it. The limit applies to the bytes on the wire and to the decoded size of a gzip or deflate response.

```bash theme={null}
hitspec run api.http --max-response-bytes 1048576
```

## Redirects and your headers

When a redirect goes to a different origin (scheme, host or port), hitspec drops the headers you set on the request, such as API keys and `Authorization`, so they are not leaked to another site. Content negotiation headers (`Accept`, `Content-Type`, `User-Agent`, ...) are kept. `--redirect-forward-headers` keeps all of them; use it only for redirects you trust.


# Watch Mode
Source: https://hitspec.dev/features/watch-mode

Automatically re-run tests when files change during development.

Watch mode monitors your `.http` and `.hitspec` files for changes and automatically re-runs tests when a file is saved. This creates a fast feedback loop during API development.

## Usage

```bash theme={null}
hitspec run tests/ --watch
```

Short form:

```bash theme={null}
hitspec run tests/ -w
```

## How It Works

1. hitspec runs all matching tests once
2. It then watches the directories containing your test files
3. When a `.http` or `.hitspec` file is modified, tests re-run automatically
4. Press `Ctrl+C` to stop watching (exit code `130`)

## Combining with Filters

Combine watch mode with filters for focused development:

```bash theme={null}
# Watch only smoke tests
hitspec run tests/ --watch --tags smoke

# Watch and filter by name
hitspec run tests/ --watch --name "createUser"

# Watch with a specific environment
hitspec run tests/ --watch --env dev
```

## Debouncing

hitspec debounces file change events with a 300ms delay. Rapid consecutive saves (e.g., from auto-formatting) only trigger a single test re-run.

## Output in Watch Mode

Each re-run creates fresh output. For structured formats (JSON, JUnit), the formatter is re-initialized on each change so you always get complete, valid output.

```bash theme={null}
# Watch with JSON output
hitspec run tests/ --watch --output json
```

With `--output-file`, the file is truncated and rewritten on every re-run, so it always holds exactly one complete report from the latest run (not the reports of all runs appended together).

The `Watching for changes...` and `File changed` lines are written to stderr. Stdout carries only the reports, so you can pipe or redirect it without the banners:

```bash theme={null}
hitspec run tests/ --watch --output json 2>/dev/null
```

In watch mode, filters that match no request print `no requests matched ...` to stderr on every run, but watch mode keeps running instead of exiting.

## Config and Environment Changes

Watch mode also re-runs when `hitspec.yaml` (or the file given with `--config`) or the file given with `--env-file` changes. The settings are reloaded before the next pass, so a new timeout, proxy or variable takes effect without restarting. A new `.http` file in a watched directory is picked up too. The directories `node_modules`, `vendor` and `.git` are not watched. Editors that save by renaming a temp file over the original are handled.

An edited `.env` file takes effect on the next pass: values it exported are refreshed, or unset when the file no longer defines them. Variables you set in the shell are never overwritten. With `--cookies`, the cookie jar is kept across re-runs. Ctrl+C stops watching and exits with code `130`.


# hitspec studio
Source: https://hitspec.dev/guides/api-client-manager

Use the interactive terminal app to build, run, and debug HTTP requests

hitspec studio is a keyboard-first interactive terminal app for working with hitspec files. It uses the same parser, runner, history store, stress engine, mock server, recorder, and import/export code as the CLI.

<Tip>
  studio edits normal `.http` / `.hitspec` files on disk. There is no separate project format, and saved files stay version-control friendly.
</Tip>

## Start the app

```bash theme={null}
hitspec studio
hitspec studio ./tests/api/
hitspec studio ./tests/api/users.http
```

It runs directly in the terminal — no browser, no port. When you need the REST/WebSocket API for integrations, use the server instead:

```bash theme={null}
hitspec serve --api-only --port 4000 --cors
```

## Keyboard Workflow

| Key | Action |
| - | - |
| `Ctrl+P` | Open the command palette |
| `1` - `9` | Navigate between screens |
| `Tab` / `Shift+Tab` | Move focus between panes |
| `Enter` | Open the selected file or command |
| `e` | Edit the active file inline |
| `Ctrl+S` | Save source changes |
| `r` | Run the selected request |
| `R` | Run every request in the file |
| `Ctrl+R` | Refresh workspace data |
| `?` | Toggle expanded help |
| `q` | Quit |

## Workspace

The workspace screen is compact and responsive:

* File list with search/filter from the Bubbles list component
* Parsed request table with method and URL
* Inline source editor powered by Bubbles textarea
* Response viewport with body, errors, timings, and assertion status
* Headers and assertions tables
* Bottom status bar with environment, progress, and help

Wide terminals show file, source, and response panes together. Medium terminals keep the file list plus one main pane. Narrow terminals switch to a single-pane tabbed workflow through focus changes.

## Secondary Screens

studio maps the former manager routes to terminal screens:

* **Stress**: quick-start load tests, saved `hitspec.yaml` profiles by name, and live RPS/error/latency metrics
* **Mock**: start/stop the mock server and inspect registered routes
* **Contract**: verify selected contract files against a provider URL
* **Record**: start/stop the recording proxy, inspect captured traffic, and export recordings
* **History**: browse persistent SQLite-backed runs and request results
* **Import**: convert cURL, Insomnia, OpenAPI, and Postman input into hitspec content
* **Cookies**: inspect the local cookie store captured from responses; cookies are not injected automatically
* **Settings**: edit config and environment values that persist to `hitspec.yaml`

## API-Only Mode

`hitspec serve --api-only` keeps the REST API and WebSocket endpoints for scripts and integrations. The web SPA is no longer served; non-API browser routes are not part of `serve`.

```bash theme={null}
hitspec serve --api-only --host localhost --port 4000
```

The API remains under `/api/v1/*`, with realtime events at `/api/v1/ws`.


# CI/CD Pipeline Integration
Source: https://hitspec.dev/guides/ci-cd-pipeline

Set up hitspec in GitHub Actions, GitLab CI, and other CI/CD systems.

hitspec integrates with any CI/CD system. This guide covers common patterns for automated API testing.

## GitHub Actions

```yaml theme={null}
name: API Tests
on: [push, pull_request]

permissions:
  contents: read
  checks: write

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install hitspec
        run: |
          curl -fsSL https://hitspec.dev/install.sh | sh
          echo "$HOME/.hitspec/bin" >> $GITHUB_PATH

      - name: Run API tests
        run: |
          hitspec run tests/ \
            --env staging \
            --output junit \
            --output-file results.xml \
            --bail
        env:
          HITSPEC_ENV: staging

      - name: Publish Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: ${{ !cancelled() }}
        with:
          files: results.xml
          comment_mode: off

      - name: Notify on failure
        if: failure()
        run: |
          hitspec run tests/ \
            --notify slack \
            --notify-on failure
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
```

## GitLab CI

```yaml theme={null}
api-tests:
  stage: test
  script:
    - curl -fsSL https://hitspec.dev/install.sh | sh
    - hitspec run tests/ --env staging --output junit --output-file results.xml
  artifacts:
    when: always
    reports:
      junit: results.xml
  variables:
    HITSPEC_ENV: staging
```

## General CI/CD Tips

### Exit Codes

hitspec uses standard exit codes. See [Exit Codes](/reference/exit-codes) for the full list.

* `0` -- all tests passed
* `1` -- one or more tests failed
* `2` -- a file could not be loaded (parse error)
* `3` -- config error
* `4` -- network error: the API could not be reached (a request got no response)
* `64` -- usage error (unknown flag, bad value, missing argument), or `--name`/`--tags` matched no request
* `130` -- interrupted (Ctrl+C or SIGTERM)

A step that only expects `0` or `1` must also handle `4`.

### Recommended Flags

| Flag | Why |
| - | - |
| `--output junit` | Machine-readable results for CI reporting |
| `--output-file results.xml` | Write to a file for artifact upload |
| `--bail` | Fail fast on first error |
| `--no-color` | Clean output in CI logs |
| `--env staging` | Target the correct environment |

### Environment Variables

Store sensitive values as CI/CD secrets:

```bash theme={null}
export HITSPEC_ENV=staging
export API_TOKEN=${{ secrets.API_TOKEN }}
export SLACK_WEBHOOK=${{ secrets.SLACK_WEBHOOK }}
```

### Parallel Testing in CI

```bash theme={null}
hitspec run tests/ --parallel --concurrency 10 --env staging
```

<Tip>
  Use `--output json --output-file results.json` to generate output compatible with `hitspec diff` for regression detection between builds.
</Tip>


# Contract Testing Guide
Source: https://hitspec.dev/guides/contract-testing

Step-by-step guide to consumer-driven contract testing with hitspec.

This guide walks through setting up contract testing with hitspec from scratch.

## What is Contract Testing?

Contract testing verifies that an API provider honors the agreements made with its consumers. Instead of running full integration tests, you define the expected interactions and verify them independently.

## Step 1: Define Contracts

Create a `contracts/` directory and define expected interactions:

```http theme={null}
# contracts/user-service.http
@baseUrl = {{baseUrl}}

### Get user by ID
# @name getUserById
# @contract.provider UserService
# @contract.state "user with id 1 exists"

GET {{baseUrl}}/users/1

>>>
expect status 200
expect body.id == 1
expect body.name type string
expect body.email type string
<<<

### Create user
# @name createUser
# @contract.provider UserService
# @contract.state "database is empty"

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

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

>>>
expect status 201
expect body.id exists
expect body.name == "Jane Doe"
<<<
```

## Step 2: Create a State Handler (Optional)

If your contracts specify `@contract.state`, create a script that sets up those states:

```bash theme={null}
#!/bin/bash
# setup-states.sh
case "$1" in
  "user with id 1 exists")
    curl -s -X POST http://localhost:3000/test/seed \
      -d '{"table":"users","data":{"id":1,"name":"John","email":"john@example.com"}}' \
      > /dev/null
    ;;
  "database is empty")
    curl -s -X POST http://localhost:3000/test/reset > /dev/null
    ;;
esac
```

Make it executable: `chmod +x setup-states.sh`

## Step 3: Verify Contracts

```bash theme={null}
hitspec contract verify contracts/ \
  --provider http://localhost:3000 \
  --state-handler ./setup-states.sh \
  -v
```

## Step 4: CI/CD Integration

Run contract verification as part of the provider's CI pipeline:

```yaml theme={null}
contract-test:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v6
    - name: Start provider
      run: docker compose up -d
    - name: Wait for health
      run: timeout 30 bash -c 'until curl -s localhost:3000/health; do sleep 1; done'
    - name: Verify contracts
      run: |
        hitspec contract verify contracts/ \
          --provider http://localhost:3000 \
          --state-handler ./setup-states.sh
```

## Best Practices

1. **Keep contracts minimal** -- only assert on fields your consumer actually uses
2. **Use a dedicated directory** -- separate contracts from integration tests
3. **Version your contracts** -- treat them as API documentation
4. **Run on both sides** -- consumers generate contracts, providers verify them
5. **Use state handlers** -- ensure reproducible provider states for each interaction


# Database Testing Guide
Source: https://hitspec.dev/guides/database-testing

Use database assertions to verify side effects of API calls against PostgreSQL, MySQL, and SQLite.

Database assertions let you verify that API calls produce the expected side effects in your database. After sending a request, query the database and assert on the results.

## Supported Databases

| Database | Connection String |
| - | - |
| SQLite | `sqlite://path/to/db.sqlite` or `sqlite:./test.db` |
| PostgreSQL | `postgres://user:pass@host:port/dbname` |
| MySQL | `mysql://user:pass@host:port/dbname` |

## Security

Database assertions are disabled by default. Enable them with `--allow-db`:

```bash theme={null}
hitspec run tests/ --allow-db
```

<Warning>
  The `--allow-db` flag is required for security. Database blocks execute arbitrary SQL queries, so you must explicitly opt in.
</Warning>

## Syntax

Set the connection with a `# @db` directive on the request, then use a `>>>db` block after it: the SQL query first, then `expect <column> <operator> <value>` lines checked against the first row of the result:

```http theme={null}
### Create user
# @db sqlite:./test.db
POST {{baseUrl}}/users
Content-Type: application/json

{"name": "John", "email": "john@example.com"}

>>>
expect status 201
<<<

>>>db
SELECT COUNT(*) AS count, name, email FROM users WHERE email = 'john@example.com'
expect count == 1
expect name == "John"
expect email == "john@example.com"
<<<
```

## Connection Strings

### SQLite

```
sqlite://./test.db
sqlite:./relative/path.db
sqlite:///absolute/path.db
```

### PostgreSQL

```
postgres://username:password@localhost:5432/mydb
postgres://username:password@localhost:5432/mydb?sslmode=disable
```

### MySQL

```
mysql://username:password@localhost:3306/mydb
```

## Use Cases

### Verify record creation

```http theme={null}
# @db {{dbUrl}}
POST {{baseUrl}}/orders
Content-Type: application/json

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

>>>
expect status 201
<<<

>>>db
SELECT COUNT(*) as count FROM orders WHERE product = 'Widget'
expect count == 1
<<<
```

### Verify cascade deletes

```http theme={null}
# @db {{dbUrl}}
DELETE {{baseUrl}}/users/1

>>>
expect status 204
<<<

>>>db
SELECT COUNT(*) as count FROM user_sessions WHERE user_id = 1
expect count == 0
<<<
```

### Verify data transformation

```http theme={null}
# @db {{dbUrl}}
PUT {{baseUrl}}/users/1
Content-Type: application/json

{"name": "  John Doe  "}

>>>
expect status 200
<<<

>>>db
SELECT name FROM users WHERE id = 1
expect name == "John Doe"
<<<
```

<Tip>
  Store database connection strings in environment variables: `@dbUrl = {{$env(DATABASE_URL)}}`. This keeps credentials out of test files and lets you target different databases per environment.
</Tip>


# Load Testing Guide
Source: https://hitspec.dev/guides/load-testing

Run stress tests with hitspec to validate API performance under load.

hitspec includes a built-in stress testing engine. Use the same `.http` files you write for functional tests to run load tests -- no separate tool needed.

## Quick Start

```bash theme={null}
# Rate-based: 100 requests/second for 1 minute
hitspec run api.http --stress --duration 1m --rate 100

# Virtual user mode: 50 concurrent users for 2 minutes
hitspec run api.http --stress --vus 50 --duration 2m --think-time 1s
```

## Two Modes

### Rate Mode (default)

Sends requests at a fixed rate (requests per second):

```bash theme={null}
hitspec run api.http --stress -d 1m -r 100
```

### Virtual User Mode

Simulates concurrent users, each sending requests sequentially with optional think time:

```bash theme={null}
hitspec run api.http --stress --vus 50 --think-time 500ms --duration 2m
```

## Ramp-Up

Gradually increase load instead of starting at full capacity:

```bash theme={null}
hitspec run api.http --stress -d 5m -r 200 --ramp-up 30s
```

This takes 30 seconds to ramp from 0 to 200 req/s, then sustains 200 req/s for the remaining 4m30s.

## Thresholds

Set pass/fail criteria based on performance metrics:

```bash theme={null}
hitspec run api.http --stress -d 1m -r 100 \
  --threshold "p95<200ms,errors<0.1%"
```

If any threshold is exceeded, hitspec exits with code `1`.

Available threshold metrics:

* `p50` -- 50th percentile latency
* `p95` -- 95th percentile latency
* `p99` -- 99th percentile latency
* `errors` -- Error rate percentage (transport errors and non-2xx responses; assertion failures are not counted)
* `assertions` -- Share of checked responses that failed an `expect` assertion (`assertions<0%` means none may fail)

Requests still in flight when the duration ends are reported as "incomplete" and do not count as errors. If the run cannot reach its target `--rate` (more than 10% short), hitspec prints a warning, because the latencies then understate real load. See [Load and stress test APIs](/features/stress-testing#assertions-errors-and-incomplete-requests).

## Stress Profiles

Define reusable profiles in `hitspec.yaml`:

```yaml theme={null}
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"
```

Use a profile:

```bash theme={null}
hitspec run api.http --stress --profile load --env staging
```

CLI flags override profile values.

## Multiple Files

Stress test across multiple files:

```bash theme={null}
hitspec run users.http orders.http --stress -d 1m -r 50
```

Or an entire directory:

```bash theme={null}
hitspec run ./tests/ --stress -d 1m -r 50
```

## Output

### Real-time Progress

By default, hitspec shows a live progress bar with current RPS, latency, and error count. Disable with `--no-progress`.

### JSON Output

```bash theme={null}
hitspec run api.http --stress -d 1m -r 100 --stress-json
```

### Metrics Export

Export to Prometheus, DataDog, or JSON for dashboards:

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics prometheus --metrics-port 9090
```

See [Metrics Export](/features/metrics-export) for details.

## CI/CD Integration

```bash theme={null}
hitspec run api.http --stress -d 1m -r 100 \
  --threshold "p95<200ms,errors<1%" \
  --env staging \
  --stress-json > stress-results.json
```

The exit code indicates whether thresholds passed:

* `0` -- all thresholds met
* `1` -- one or more thresholds exceeded


# Migrate from Postman to hitspec .http tests
Source: https://hitspec.dev/guides/migrating-from-postman

Import Postman collections into hitspec and convert them to plain-text .http files. Covers the import process and the key differences from Postman.

hitspec can import Postman collections and convert them to `.http` files. This guide covers the import process and key differences.

## Importing a Collection

Export your Postman collection as JSON (Collection v2.1), then import:

```bash theme={null}
hitspec import postman collection.json -o tests/api.http
```

This converts all requests in the collection, including folders, headers, and bodies.

## What Gets Converted

| Postman Feature | hitspec Equivalent |
| - | - |
| Request method + URL | `GET {{baseUrl}}/path` |
| Headers | Headers below the request line |
| Body (raw JSON) | JSON body block |
| Body (form-urlencoded) | URL-encoded body |
| Folders | Request sections with `###` separators |
| Collection variables `{{var}}` | `{{var}}` (same syntax) |
| Dynamic variables `{{$guid}}` | `{{$uuid()}}` |
| Dynamic variables `{{$timestamp}}` | `{{$timestamp()}}` |
| Dynamic variables `{{$randomInt}}` | `{{$random(0, 1000)}}` |
| Dynamic variables `{{$randomEmail}}` | `{{$randomEmail()}}` |
| Collection variables | `@name = value` lines |
| Environment export | `hitspec.yaml` environments (use `--config`) |
| Bearer/Basic/API key auth | `# @auth ...` (collection, folder, request) |
| `pm.test` status/body/header checks | `expect ...` lines; the rest as `# TODO: untranslated test` |
| form-data / GraphQL / file bodies | `>>>multipart` / `>>>graphql` / `< ./file` |

## Other Import Formats

hitspec also imports from:

### OpenAPI / Swagger

```bash theme={null}
hitspec import openapi spec.yaml -o tests/api.http
hitspec import openapi https://api.example.com/openapi.json -o tests/
hitspec import openapi spec.yaml --tags users,auth --base-url http://localhost:3000
```

### curl Commands

```bash theme={null}
hitspec import curl "curl -X POST https://api.example.com -d '{\"name\":\"John\"}'"
hitspec import curl @commands.txt -o tests/api.http
```

### Insomnia

```bash theme={null}
hitspec import insomnia export.json -o tests/api.http
```

## Key Differences from Postman

### Test Syntax

<Tabs>
  <Tab title="Postman (JavaScript)">
    ```javascript theme={null}
    pm.test("Status is 200", function() {
      pm.response.to.have.status(200);
    });

    pm.test("Has user ID", function() {
      var json = pm.response.json();
      pm.expect(json.id).to.exist;
    });
    ```
  </Tab>

  <Tab title="hitspec (declarative)">
    ```http theme={null}
    >>>
    expect status 200
    expect body.id exists
    <<<
    ```
  </Tab>
</Tabs>

### Variables

| Postman | hitspec |
| - | - |
| Collection variables | `@variable = value` in file |
| Environment variables | `hitspec.yaml` environments |
| `{{$guid}}` | `{{$uuid()}}` |
| `pm.environment.set("key", val)` | `>>>capture` blocks |

### Authentication

| Postman | hitspec |
| - | - |
| Collection-level auth UI | `# @auth bearer {{token}}` per request |
| Inherit from parent | Explicit per request or default headers in config |

### Request Dependencies

| Postman | hitspec |
| - | - |
| Execution order in Collection Runner | `# @depends requestName` |
| `pm.environment.set()` for chaining | `>>>capture` blocks |

## After Import

After importing, you should:

1. **Add assertions** -- the import generates basic `expect status == 200` assertions. Add more specific ones.
2. **Replace hardcoded values** -- use variables and `{{$env()}}` for URLs, tokens, etc.
3. **Add captures** -- chain requests with `>>>capture` blocks and `@depends`.
4. **Set up environments** -- create `hitspec.yaml` with your environments.

## Exporting Back to curl

You can also export hitspec files to curl for debugging:

```bash theme={null}
hitspec export curl tests/api.http
hitspec export curl tests/api.http --name "Login" --exec
```

Other formats work the same way: `hitspec export --format python tests/api.http`.


# Regression Testing with hitspec diff
Source: https://hitspec.dev/guides/regression-testing

Compare test runs to detect performance regressions and behavior changes.

`hitspec diff` compares two JSON test result files and highlights differences in pass/fail status and response times. This is useful for detecting regressions between builds, branches, or deployments.

## Workflow

1. Run tests and save results as JSON
2. Make changes (deploy, merge PR, etc.)
3. Run tests again and save new results
4. Compare with `hitspec diff`

```bash theme={null}
# Before changes
hitspec run tests/ --output json --output-file baseline.json

# ... make changes ...

# After changes
hitspec run tests/ --output json --output-file current.json

# Compare
hitspec diff baseline.json current.json
```

## Output Formats

### Console (default)

```bash theme={null}
hitspec diff baseline.json current.json
```

Shows a color-coded summary with improved/regressed/unchanged counts and per-test duration changes.

### JSON

```bash theme={null}
hitspec diff baseline.json current.json --output json
```

### HTML

```bash theme={null}
hitspec diff baseline.json current.json --output html > diff-report.html
```

Generates a self-contained HTML report with a dark theme, summary cards, and a comparison table.

## Threshold Checks

Fail the diff if any test regresses beyond a threshold:

```bash theme={null}
hitspec diff baseline.json current.json --threshold 10%
```

This exits with code `1` if any test's response time increased by more than 10%. Useful as a CI/CD gate.

## CI/CD Integration

```yaml theme={null}
# GitHub Actions
- name: Run baseline tests
  run: hitspec run tests/ --output json --output-file baseline.json
  continue-on-error: true

- name: Deploy staging
  run: ./deploy.sh staging

- name: Run current tests
  run: hitspec run tests/ --output json --output-file current.json

- name: Check for regressions
  run: hitspec diff baseline.json current.json --threshold 15%
```

## What Gets Compared

| Metric | Description |
| - | - |
| Pass/fail status | Tests that changed from pass to fail (or vice versa) |
| Duration | Response time changes with percentage |
| New tests | Tests present only in the second file |
| Removed tests | Tests present only in the first file |

A test is classified as:

* **Improved** -- went from fail to pass, or duration decreased by >10%
* **Regressed** -- went from pass to fail, or duration increased by >10%
* **Unchanged** -- same status and duration within 10%


# Troubleshooting
Source: https://hitspec.dev/guides/troubleshooting

Common issues and how to resolve them

## Variable Interpolation

### Variables not being replaced

If `{{variableName}}` appears literally in your request instead of being substituted:

1. **Check your environment file** — Variables must be defined in a `.env` or `hitspec.yaml` file.
2. **Verify the environment is active** — Use `hitspec run --env production` (or `HITSPEC_ENV`), or press `ctrl+e` in `hitspec studio`.
3. **Check for typos** — Variable names are case-sensitive. `{{baseUrl}}` and `{{baseURL}}` are different.

```http theme={null}
### Correct: baseUrl is defined in the active environment
GET {{baseUrl}}/users

### Wrong: base_url is not the same variable as baseUrl
GET {{base_url}}/users
```

<Tip>
  Use `hitspec run --verbose` to see which variables are resolved and which are missing.
</Tip>

### Circular variable references

If you see a `circular variable reference` warning, check that your variables don't reference each other:

```yaml theme={null}
# hitspec.yaml — this will cause a circular reference warning
environments:
  dev:
    a: "{{b}}"
    b: "{{a}}"
```

***

## Captures & Dependencies

### Capture value is empty

If a `>>>capture` block isn't extracting the expected value:

1. **Verify the path** — Use `name from body.data.id` and ensure the response actually contains that path.
2. **Check response content type** — Body paths only work on JSON responses.
3. **Ensure the request succeeds** — If the request returns an error status, the response body may not contain the expected structure.

```http theme={null}
### Login
# @name login

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

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

>>>capture
token from body.accessToken
<<<
```

<Warning>
  Captures are evaluated after assertions. If an assertion fails and you're running with `--bail`, later requests that depend on the capture won't run.
</Warning>

### Dependency order issues

Requests run top-to-bottom within a file, and `@depends` makes sure the request it names has run first. If request B uses a capture from request A, B must declare `# @depends A`:

Declare the dependency with `@depends` and read the value as `{{<request name>.<capture name>}}`:

```http theme={null}
### Login (must come first)
# @name login

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

{"email": "admin@test.com", "password": "pass"}

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

### Use the token (depends on Login)
# @depends login

GET {{baseUrl}}/profile
Authorization: Bearer {{login.token}}
```

***

## SSL / TLS Errors

### Certificate verification failed

If you see `x509: certificate signed by unknown authority`:

```bash theme={null}
# Option 1: Disable SSL verification for testing
hitspec run --insecure tests.http   # or the short form: -k

# Option 2: Set in hitspec.yaml
# validateSSL: false
```

<Warning>
  Only disable SSL verification for local development or testing. Never disable it for production API tests.
</Warning>

### Self-signed certificates

For APIs using self-signed certificates, you can either disable verification or add the CA to your system trust store.

***

## Timeout Issues

### Request timeout

If requests are timing out:

```bash theme={null}
# Increase timeout (default is 30s)
hitspec run --timeout 60s tests.http
```

<Note>
  The `--timeout` flag (and `HITSPEC_TIMEOUT`) take a **duration string** like
  `30s`, `1m`, or `500ms`. The `timeout` key in `hitspec.yaml` is an **integer in
  milliseconds** (see below).
</Note>

Or set it in `hitspec.yaml`:

```yaml theme={null}
timeout: 60000  # milliseconds
```

A single request can override both with `# @timeout 60000` (milliseconds).

### Stress test timeout

During stress testing, individual request timeouts may need to be higher. Raise `--timeout` for the run, or `# @timeout` on the slow request:

```bash theme={null}
hitspec run api.http --stress --duration 60s --rate 100 --timeout 10s
```

***

## hitspec serve & studio Issues

### Port already in use

If you see `listen tcp :4000: bind: address already in use` from `hitspec serve --api-only`:

```bash theme={null}
# Use a different port
hitspec serve --api-only --port 8080

# Or find and kill the process using port 4000
lsof -ti:4000 | xargs kill
```

### The API server rejects my request

`hitspec serve --api-only` only answers requests whose `Host` is a loopback address and whose JSON bodies carry `Content-Type: application/json`. Bind to another address with `--host` and send `Authorization: Bearer <token>` (see `--api-token`).

### Files not appearing in the file list

If your `.http` or `.hitspec` files don't appear:

1. **Check the working directory** — `hitspec studio` uses the current directory by default.
2. **Check file extensions** — Only `.http` and `.hitspec` files are shown.
3. **Nested directories** — Files in subdirectories are shown in a tree structure. Expand the folder.

***

## Assertion Failures

### Unexpected assertion results

Common issues with assertions:

```http theme={null}
### Get user
GET {{baseUrl}}/users/1

>>>
expect status 200

# Wrong: compares the whole body to a string, which is almost never what you want
# expect body == "John"

# Correct: address the JSON field with body.<path>
expect body.name == "John"
expect body.roles[0] == "admin"
<<<
```

`hitspec run -v` prints the expected and actual value of every failed assertion.

### Schema validation failures

If `expect body schema ./schemas/user.json` fails:

1. **Check the schema path** — Relative paths are resolved from the file's directory.
2. **Validate your schema** — Ensure it's valid JSON Schema (draft-07).
3. **Check for required fields** — The response must include all `required` fields.

***

## CI/CD Issues

### Exit codes

hitspec uses these exit codes:

| Code | Meaning |
| - | - |
| 0 | All tests passed |
| 1 | One or more assertions failed |
| 2 | A file could not be loaded (invalid .http syntax, duplicate `@name`, `@depends` cycle) |
| 3 | Configuration error (broken `hitspec.yaml`, missing `--env-file`, bad `--cacert`, `--cert`, `--key` or `--proxy`) |
| 4 | Network error: a request got no response because the connection failed (refused, DNS, TLS, reset, timeout before connecting) |
| 64 | Usage error (unknown flag or command, bad flag value, missing argument, `-` combined with other files), or `--tags`/`--name` matched nothing |
| 130 | Interrupted (Ctrl+C or SIGTERM) |

### GitHub Actions fails but works locally

1. **Environment variables** — Make sure all required variables are set in your CI environment.
2. **Network access** — Ensure the CI runner can reach your API endpoints.
3. **Timeouts** — CI runners may be slower; increase timeouts.

```yaml theme={null}
- name: Run API tests
  run: hitspec run --timeout 60s --env ci tests/
  env:
    BASE_URL: ${{ vars.API_URL }}
```

***

## Performance

### Slow test execution

1. **Enable parallel execution** — `hitspec run --parallel tests/`
2. **Reduce timeout** for fast-failing — `hitspec run --timeout 5s`
3. **Use `@if`/`@unless`** to skip irrelevant tests conditionally.

### Large response bodies

For endpoints returning large responses, assertions on the full body may be slow. Use specific JSONPath queries instead:

```http theme={null}
### List items
GET {{baseUrl}}/items

>>>
# Slow: compares the entire body
# expect body == "..."

# Fast: only checks the field you care about
expect body.data[0].id exists
<<<
```

***

## Getting Help

If your issue isn't listed here:

1. Run with `--verbose` for detailed output.
2. Check the [GitHub Issues](https://github.com/abdul-hamid-achik/hitspec/issues) for known bugs.
3. Open a new issue with your `.http` file content, error message, and hitspec version (`hitspec --version`).


# Upgrading
Source: https://hitspec.dev/guides/upgrading

Tests that may start failing after an upgrade, why, and how to upgrade safely

Some releases fix checks that used to pass without checking anything, or
settings that were silently ignored. After such an upgrade a test can fail, or
a file can stop loading, even though nothing in your files changed. In every
case listed here the old result was wrong: the new failure is the test finally
checking what it says.

## Upgrade safely

<Steps>
  <Step title="Validate with the new version">
    `hitspec validate` reports every file that no longer loads, with
    `file:line:col` and a suggested fix, and prints warnings such as unknown
    directives. `--strict` turns the warnings into errors and also checks that
    every `{{variable}}` is defined. See [validate](/reference/validate-list).

    ```bash theme={null}
    hitspec validate tests/ --strict
    ```
  </Step>

  <Step title="Run the suite once locally">
    Run your tests with the new version and read each failure against the
    lists below before you touch CI.

    ```bash theme={null}
    hitspec run tests/ --env staging
    ```
  </Step>

  <Step title="Pin the version in CI">
    Upgrade CI on purpose, not as a side effect of a new release. With the
    GitHub Action, set `version:`:

    ```yaml theme={null}
    - uses: abdul-hamid-achik/hitspec@v2
      with:
        files: tests/
        version: v2.24.0
    ```

    With Go, install an exact version:
    `go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@v2.24.0`.
  </Step>
</Steps>

Every release lists its changes in the
[changelog](https://github.com/abdul-hamid-achik/hitspec/blob/main/CHANGELOG.md),
and from 2.20.0 on the GitHub release page of each version shows the same
notes.

## 2.24.0

`reporters` and `outputDir` in `hitspec.yaml` used to be read and ignored. They
now apply in `hitspec run`. Nothing changes if your config does not set them,
or sets only `reporters: [console]`.

### `reporters` and `outputDir`

* An unknown reporter name exits 3. Valid names: `console`, `json`, `junit`,
  `tap`, `html`.
* Two or more reporters without `outputDir` exit 3: they would all write to
  stdout. Set `outputDir` or keep one reporter.
* One reporter other than `console` without `outputDir` replaces the console
  report on stdout (`reporters: [json]` is `-o json`).
* With `outputDir`, reports are written there as `hitspec-results.json`,
  `hitspec-junit.xml`, `hitspec-results.tap` and `hitspec-report.html`,
  relative to the config file. If no report goes to stdout, failures are listed
  on stderr as with `--quiet`.
* `-o`, `--output-file`, `HITSPEC_OUTPUT` and `HITSPEC_OUTPUT_FILE` still win
  and skip both keys. See [Configuration](/reference/configuration#reporters-and-outputdir).

### Windows

* A connection the server resets before any response exits 4 (network error),
  as on Linux and macOS. It used to exit 1 when Winsock reported the reset.

### hitspec studio

* The stress form has a new last field, `profile`, for a saved stress profile.
  The other fields keep their order.
* Search re-parses a file only when its modification time or size changed, or
  when studio wrote it.

## 2.23.2

* `hitspec run --stress` prints no color codes when stdout is not a
  terminal, as before 2.23.1. Only a check that expected escape codes in a
  file or pipe is affected.
* Go library: `output.WithNoColor(true)` turns colors off for that formatter
  only, not for the whole process.

## 2.23.1

* `hitspec run --metrics ...` without `--stress`, or with `HITSPEC_METRICS`
  set, prints a warning on stderr. It still exits 0. Add `--stress` or unset
  the variable for normal runs.
* studio and `serve` refuse a `__snapshots__` directory or snapshot file that
  a symlink points to outside the workspace. `hitspec run` is unchanged.
* Stress metrics (JSON, Prometheus, DataDog) now include `status_codes`;
  before, they were always empty.
* `hitspec export --exec` runs through `sh` instead of `bash`.

## 2.23.0

2.23.0 runs the whole test suite on Windows and fixes what that found. It
also applies two `hitspec.yaml` keys that used to be ignored. You only need to
change a `.http` file if it relied on one of the old behaviors below.

### Exit codes

* **A busy port exits 3 in every command.** `hitspec mock` and
  `hitspec record` used to exit 1. `hitspec run --stress --metrics prometheus`
  used to print the error and run the whole load test without metrics. It now
  stops before sending a request. See [Exit codes](/reference/exit-codes).

### Settings that now apply

* `noColor: true` in `hitspec.yaml` turns colors off in `hitspec run`.
  `--no-color=false` or `HITSPEC_NO_COLOR=false` turns them back on.
* With `verbose: true`, stderr starts with the `config: <path>` line, as with
  `-v`. `--verbose=0` turns both off.

### studio, serve and the desktop app

* A `schema` file that a symlink points to outside the workspace is refused,
  as body files already were. `hitspec run` is unchanged.
* **Apply** on a saved stress profile in the desktop app now sends the
  profile, so its thresholds are checked. A run can report failed thresholds
  where it used to ignore them.
* New JSON fields, omitted when empty: `duration` on the stress status and
  `stress_update` events, `warnings` on history results, and an optional
  `profile` on `POST /api/v1/stress/start`. Strict schema validators must
  allow them.
* In `hitspec studio`, `enter` in search selects the request it found, and
  unsaved edits survive the file being deleted on disk (`ctrl+s` recreates
  it).

### Windows

* Hooks and `>>>shell` blocks run through Git for Windows' `sh` when it is
  installed. Without it they fall back to `cmd /C`, where POSIX syntax does
  not work.
* A contract state handler such as `setup-states.sh` runs through that `sh`.
* Quoted globs (`hitspec run 'tests/**/*.http'`) work.
* studio, `serve` and the desktop app report paths with `/`, and so does
  `hitspec import -o`.
* The MCP server refuses `/x`, `\x` and `C:x` paths.
* On every platform, certificate and key errors show the path in plain
  quotes, without doubled backslashes.

## 2.22.0

Most of 2.22.0 adds things, but some changes show up as a different exit code,
a request sent differently, or a check that used to be switched off. None of
them needs an edit to a `.http` file unless it relied on one of the old
behaviors below.

### Exit codes

* **Network errors exit 4.** A request that gets no response because the
  connection failed (refused, DNS, TLS or certificate errors, a reset before
  any response, a timeout before connecting, an OAuth2 token endpoint or a
  `@waitFor` target that cannot be reached) used to exit 1. If a CI step
  accepts only 0 and 1, treat 4 as a failure too. A timeout after connecting
  and assertion failures are still 1. See [Exit codes](/reference/exit-codes).
* **Ctrl+C and SIGTERM exit 130**, after printing the finished requests and
  writing `--output-file`. SIGTERM used to read as 143.
* **Command-line mistakes exit 64**: an unknown flag or command, a bad flag
  value, a missing required flag, the wrong number of arguments, and
  `--dry-run` with `--stress` (which used to run the load test). They exited 1.
* **More configuration errors exit 3 before any request is sent:** a missing
  `--env-file`, a CA, certificate, key or proxy that cannot be loaded, and a
  broken `hitspec.yaml` in `validate`, `studio`, `serve` and `contract` (studio
  and serve used to fall back to the defaults silently).
* **`--dry-run` parses.** A file that does not load exits 2, and filters that
  match exit 0. The plan is always text: `-o` and `--output-file` are ignored.

### Which settings apply

* `hitspec.yaml` is found by walking up from the working directory, stopping
  after the first directory with `.git`, so a config in a parent directory of
  your tests now applies. `hitspec run -v` prints the file it used. Unknown
  keys print a warning; `hitspec validate --strict` turns them into errors.
* `verbose: true` in `hitspec.yaml` now works (it is `-v`); `--verbose=0`
  turns it off.

### Requests sent differently

* **Query lines** (`? name = value`) keep their order and duplicates and encode
  a space as `%20`. They used to be sorted, collapsed and encoded with `+`.
* **Illegal URL characters** (spaces, quotes, non-ASCII) are percent-encoded
  instead of being sent raw.
* **Form blocks** (`& name = value`) keep the spaces in values.
* **A body file that cannot be read** (`< ./file`, a multipart file) fails the
  request. The literal text used to be sent.
* **Unnamed multipart file parts** are sent as field `file`. Name them with
  `file avatar @./me.png`.
* **`@waitFor`** uses the run's client: proxy, CA, `--insecure`, default
  headers and `followRedirects: false` apply to it.
* **Cookies** are only kept between requests with `--cookies` (or
  `cookies: true`).

### Reports and file selection

* Failure output shows the request, the response status and a body excerpt.
  `-v` prints `Response: 200 OK` instead of `Status: 200`; `-vv` adds headers
  and `-vvv` bodies.
* More header names are redacted (anything with `token`, `secret`, `password`
  or `api-key`), in every format including HTML.
* JSON, JUnit and TAP carry new fields such as `warnings`. JUnit states each
  failed assertion once, and TAP escapes backslashes and newlines.
* Directories are searched without `.git`, `node_modules` and `vendor`, and a
  file reached twice runs once.

### mock, record, stress and metrics

* `mock` and `record` listen on `127.0.0.1`; pass `--host 0.0.0.0` for Docker.
  A busy port is an error.
* The Prometheus endpoint listens on `127.0.0.1`; pass `--metrics-host 0.0.0.0`
  when another machine or container scrapes it.
* `mock` answers a wrong method with 405 and serves HEAD for GET routes; CORS
  needs `--cors`.
* `record` redacts tokens, passwords, secrets, API keys and `Set-Cookie` in
  recordings (`--no-redact` keeps them).
* Stress results count requests cut off at the end as incomplete, and
  assertion failures have their own `assertions<N%` threshold, so `rps` and
  `errors` thresholds can move.
* **`errors<0` and `errors: "0%"` are enforced.** They used to switch the
  check off, so a run with errors passed; now one failed request fails it.
* With `--profile`, explicit flags win, and profile thresholds keep their
  operator (`rps: ">=100"`).

### serve, studio and the desktop app

* `--read-only` lets you run requests, stress, mock, record, contract
  verification and import; it only refuses writes to the workspace and
  settings.
* Body files outside the workspace are refused in `serve`, `studio` and the
  desktop app, including in stress and contract runs.
* Starting mock or record on a busy port fails (409 from `serve`), and a
  stress run that cannot start reports `error`.
* `PUT /api/v1/config` applies a key that is present even when it is `0` or
  `""`. Clients that sent those to mean "unchanged" must leave the key out.
* In `hitspec studio`, `enter` no longer submits forms (use `s`, or `ctrl+s`
  while editing), `r` runs the editor's unsaved text, `ctrl+c` cancels a run
  and asks before discarding edits, copy-as fills in `{{variables}}`
  (secrets included), and the mouse is captured only with `--mouse`.

## 2.21.0

### Files that no longer load (exit code 2)

* **Misspelled operators.** They were silently treated as `==`.
  `expect body.name contians "x"` now fails with
  `unknown operator "contians" (did you mean "contains"?)`.

* **An operator with no value, or with two.** `expect status 200 201` is an
  error. To accept several values, use `in`:

  ```http theme={null}
  GET https://api.example.com/health

  >>>
  expect status in [200, 201]
  <<<
  ```

* **Blocks that do not belong to a request.** A `>>>`, `>>>capture`, `>>>db`
  or `>>>shell` block above its request, a block with an unknown type, or a
  block without its closing `<<<` was dropped without a word. Move the block
  below its request, fix the type, or close it.

* **`>>>db <connection>`.** That form never existed, so its checks never ran.
  Set the connection with `# @db` and put the SQL and the column checks inside
  the block (see [Database Testing](/guides/database-testing)).

* **Unsupported `jsonpath` features** (`..`, `?()` filters, slices, unions)
  are errors instead of silently matching nothing.

### Assertions that now check what they say

* **null versus absent.** `== null` needs a JSON `null`; a missing field no
  longer equals null. Use `!exists` to check that a field is absent. Value
  operators (`==`, `>`, `contains`, ...) fail on a missing field; the negated
  ones (`!=`, `!contains`, `!includes`, `!in`) pass.

* **Non-JSON bodies.** `body.x` on an HTML or plain-text response fails with
  "response body is not JSON" instead of comparing against nothing.
  `application/problem+json`, other `+json` types and `text/json` count as
  JSON.

* **Unquoted values are read whole.** `expect body.name == Jane Doe` compares
  `Jane Doe`; it used to compare only `Jane`. A trailing `# comment` is no
  longer part of the value.

* **`jsonpath $.x` subjects are evaluated.** They used to resolve to nothing,
  so `!exists` and `!=` passed whatever the response held.

* **Objects and arrays compare by value**, and numbers compare numerically:

  ```http theme={null}
  GET https://api.example.com/users/1

  >>>
  expect body.address == {"city": "Monterrey", "zip": "64000"}
  <<<
  ```

* **`length` counts characters, not bytes.** `"café"` has length 4; it was 5.

* **`contains`, `startsWith`, `endsWith` and `matches`** on a whole JSON body,
  an object or an array use its JSON text.

* **Paths with `.#` and `#(...)` work.** The `#` used to start a comment and
  cut the path short.

* **`# @if` and `# @unless` evaluate `==`, `!=`, `!`, `&&` and `||`.** Before,
  any non-empty text was true, so `# @if {{env}} == prod` ran the request in
  every environment. It is now skipped outside prod.

* **Directives above the first request** of a file without a `###` line were
  dropped. Its `@name`, `@tags`, `@skip` and `@depends` now apply, so tag
  filters and dependencies can select different requests.

* **`>>>db` blocks written as bare SQL** were dropped. They now run, and need
  `--allow-db`.

### Settings that now apply

* **hitspec.yaml in `hitspec run`.** `timeout`, `retries`, `retryDelay`,
  `maxRedirects`, `parallel`, `concurrency` and `bail` were overridden by the
  flag defaults. A yaml `timeout: 5000` now fails requests slower than five
  seconds, `retries: 3` repeats failing requests, and `bail: true` stops at the
  first failure.
* **`HITSPEC_*=false` overrides hitspec.yaml** (`HITSPEC_INSECURE`,
  `HITSPEC_PARALLEL`, `HITSPEC_BAIL`). The order everywhere is: flag, then
  `HITSPEC_*` variable, then hitspec.yaml, then the built-in default.
* **`maxRedirects: N` follows N redirects.** It followed N-1.

### HTTP behavior

* **Proxy variables are honored.** `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
  apply when no proxy is configured. On a runner with a proxy in its
  environment, requests now go through it; list hosts that must be reached
  directly in `NO_PROXY`. Loopback hosts are never proxied.
* **Credentials stay on their origin.** On a redirect to another scheme, host
  or port, the headers you set (`Authorization`, `Cookie`, `X-Api-Key`, ...)
  are not forwarded. A test that relied on the credential following the
  redirect gets a 401: point it at the final URL.
* **`Host:` is sent as the request's Host.** It used to be ignored.
* **Compressed bodies are decoded.** With an explicit `Accept-Encoding: gzip`
  or `deflate`, assertions see the decoded body, not compressed bytes.
* **Repeated `Set-Cookie` headers are joined with `, `** (it was `; `), like
  every other repeated header.
* **Response bodies over 100 MiB fail** with "response body exceeds".
* **HTTP/2 is negotiated over TLS.**

### Other commands

* **`hitspec diff`.** Skipped tests have their own status and no longer count
  as failures or regressions. A 0 ms baseline never trips `--threshold`.
* **`hitspec mcp serve`.** Saved requests run by `hitspec_fetch` no longer read
  the server's environment variables; allow one with `--allow-env NAME`.
  `--workspace` refuses your home directory, its parents and `/` unless you
  pass `--allow-broad-workspace`.

## 2.20.0

* **`expect header X exists`** passed even when the header was missing. It now
  fails in that case.
* **A body cut short by a timeout** (`@timeout`, `--timeout`) counted as a
  success with a partial body. It is now a failure. Only `text/event-stream`
  (SSE) responses may end at the deadline.
* **Files that fail to load** (a syntax error, a duplicate `@name`, a circular
  `@depends`) were skipped and the run could still exit 0. `hitspec run` now
  exits 2. `--name` and `--tags` filters that match nothing exit 64. See
  [Exit Codes](/reference/exit-codes).
* **`@auth`** with an unknown type or the wrong number of arguments is a parse
  error.
* **The default environment.** Without `--env` or `HITSPEC_ENV`, `hitspec run`
  uses hitspec.yaml `defaultEnvironment` (it always used `dev`), so variables
  such as `{{baseUrl}}` can resolve differently.
* **Header values are sent verbatim.** Quotes and text after `#` are kept:
  `If-None-Match: "abc"` sends the quotes.
* **Captured values are inserted literally.** A `{{...}}` inside a captured
  value is no longer expanded.


# Install hitspec — Homebrew, Go, and binary
Source: https://hitspec.dev/installation

Install hitspec on macOS, Linux, or Windows via Homebrew, go install, a pre-built binary, or build from source. Get the hitspec CLI running in minutes.

## Homebrew (macOS / Linux)

hitspec is published as a Homebrew cask in the `abdul-hamid-achik/tap` tap:

```bash theme={null}
brew install --cask abdul-hamid-achik/tap/hitspec
```

This installs the latest release and makes the `hitspec` command available in your shell.

## Go Install

If you have Go installed:

```bash theme={null}
go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@latest
```

<Note>
  Needs Go 1.21 or later to start; `go.mod` pins the Go 1.26.9 toolchain, which Go downloads automatically. The binary will be placed in your `$GOPATH/bin` directory -- make sure it's in your `PATH`.
</Note>

## Binary Download

Pre-built archives for every platform are attached to each [GitHub
Release](https://github.com/abdul-hamid-achik/hitspec/releases). Assets are named:

```
hitspec_<version>_<os>_<arch>.tar.gz     # macOS / Linux  (e.g. hitspec_2.14.1_darwin_arm64.tar.gz)
hitspec_<version>_windows_<arch>.zip     # Windows
```

where `<os>` is `darwin`, `linux`, or `windows` and `<arch>` is `amd64` or `arm64`.

<Tabs>
  <Tab title="macOS / Linux">
    Download the archive for your platform from the
    [Releases page](https://github.com/abdul-hamid-achik/hitspec/releases/latest),
    then extract and install it. For example, on Apple Silicon macOS:

    ```bash theme={null}
    # Substitute the version and platform for your machine
    VERSION=2.19.0
    curl -Lo hitspec.tar.gz \
      "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_darwin_arm64.tar.gz"
    tar -xzf hitspec.tar.gz hitspec
    chmod +x hitspec
    sudo mv hitspec /usr/local/bin/
    ```
  </Tab>

  <Tab title="Windows">
    Download `hitspec_<version>_windows_amd64.zip` from the
    [Releases page](https://github.com/abdul-hamid-achik/hitspec/releases/latest),
    extract `hitspec.exe`, and add its folder to your `PATH`.
  </Tab>
</Tabs>

<Tip>
  Homebrew (`brew upgrade --cask hitspec`) and `go install ...@latest` make upgrades a
  single command -- prefer them over manual downloads unless you need a specific
  archived version.
</Tip>

## Build from Source

To build hitspec yourself -- to contribute, or to get an unreleased change -- clone
the repo and build the CLI. The module is `github.com/abdul-hamid-achik/hitspec/v2`
and the CLI entry point is `apps/cli` (`cmd/hitspec` is the same binary, named for
`go install`).

<Steps>
  <Step title="Prerequisites">
    * **Go 1.26** (`go version`; an older Go 1.21+ downloads the pinned 1.26.9 toolchain automatically)
    * **[Task](https://taskfile.dev)** -- the task runner used for every dev command (optional, but recommended)
    * **[glyph](https://github.com/abdul-hamid-achik/glyphrun)** -- only needed to run the studio end-to-end specs (`task e2e`)
  </Step>

  <Step title="Clone and build">
    <CodeGroup>
      ```bash With Task (recommended) theme={null}
      git clone https://github.com/abdul-hamid-achik/hitspec.git
      cd hitspec
      task setup   # download deps + run code generation
      task build   # builds ./bin/hitspec
      ```

      ```bash Plain Go theme={null}
      git clone https://github.com/abdul-hamid-achik/hitspec.git
      cd hitspec
      go build -o bin/hitspec ./apps/cli
      ```
    </CodeGroup>

    `task build` stamps the binary with the version and build time. The result is
    `./bin/hitspec`.
  </Step>

  <Step title="Install to your PATH (optional)">
    ```bash theme={null}
    task install   # go install into $GOPATH/bin
    ```
  </Step>

  <Step title="Run the checks">
    ```bash theme={null}
    task test    # all Go tests (race + coverage)
    task lint    # gofmt + go vet + golangci-lint
    task check   # lint + test + security
    task e2e     # studio terminal-UI specs (requires glyph)
    ```
  </Step>
</Steps>

<Note>
  Run `task` (or `task --list`) to see every available command, including
  `task studio:dev`, `task serve:dev`, and `task docs:dev` (live Mintlify docs).
</Note>

## Verify Installation

```bash theme={null}
hitspec version
```

You should see the installed version number. If the command is not found, make sure the binary location is in your `PATH`.

## Updating

<CodeGroup>
  ```bash Homebrew theme={null}
  brew upgrade --cask hitspec
  ```

  ```bash Go theme={null}
  go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@latest
  ```
</CodeGroup>


# Agent artifact workflow
Source: https://hitspec.dev/integrations/agent-artifacts

Compose Hitspec with file.cheap, MCPHub, Local Agent, and an external tvault boundary

Hitspec owns HTTP execution, live-web discovery, response rendering, and the
explicit artifact-adapter boundary. file.cheap owns durable artifact storage
and indexing. MCPHub owns lazy tool discovery and oversized MCP-result spooling.
Local Agent consumes the namespaced tools.

## Local Agent web surface

Hitspec is the only model-visible web abstraction. Tavily is an internal,
replaceable provider selected by the server operator; do not register Tavily as
another MCP server for Local Agent.

```text theme={null}
Local Agent
    └── MCPHub
          └── Hitspec
                ├── hitspec_search_web       discovery
                ├── hitspec_fetch            retrieval
                └── hitspec_capture_webpage  durable evidence
                              └── file.cheap  artifact corpus
```

This is the stable v2.18.0 web surface. `hitspec_search_web` discovers candidate
sources, `hitspec_fetch` reads without persistence, and
`hitspec_capture_webpage` creates durable page evidence.
`hitspec_list_requests` and `hitspec_validate` remain workspace tools. Search
returns a provider-neutral `kind: "discovery"` document capped at 64 KiB;
capture returns a compact stash receipt with the durable content hash.

## Save a response in file.cheap

Use an explicit file handoff so the artifact is reviewable before persistence:

```bash theme={null}
hitspec fetch https://example.com/docs \
  --format markdown \
  --output-file response.md

fcheap save response.md \
  --tool hitspec \
  --tag hitspec-response \
  --tag format:markdown \
  --source https://example.com/docs \
  --index
```

Useful tags include `hitspec-response`, `format:raw|text|markdown|json`, a safe
request name, and `status:<code>`. Do not put credentials, tokens, cookies, or
URL query parameters in names, tags, or source metadata.

The same reviewable CLI handoff remains useful for humans. For agents, start the
Hitspec MCP server with a fixed `--fcheap-path`; `hitspec_capture_webpage`
performs the handoff inside a private temporary directory and returns a compact
receipt. `hitspec_fetch` never persists. The model cannot choose the executable,
stash directory, or output path.

## Register both servers in MCPHub

```yaml theme={null}
version: 1
expose: lazy
response_budget: 32KB

servers:
  hitspec:
    command: hitspec
    args:
      - mcp
      - serve
      - --workspace
      - /absolute/api-workspace
      - --fcheap-path
      - /absolute/path/to/fcheap
    vault: tavily
    vault_only: [TAVILY_API_KEY]
    env:
      HITSPEC_SEARCH_PROVIDER: tavily
    enabled: true
    tags: [http, api, testing]

  fcheap:
    command: fcheap
    args: [mcp, serve]
    enabled: true
    tags: [artifacts, search]

agents:
  local-agent:
    type: local-agent
    path: ~/.config/local-agent/config.yaml
    mode: gateway
    servers: [hitspec, fcheap]
```

Agents see namespaced tools such as `hitspec__hitspec_search_web`,
`hitspec__hitspec_fetch`, `hitspec__hitspec_capture_webpage`, and
`fcheap__fcheap_search`. Verify the catalog before changing an agent config:

```bash theme={null}
mcphub doctor --json --probe
mcphub sync local-agent
# Review the dry run, then apply explicitly:
mcphub sync local-agent --write
```

MCPHub may spool a large inline result and return a temporary handle. That is a
transport safeguard, not durable artifact storage. Hitspec's webpage capture
invokes the fixed file.cheap CLI with argv (never a shell), parses its
JSON receipt even after a partial post-save failure, and removes the private
handoff.
The file.cheap child receives only basic process settings and `FCHEAP_*`
configuration; web-provider credentials are not inherited.

`vault_only` limits the values tvault adds to the Hitspec child process. It does
not remove `TAVILY_API_KEY` if that variable is already exported by MCPHub's
parent process, so do not export the key globally. The model cannot supply the
provider, endpoint, API key, authorization header, file.cheap executable, stash
directory, or output path as tool arguments.

## Approval policy

| Tool | Recommended policy |
| - | - |
| `hitspec_search_web` | Eligible for AUTO only when the exact bounded tool is explicitly allowlisted. Results are discovery, not evidence. |
| `hitspec_capture_webpage` | Public-network read plus durable write; allowlist only after both effects are accepted. |
| `hitspec_fetch` | Keep approval-gated because it accepts methods, headers, and bodies. It never persists content. |

AUTO does not grant private-network access or weaken SSRF, redirect, body-size,
or workspace checks.

## Safe rollout

Before replacing a binary already connected to MCPHub, record its executable,
checksum, and complete tool schemas. If it already exposes
`hitspec_capture_webpage`, preserve that public name and compatible inputs before
cutover; rebuilding from a checkout with a smaller catalog is a regression.

Build a candidate without replacing the active binary, then require:

1. `mcphub doctor --server hitspec --probe` shows all five tools: search, fetch,
   webpage capture, list, and validate.
2. A canary completes `hitspec_search_web` → `hitspec_capture_webpage` →
   `fcheap search`, with the expected normalized source and hashes.
3. AUTO and approval behavior matches the table above and no secret appears in
   process arguments, logs, results, or file.cheap child environment.

Keep the previous executable and configuration for immediate rollback.

## tvault boundary

The MCPHub/tvault process wrapper above is the external injection boundary.
Native tvault resolution inside Hitspec remains deferred: Hitspec has no
vault-specific request syntax and never writes fetched credentials back to an
environment automatically. Until a separate secret-reference contract is
defined:

* inject required values into the Hitspec process environment outside the
  request or tool arguments;
* do not place secret values in `.http` files, MCPHub YAML, URL query strings,
  output filenames, tags, logs, or Markdown provenance; and
* keep MCPHub's `vault`/`vault_only` process wrapper as the boundary rather than
  teaching Hitspec to read a vault ad hoc.

The follow-up design must define reference syntax, precedence, redaction,
missing-secret errors, and the boundary between Hitspec environments and tvault
before native support is enabled.


# DataDog
Source: https://hitspec.dev/integrations/datadog

Send hitspec stress test metrics directly to DataDog for monitoring.

hitspec can send test execution metrics directly to the DataDog API during stress tests.

## Setup

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics datadog \
  --datadog-api-key "$DD_API_KEY"
```

## Configuration

| Flag | Env Var | Default | Description |
| - | - | - | - |
| `--datadog-api-key` | `DD_API_KEY` | *(required)* | Your DataDog API key |
| `--datadog-site` | `DD_SITE` | `datadoghq.com` | DataDog site (EU: `datadoghq.eu`) |
| `--datadog-tags` | `DD_TAGS` | | Comma-separated tags |

## Tags

Add custom tags to your metrics for filtering in DataDog dashboards:

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics datadog \
  --datadog-api-key "$DD_API_KEY" \
  --datadog-tags "env:staging,service:user-api,team:backend"
```

## CI/CD Example

```yaml theme={null}
# GitHub Actions
- name: Stress test with DataDog metrics
  run: |
    hitspec run api.http --stress -d 5m -r 100 \
      --metrics datadog \
      --datadog-tags "env:staging,branch:${{ github.ref_name }}"
  env:
    DD_API_KEY: ${{ secrets.DD_API_KEY }}
```


# GitHub Actions
Source: https://hitspec.dev/integrations/github-actions

Run hitspec API tests in your GitHub Actions CI/CD pipeline with JUnit reporting, caching, and matrix testing.

hitspec integrates with GitHub Actions through an official action and direct CLI usage. You can run API tests on every push, pull request, or schedule, and report results using JUnit XML.

## Official GitHub Action

The fastest way to add hitspec to your pipeline:

```yaml .github/workflows/api-tests.yml theme={null}
name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          output: junit
          output-file: test-results.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results
          path: test-results.xml
```

### Action Inputs

| Input | Description | Default |
| - | - | - |
| `files` | Files, directories or glob patterns, separated by whitespace or newlines (see [Selecting files](#selecting-files)) | (required) |
| `env` | Environment name. When empty, hitspec uses `defaultEnvironment` from `hitspec.yaml` | - |
| `env-file` | Path to `.env` file for variable interpolation | - |
| `output` | Output format (`console`, `json`, `junit`, `tap`, `html`) | `console` |
| `output-file` | Write the report to this file. Defaults to `hitspec-results.<ext>` for `json`, `junit`, `tap` and `html` | - |
| `tags` | Filter by tags (comma-separated) | - |
| `name` | Filter by request name pattern | - |
| `timeout` | Request timeout: a duration such as `30s` or `1m`, or a plain integer meaning milliseconds (`5000` is `5000ms`) | - |
| `parallel` | Run requests in parallel | `false` |
| `concurrency` | Max concurrent requests when `parallel` is enabled | - |
| `bail` | Stop on first failure | `false` |
| `verbose` | Show detailed output | `false` |
| `insecure` | Disable SSL certificate validation | `false` |
| `proxy` | Proxy URL for requests | - |
| `stress` | Enable stress testing mode | `false` |
| `duration` | Stress test duration (e.g. `30s`, `1m`) | `30s` |
| `rate` | Target requests per second for stress testing | `10` |
| `vus` | Number of virtual users (alternative to `rate`) | - |
| `max-vus` | Maximum concurrent requests in stress mode | - |
| `think-time` | Think time between requests per VU | - |
| `ramp-up` | Ramp-up time to reach target rate/VUs | - |
| `threshold` | Pass/fail thresholds (e.g. `"p95<200ms,errors<0.1%"`) | - |
| `profile` | Stress profile name from `hitspec.yaml` | - |
| `version` | hitspec release to install (e.g. `v2.20.0` or `latest`) | `latest` |

### Selecting files

`files` takes one or more paths separated by spaces or newlines. Directories and
glob patterns are both accepted, and a pattern that matches nothing fails the
step instead of silently testing nothing:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: |
      tests/smoke/
      services/**/*.http
```

`**` matches across directories when the runner's `bash` is version 4 or newer
(Linux and Windows runners); with bash 3.2 (the macOS system shell) it behaves
like a single `*`, so list one pattern per directory level there. Paths that
contain spaces are not supported.

### Reports

With the default `output: console` the results are printed in the log. When you
choose a machine-readable format (`json`, `junit`, `tap` or `html`) the report is
written to `output-file`, or to `hitspec-results.<ext>` (`.json`, `.xml`, `.tap`,
`.html`) when you do not set one, so it never floods the log. Use the
`report-file` output to find it:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  id: hitspec
  with:
    files: tests/
    output: junit

- uses: actions/upload-artifact@v7
  if: always()
  with:
    name: test-results
    path: ${{ steps.hitspec.outputs.report-file }}
```

### Action Outputs

| Output | Description |
| - | - |
| `exit-code` | Exit code from hitspec (`0` = success, non-zero = failure) |
| `report-file` | Path of the report file (empty for `console` output without `output-file`) |
| `version` | The hitspec release that was installed, for example `v2.20.0` |

### Installation, platforms and verification

The action downloads the hitspec release archive from GitHub Releases (with
retries), verifies its SHA-256 against the `checksums.txt` published with the
same release, and adds the binary to `PATH` for the following steps. A checksum
mismatch fails the step. It supports Linux, macOS and Windows runners on
`amd64` and `arm64`. With `version: latest` the release is resolved through the
public `releases/latest` redirect, so no API quota is used.

The step fails whenever hitspec exits non-zero. Combine it with
`continue-on-error: true` and `steps.<id>.outcome` if a failing test run should
not stop the job.

### Pinning the action

`@v2` is a floating tag that moves to the latest `v2.x.y` release. Pin to a
specific release tag (for example `@v2.20.0`) or a commit SHA for fully
reproducible workflows. The older `@v1` tag is frozen and still contains the
previous, less robust implementation of the action; move to `@v2`.

## Using the CLI Directly

If you prefer installing hitspec yourself (for example, to pin a specific version or use Homebrew caching), you can call the CLI directly:

```yaml .github/workflows/api-tests.yml theme={null}
name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install hitspec
        run: |
          # Choose a published version from the Releases page:
          # https://github.com/abdul-hamid-achik/hitspec/releases/latest
          VERSION=2.18.0
          curl -fsSL "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_linux_amd64.tar.gz" | tar xz
          sudo mv hitspec /usr/local/bin/

      - name: Run API tests
        run: |
          hitspec run tests/ \
            --env staging \
            --output junit \
            --output-file test-results.xml \
            --bail

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results
          path: test-results.xml
```

## Exit Codes

hitspec uses specific exit codes that GitHub Actions interprets as pass or fail:

| Code | Meaning | CI Result |
| - | - | - |
| `0` | All tests passed | Step passes |
| `1` | One or more tests failed | Step fails |
| `2` | A file could not be loaded (invalid `.http` syntax, duplicate `@name`, `@depends` cycle) | Step fails |
| `3` | Configuration error (broken `hitspec.yaml`, missing `--env-file`, bad CA, certificate, key or proxy) | Step fails |
| `4` | Network error: a request got no response because the connection failed | Step fails |
| `64` | Usage error (unknown flag, bad value, missing argument), or `--name`/`--tags` matched no request | Step fails |
| `130` | Interrupted (Ctrl+C or SIGTERM) | Step fails |

Any non-zero exit code causes the GitHub Actions step to fail, which blocks the workflow (and any required status checks) from passing.

## Environment Variables and Secrets

Use GitHub secrets to pass sensitive values like API tokens and credentials. hitspec supports all major CLI flags as environment variables with the `HITSPEC_` prefix.

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}
    HITSPEC_ENV: staging
    HITSPEC_TIMEOUT: 60s
    HITSPEC_BAIL: "true"
  with:
    files: tests/
    output: junit
    output-file: test-results.xml
```

### Using an `.env` File

If your tests rely on an environment file, generate it from secrets at runtime:

```yaml theme={null}
- name: Create environment file
  run: |
    echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci
    echo "DB_URL=${{ secrets.DB_URL }}" >> .env.ci

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    env: staging
    env-file: .env.ci
```

### Supported Environment Variables

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

Each variable sits between its flag and hitspec.yaml: the flag wins over the
variable, and the variable wins over hitspec.yaml. `HITSPEC_BAIL=false` turns
off a `bail: true` in hitspec.yaml.

### Metrics and Notification Variables

| Environment Variable | CLI Flag | Description |
| - | - | - |
| `HITSPEC_METRICS` | `--metrics` | Metrics export format: `prometheus`, `datadog`, `json` |
| `HITSPEC_METRICS_PORT` | `--metrics-port` | Prometheus metrics port (default `9090`) |
| `HITSPEC_METRICS_HOST` | `--metrics-host` | Prometheus bind address (default `127.0.0.1`) |
| `HITSPEC_METRICS_FILE` | `--metrics-file` | Output file for JSON metrics |
| `DD_API_KEY` | `--datadog-api-key` | DataDog API key |
| `DD_SITE` | `--datadog-site` | DataDog site (default `datadoghq.com`) |
| `DD_TAGS` | `--datadog-tags` | Comma-separated DataDog tags |
| `HITSPEC_NOTIFY` | `--notify` | Notification service: `slack`, `teams` |
| `HITSPEC_NOTIFY_ON` | `--notify-on` | When to notify: `always`, `failure`, `success`, `recovery` (default `failure`) |
| `SLACK_WEBHOOK` | `--slack-webhook` | Slack webhook URL |
| `SLACK_CHANNEL` | `--slack-channel` | Slack channel override |
| `TEAMS_WEBHOOK` | `--teams-webhook` | Microsoft Teams webhook URL |

## Caching

Cache the hitspec binary to speed up subsequent runs:

```yaml theme={null}
- name: Cache hitspec binary
  uses: actions/cache@v5
  with:
    path: /usr/local/bin/hitspec
    key: hitspec-${{ runner.os }}-${{ hashFiles('.hitspec-version') }}

- name: Install hitspec
  run: |
    if ! command -v hitspec &> /dev/null; then
      # Choose a published version from the Releases page:
      # https://github.com/abdul-hamid-achik/hitspec/releases/latest
      VERSION=2.18.0
      curl -fsSL "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_linux_amd64.tar.gz" | tar xz
      sudo mv hitspec /usr/local/bin/
    fi
```

If you install hitspec via Go, you can cache the Go module cache instead:

```yaml theme={null}
- uses: actions/setup-go@v6
  with:
    go-version: "1.26.x"
    cache: true

- name: Install hitspec
  run: go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@latest
```

## Matrix Testing

Run the same tests across multiple environments or configurations using a GitHub Actions matrix:

```yaml .github/workflows/api-tests.yml theme={null}
name: API Tests (Matrix)

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        environment: [dev, staging, production]
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: ${{ matrix.environment }}
          output: junit
          output-file: test-results-${{ matrix.environment }}.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results-${{ matrix.environment }}
          path: test-results-${{ matrix.environment }}.xml
```

### Matrix with Tags

You can also use a matrix to run different test suites:

```yaml theme={null}
strategy:
  fail-fast: false
  matrix:
    include:
      - suite: smoke
        tags: smoke
        timeout: 30s
      - suite: integration
        tags: integration
        timeout: 120s
      - suite: contract
        tags: contract
        timeout: 60s

steps:
  - uses: actions/checkout@v6

  - uses: abdul-hamid-achik/hitspec@v2
    env:
      HITSPEC_TIMEOUT: ${{ matrix.timeout }}
    with:
      files: tests/
      tags: ${{ matrix.tags }}
      output: junit
      output-file: test-results-${{ matrix.suite }}.xml
```

## Stress Testing in CI

Run load tests in your pipeline to catch performance regressions:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: api.http
    stress: true
    duration: 2m
    rate: 100
    threshold: "p95<200ms,errors<0.5%"
```

The `threshold` input defines pass/fail criteria. If any threshold is exceeded, the step fails with exit code `1`.

## Reporting with JUnit

Most CI reporting tools understand JUnit XML. To publish results in GitHub pull requests, combine hitspec with a JUnit reporter action:

```yaml theme={null}
- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    output: junit
    output-file: test-results.xml

- name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: ${{ !cancelled() }}
  with:
    files: test-results.xml
    comment_mode: off
```

This adds a test summary directly to the pull request checks tab. Grant the
workflow or job token `checks: write` when publishing check runs.

## Full Example Workflow

A complete workflow that runs smoke tests on every PR, full tests on `main`, and uploads results:

```yaml .github/workflows/api-tests.yml theme={null}
name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          tags: smoke
          output: junit
          output-file: smoke-results.xml
          bail: true

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: smoke-results
          path: smoke-results.xml

  full:
    runs-on: ubuntu-latest
    needs: smoke
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v6

      - name: Create environment file
        run: |
          echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: staging
          env-file: .env.ci
          parallel: true
          output: junit
          output-file: full-results.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: full-results
          path: full-results.xml
```


# Output Formats
Source: https://hitspec.dev/integrations/output-formats

hitspec supports five output formats: console, JSON, JUnit XML, TAP, and HTML. Choose the right format for your workflow.

hitspec supports five output formats, each designed for a different use case. Set the format with the `--output` (or `-o`) flag:

```bash theme={null}
hitspec run tests/ --output <format>
```

To write the output to a file instead of stdout:

```bash theme={null}
hitspec run tests/ --output json --output-file results.json
```

## Console (default)

Human-readable output with colors, designed for local development. This is the default when no `--output` flag is specified.

```bash theme={null}
hitspec run tests/
```

```
Running: tests/api.http

  ✓ healthCheck (45ms)
  ✓ login (120ms)
  ✗ getProfile (89ms)
    → status ==
      Expected: 200
      Actual:   401
      expected 200, got 401

Tests: 2 passed, 1 failed, 3 total
Time:  254ms
```

**When to use:** Local development, debugging, interactive use. The colored output makes it easy to spot failures at a glance.

**Flags that affect console output:**

| Flag | Effect |
| - | - |
| `--verbose` / `-v` | Show the request and status of every request (`-vv` adds headers, `-vvv` the full bodies) |
| `--quiet` / `-q` | Suppress all output except errors |
| `--no-color` | Disable colored output (also set via `HITSPEC_NO_COLOR=true`) |

## JSON

Machine-readable JSON output for scripting, custom dashboards, and programmatic analysis.

```bash theme={null}
hitspec run tests/ --output json
```

```json theme={null}
{
  "file": "tests/api.http",
  "passed": 2,
  "failed": 1,
  "skipped": 0,
  "duration": 254,
  "results": [
    {
      "name": "healthCheck",
      "passed": true,
      "duration": 45
    },
    {
      "name": "login",
      "passed": true,
      "duration": 120
    },
    {
      "name": "getProfile",
      "passed": false,
      "duration": 89,
      "errors": [
        {
          "assertion": "status ==",
          "expected": "200",
          "actual": "401",
          "message": "expected 200, got 401"
        }
      ]
    }
  ]
}
```

**When to use:** Scripting and automation. Pipe the output to `jq` for filtering, feed it into monitoring dashboards, or use `hitspec diff` to compare two JSON result files for regression detection.

**Examples:**

<CodeGroup>
  ```bash Filter failures with jq theme={null}
  hitspec run tests/ -o json | jq '.results[] | select(.passed == false)'
  ```

  ```bash Save and compare results theme={null}
  hitspec run tests/ -o json --output-file baseline.json
  # ... make changes ...
  hitspec run tests/ -o json --output-file current.json
  hitspec diff baseline.json current.json
  ```

  ```bash Extract timing data theme={null}
  hitspec run tests/ -o json | jq '[.results[] | {name, duration}]'
  ```
</CodeGroup>

## JUnit XML

Standard JUnit XML format understood by virtually all CI/CD systems. This is the recommended format for CI pipelines.

```bash theme={null}
hitspec run tests/ --output junit --output-file test-results.xml
```

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<testsuites tests="3" failures="1" errors="0" time="0.254">
  <testsuite name="tests/api.http" tests="3" failures="1" errors="0" time="0.254">
    <testcase name="healthCheck" time="0.045" />
    <testcase name="login" time="0.120" />
    <testcase name="getProfile" time="0.089">
      <failure message="expected 200, got 401">
        Assertion: status ==
        Expected: 200
        Actual:   401
      </failure>
    </testcase>
  </testsuite>
</testsuites>
```

**When to use:** CI/CD pipelines. JUnit XML is the de facto standard for test reporting in GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure DevOps, and other CI systems. Use `--output-file` to write to a file that your CI system can pick up as a test artifact.

**CI integration example:**

```yaml theme={null}
# GitHub Actions
- name: Run API tests
  run: hitspec run tests/ --output junit --output-file test-results.xml

- name: Publish results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: ${{ !cancelled() }}
  with:
    files: test-results.xml
    comment_mode: off
```

Grant the workflow or job token `checks: write` when publishing check runs.

## TAP (Test Anything Protocol)

TAP is a text-based protocol for reporting test results. It works well with Unix tools and TAP consumers.

```bash theme={null}
hitspec run tests/ --output tap
```

```
TAP version 13
1..3
ok 1 - healthCheck
ok 2 - login
not ok 3 - getProfile
  ---
  message: expected 200, got 401
  ---
```

**When to use:** Unix pipelines and environments that already consume TAP output. TAP is a simple line-based format that works naturally with `grep`, `awk`, and other text-processing tools. It is also understood by TAP reporters in Node.js, Perl, and other ecosystems.

**Examples:**

<CodeGroup>
  ```bash Count failures theme={null}
  hitspec run tests/ -o tap | grep -c "^not ok"
  ```

  ```bash Show only failures theme={null}
  hitspec run tests/ -o tap | grep "^not ok"
  ```

  ```bash Pipe to a TAP reporter theme={null}
  hitspec run tests/ -o tap | npx tap-spec
  ```
</CodeGroup>

## HTML

Generate a self-contained HTML report for sharing test results with stakeholders who may not have terminal access.

```bash theme={null}
hitspec run tests/ --output html --output-file report.html
```

The HTML report includes:

* Summary of passed, failed, and skipped tests
* Duration for each request
* Detailed assertion failure messages
* Filterable and sortable results table

**When to use:** Sharing results with non-technical stakeholders, archiving test runs as artifacts, or generating reports for review meetings. Combine with `actions/upload-artifact` in CI to attach the report to each build.

```yaml theme={null}
# GitHub Actions
- name: Run API tests
  run: hitspec run tests/ --output html --output-file report.html

- uses: actions/upload-artifact@v7
  if: always()
  with:
    name: api-test-report
    path: report.html
```

## Format Comparison

| Format | Best For | Machine Readable | Human Readable | CI Support |
| - | - | :-: | :-: | :-: |
| `console` | Local development | No | Yes | -- |
| `json` | Scripting, dashboards | Yes | No | -- |
| `junit` | CI/CD pipelines | Yes | No | All major CI systems |
| `tap` | Unix pipelines | Yes | Partially | TAP consumers |
| `html` | Reports, sharing | No | Yes | Upload as artifact |

## From hitspec.yaml

Set `reporters` and `outputDir` in `hitspec.yaml` to choose the reports without flags. This prints the console report and writes a JUnit file for CI:

```yaml theme={null}
reporters:
  - console
  - junit
outputDir: reports
```

```bash theme={null}
hitspec run tests/   # console report on stdout, reports/hitspec-junit.xml for CI
```

Each reporter other than `console` writes a fixed file name in `outputDir`: `hitspec-results.json`, `hitspec-junit.xml`, `hitspec-results.tap` or `hitspec-report.html`. Without `outputDir`, all reporters write to stdout, so only one is allowed (`reporters: [json]` is the same as `--output json`). `--output`, `--output-file`, `HITSPEC_OUTPUT` and `HITSPEC_OUTPUT_FILE` take precedence and ignore both keys. See [Configuration](/reference/configuration#reporters-and-outputdir) for the rules and exit codes.

## Setting a Default Format

Use the `HITSPEC_OUTPUT` environment variable to avoid passing `--output` on every invocation:

```bash theme={null}
export HITSPEC_OUTPUT=json
hitspec run tests/  # outputs JSON without --output flag
```

Similarly, `HITSPEC_OUTPUT_FILE` sets a default output file path:

```bash theme={null}
export HITSPEC_OUTPUT=junit
export HITSPEC_OUTPUT_FILE=test-results.xml
hitspec run tests/  # writes JUnit XML to test-results.xml
```


# Prometheus
Source: https://hitspec.dev/integrations/prometheus

Export hitspec stress test metrics to Prometheus for monitoring dashboards.

hitspec exposes a Prometheus-compatible metrics endpoint during stress tests, allowing you to scrape metrics into Prometheus and visualize them in Grafana.

## Setup

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics prometheus \
  --metrics-port 9090
```

Metrics are available at `http://localhost:9090/metrics` while the stress test runs. The endpoint listens on `127.0.0.1` only. To let a Prometheus server on another machine scrape it, bind another interface with `--metrics-host 0.0.0.0` (env: `HITSPEC_METRICS_HOST`); the metrics are not authenticated, so expose them only on a trusted network. The numbers are updated every second during the run, so a scrape in the middle of a test sees the current totals, not zeros.

## Prometheus Configuration

Add hitspec as a scrape target in your `prometheus.yml`:

```yaml theme={null}
scrape_configs:
  - job_name: 'hitspec'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:9090']
```

## Available Metrics

| Metric | Type | Description |
| - | - | - |
| `hitspec_requests_total` | Counter | Total number of requests |
| `hitspec_requests_success_total` | Counter | Successful requests |
| `hitspec_requests_failed_total` | Counter | Failed requests |
| `hitspec_request_duration_ms{quantile="..."}` | Gauge | Request duration in milliseconds: `min`, `max`, `avg`, and the `0.50`, `0.95` and `0.99` quantiles |
| `hitspec_requests_by_status_total{status="..."}` | Counter | Requests by HTTP status code |
| `hitspec_test_requests_total{test="..."}` | Counter | Requests per named test |
| `hitspec_test_duration_avg_ms{test="..."}` | Gauge | Average request duration per named test |

## Custom Port

```bash theme={null}
hitspec run api.http --stress -d 5m -r 100 \
  --metrics prometheus \
  --metrics-port 9100
```

Environment variables: `HITSPEC_METRICS_PORT`, `HITSPEC_METRICS_HOST`


# Slack & Teams Notifications
Source: https://hitspec.dev/integrations/slack-teams

Send hitspec test results to Slack and Microsoft Teams via webhooks.

hitspec can notify your team about test results through Slack and Microsoft Teams webhooks. See [Notifications](/features/notifications) for full details.

## Slack

### Setup

1. Create a [Slack Incoming Webhook](https://api.slack.com/messaging/webhooks)
2. Set the webhook URL as an environment variable or pass it via flag

```bash theme={null}
hitspec run tests/ \
  --notify slack \
  --slack-webhook "$SLACK_WEBHOOK" \
  --notify-on failure
```

### Configuration

| Flag | Env Var | Description |
| - | - | - |
| `--slack-webhook` | `SLACK_WEBHOOK` | Webhook URL (required) |
| `--slack-channel` | `SLACK_CHANNEL` | Override default channel |
| `--notify-on` | `HITSPEC_NOTIFY_ON` | When to notify: `always`, `failure`, `success`, `recovery` |

### What You Get

The Slack notification includes:

* Color-coded attachment (green for pass, red for fail)
* Test count summary (total, passed, failed)
* Duration
* Environment name
* Failed test details with error messages

***

## Microsoft Teams

### Setup

1. Create a [Teams Incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
2. Set the webhook URL as an environment variable or pass it via flag

```bash theme={null}
hitspec run tests/ \
  --notify teams \
  --teams-webhook "$TEAMS_WEBHOOK" \
  --notify-on failure
```

### Configuration

| Flag | Env Var | Description |
| - | - | - |
| `--teams-webhook` | `TEAMS_WEBHOOK` | Webhook URL (required) |
| `--notify-on` | `HITSPEC_NOTIFY_ON` | When to notify |

### What You Get

The Teams notification uses an Adaptive Card with:

* Summary title with pass/fail status
* Column layout with test counts
* Failed test details
* Timestamp footer

***

## Both Services

Send to both simultaneously:

```bash theme={null}
hitspec run tests/ \
  --notify slack,teams \
  --slack-webhook "$SLACK_WEBHOOK" \
  --teams-webhook "$TEAMS_WEBHOOK" \
  --notify-on failure
```


# hitspec — Plain text API tests. No magic.
Source: https://hitspec.dev/introduction

hitspec is a file-based HTTP API testing tool — write .http tests that look like real HTTP requests, assert, capture, chain, and load-test. No SDK, no GUI.

<JsonLd />

<section>
  <div>
    <span>
      <span />

      Open source · Go · single binary · zero dependencies
    </span>

    <h1>
      Plain text API tests.

      <br />

      <span>No magic.</span>
    </h1>

    <p>
      hitspec is a file-based HTTP API testing tool. Write tests in plain-text
      <code>.http</code> files that look like actual HTTP requests. Run them
      with <strong>26 assertion operators</strong>, capture values, chain
      requests, stress-test, and mock APIs — all from one binary. No SDK. No
      GUI. No JavaScript.
    </p>

    <div>
      <a href="/quickstart">
        ⚡ Get started in 60 seconds
      </a>

      <a href="/installation">
        Install hitspec
      </a>

      <a href="https://github.com/abdul-hamid-achik/hitspec">
        ★ Star on GitHub
      </a>
    </div>

    <div>
      <span>\$</span>
      <code>brew install --cask abdul-hamid-achik/tap/hitspec</code>
    </div>

    <div>
      <div>
        <span />

        <span />

        <span />

        <span>api.http</span>
      </div>
    </div>
  </div>
</section>

<section>
  <div>
    <div>26</div>
    <div>Assertion operators</div>
  </div>

  <div>
    <div>17</div>
    <div>Built-in functions</div>
  </div>

  <div>
    <div>8</div>
    <div>Auth types</div>
  </div>

  <div>
    <div>1</div>
    <div>Binary, zero runtime deps</div>
  </div>
</section>

<section>
  <span>Why hitspec</span>
  <h2>Everything Postman does. In a text file.</h2>

  <p>
    Tests are readable <code>.http</code> files — no binary collections, no JSON
    blobs, no GUI-only workflows. Diffs are meaningful, code review works
    naturally, and your whole API test suite lives next to your code in git.
  </p>

  <div>
    <Feature icon="📝" title="Plain-text .http files" href="/concepts/file-format">
      Tests look like real HTTP requests. Compatible with the REST Client VS Code
      format, so you get syntax highlighting for free.
    </Feature>

    <Feature icon="🔍" title="26 assertion operators" href="/reference/assertion-operators">
      <code>==</code>, <code>contains</code>, <code>matches</code>, <code>exists</code>,
      <code>type</code>, <code>schema</code>, <code>snapshot</code>,
      <code>length</code>, <code>in</code>, and more.
    </Feature>

    <Feature icon="🔗" title="Captures & dependencies" href="/concepts/captures">
      Chain requests by capturing response values and controlling execution order
      with <code>@depends</code>.
    </Feature>

    <Feature icon="⚡" title="Built-in stress testing" href="/features/stress-testing">
      Load test with configurable rate, virtual users, ramp-up, and pass/fail
      thresholds. No separate tool needed.
    </Feature>

    <Feature icon="🎭" title="Mock server" href="/features/mock-server">
      Spin up a mock API from your <code>.http</code> files for frontend
      development and testing.
    </Feature>

    <Feature icon="🗄️" title="Database assertions" href="/features/database-assertions">
      Verify database state after requests with <code>>>>db</code>
      blocks. PostgreSQL, MySQL, and SQLite.
    </Feature>

    <Feature icon="🔑" title="8 authentication types" href="/features/authentication">
      Bearer, Basic, API Key, Digest, AWS Signature v4, OAuth2, and more.
    </Feature>

    <Feature icon="🔌" title="Import & export" href="/reference/import-export">
      Import from curl, Insomnia, OpenAPI, and Postman. Export requests as
      curl, HTTPie, Python, fetch, Go, Ruby, or wget.
    </Feature>

    <Feature icon="🖥️" title="Interactive studio (TUI)" href="/studio">
      A keyboard-first terminal UI to edit, run, and inspect requests — like
      Postman, but file-backed. Run <code>hitspec studio</code>.
    </Feature>
  </div>
</section>

<section>
  <span>See it in action</span>
  <h2>A Postman-class client, in your terminal</h2>

  <p>
    <code>hitspec studio</code> opens a keyboard-first workspace: a file tree,
    a syntax-highlighted source editor you can save inline, a tabbed response
    viewer (Body / Headers / Assertions / Timing / Captures), a command palette,
    an environment switcher, and dedicated screens for stress, mock, contract,
    record, and history. Everything the REST <code>--api-only</code> server does,
    driven by one in-process manager.
  </p>

  <div>
    <a href="/studio">Explore the studio</a>
    <a href="/guides/api-client-manager">How it works</a>
  </div>
</section>

<section>
  <span>Install</span>
  <h2>Running in under a minute</h2>

  <p>
    One binary, no runtime dependencies. Pick whichever install path you prefer.
  </p>

  <Tabs>
    <Tab title="Homebrew (macOS / Linux)">
      ```bash theme={null}
      brew install --cask abdul-hamid-achik/tap/hitspec
      ```
    </Tab>

    <Tab title="Go">
      ```bash theme={null}
      go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@latest
      ```
    </Tab>

    <Tab title="Binary download">
      Grab a pre-built archive from the
      [Releases page](https://github.com/abdul-hamid-achik/hitspec/releases/latest),
      extract it, and put it on your <code>PATH</code>. See the
      [installation guide](/installation) for platform-specific steps.
    </Tab>
  </Tabs>

  <p>
    Then write a test and run it:
  </p>

  ```bash theme={null}
  hitspec run api.http
  ```
</section>

<section>
  <span>How it compares</span>
  <h2>hitspec vs. the usual suspects</h2>

  <p>
    A full test framework on top of plain HTTP requests — without a GUI,
    collections export, or JavaScript.
  </p>

  <div>
    <table>
      <thead>
        <tr>
          <th>Capability</th>
          <th>hitspec</th>
          <th>Postman / newman</th>
          <th>REST Client</th>
          <th>Hurl</th>
          <th>k6</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Plain-text, git-friendly files</td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>
        </tr>

        <tr>
          <td>Assertions + captures + dependencies</td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>
        </tr>

        <tr>
          <td>Built-in stress / load testing</td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <Yes />
          </td>
        </tr>

        <tr>
          <td>Mock server from test files</td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>
        </tr>

        <tr>
          <td>Database assertions</td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>
        </tr>

        <tr>
          <td>Interactive terminal client (TUI)</td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>
        </tr>

        <tr>
          <td>No JavaScript / SDK required</td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>
        </tr>

        <tr>
          <td>Single binary, zero runtime deps</td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>

          <td>
            <No />
          </td>

          <td>
            <Yes />
          </td>

          <td>
            <No />
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</section>

<section>
  <span>FAQ</span>
  <h2>Frequently asked questions</h2>

  <p>
    Everything you need to decide whether hitspec is the right API testing tool
    for your team.
  </p>

  <AccordionGroup>
    <Accordion title="What is hitspec?">
      hitspec is an open-source, file-based HTTP API testing tool. You write API
      tests as plain-text <code>.http</code> files that look like real HTTP
      requests, and hitspec executes them, evaluates assertions, captures values
      for chaining, and produces CI-friendly output. There is no SDK, no GUI, and
      no JavaScript — just text files you can read, diff, and check into git.
    </Accordion>

    <Accordion title="Is hitspec a good Postman alternative?">
      Yes. hitspec covers the same ground — requests, environments, auth,
      assertions, and an interactive client (<code>hitspec studio</code>) — but
      stores everything in version-controllable plain text. There are no binary
      collections to export, no GUI-only workflows, and tests live next to your
      code so code review works naturally. See the
      [migrating from Postman guide](/guides/migrating-from-postman).
    </Accordion>

    <Accordion title="What file format does hitspec use?">
      hitspec uses <code>.http</code> (or <code>.hitspec</code>) files. The
      <code>.http</code> format is compatible with the REST Client VS Code
      extension and other HTTP file tools, so you get syntax highlighting for
      free. hitspec adds assertion blocks (<code>>>></code> /
      <code>\<\<\<</code>), captures (<code>>>>capture</code>),
      request dependencies (<code>@depends</code>), and metadata directives on
      top. See the [file format reference](/concepts/file-format).
    </Accordion>

    <Accordion title="Can hitspec do load and stress testing?">
      Yes. Built-in stress testing is available with the <code>--stress</code>
      flag and inside the studio stress screen. You can configure request rate,
      virtual users, ramp-up, and pass/fail thresholds, and export metrics to
      Prometheus or Datadog. No separate load-testing tool is required. See the
      [stress testing guide](/features/stress-testing).
    </Accordion>

    <Accordion title="How does hitspec compare to Hurl and k6?">
      Like Hurl, hitspec uses plain-text, no-JavaScript test files. Unlike Hurl,
      hitspec adds a built-in mock server, database assertions, an interactive
      terminal client, and import/export to curl, Postman, Insomnia, and
      OpenAPI. Like k6, hitspec has built-in load testing — but with a simpler,
      HTTP-file syntax instead of JavaScript scripting. See the comparison
      table above.
    </Accordion>

    <Accordion title="Is hitspec free and open source?">
      Yes. hitspec is MIT-licensed and developed in the open on
      [GitHub](https://github.com/abdul-hamid-achik/hitspec). You can install it
      via Homebrew, <code>go install</code>, or a pre-built binary from the
      [releases page](https://github.com/abdul-hamid-achik/hitspec/releases).
    </Accordion>

    <Accordion title="Does hitspec work in CI/CD pipelines?">
      Yes. hitspec has an official GitHub Action, emits JUnit XML, TAP, JSON,
      and HTML output, respects environment variables, and returns exit codes
      that map to test outcomes. See the
      [CI/CD guide](/guides/ci-cd-pipeline) and
      [GitHub Actions integration](/integrations/github-actions).
    </Accordion>

    <Accordion title="Can I verify database state after an API request?">
      Yes. Use a <code>>>>db</code> block to run SQL against PostgreSQL,
      MySQL, or SQLite and assert on the results after an HTTP request. This is
      ideal for verifying side effects. See
      [database assertions](/features/database-assertions).
    </Accordion>
  </AccordionGroup>
</section>

<section>
  <h2>Write your first API test in under a minute</h2>

  <p>
    No SDK. No GUI. No JavaScript. Just plain-text <code>.http</code> files you
    can read, diff, and check into git.
  </p>

  <div>
    <a href="/quickstart">Start the quickstart →</a>
    <a href="/installation">Install hitspec</a>
  </div>
</section>


# Write and run your first API test in under a minute
Source: https://hitspec.dev/quickstart

Write a plain-text .http file with requests, assertions, and captures, then run it with hitspec. A fast first API test you can read, diff, and commit.

<Steps>
  <Step title="Create a test file">
    Create a file called `api.http`:

    ```http api.http theme={null}
    @baseUrl = https://jsonplaceholder.typicode.com

    ### Get a post
    # @name getPost

    GET {{baseUrl}}/posts/1

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

    >>>capture
    authorId from body.userId
    <<<

    ### Create a post
    # @name createPost

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

    {
      "title": "Hello hitspec",
      "body": "Testing made simple",
      "userId": 1
    }

    >>>
    expect status 201
    expect body.id exists
    <<<

    ### Get the post's author
    # @name getAuthor
    # @depends getPost

    GET {{baseUrl}}/users/{{getPost.authorId}}

    >>>
    expect status 200
    expect body.name exists
    expect body.email exists
    <<<
    ```

    This file defines three requests:

    1. **getPost** -- fetches a post, checks its fields, and captures the author's ID
    2. **createPost** -- creates a new post and checks the `201` response
    3. **getAuthor** -- runs after `getPost` and uses the captured `authorId` to fetch the author
  </Step>

  <Step title="Run the tests">
    ```bash theme={null}
    hitspec run api.http
    ```

    hitspec parses the file, executes each request in order (respecting dependencies), and evaluates all assertions.
  </Step>

  <Step title="See results">
    On success, you see a summary of passing tests:

    ```
      ✓ getPost (130ms)
      ✓ createPost (74ms)
      ✓ getAuthor (39ms)

    Tests: 3 passed, 3 total
    Time:  224ms
    ```

    If an assertion fails, hitspec shows exactly what went wrong:

    ```
      ✓ getPost (130ms)
      ✓ createPost (74ms)
      ✗ getAuthor (41ms)
        → status == (line 39)
          Expected: 200
          Actual:   404
          expected 200, got 404

    Tests: 2 passed, 1 failed, 3 total
    ```

    The output tells you which assertion failed, on which line, what value was expected, and what was actually returned.
  </Step>
</Steps>

## What Just Happened?

Let's break down the key concepts from this example:

**Variables** -- `@baseUrl` defines a reusable variable, referenced with `{{baseUrl}}`.

**Request separator** -- `###` marks the start of each request.

**Metadata** -- `# @name`, `# @depends` are directives that control behavior.

**Assertions** -- The `>>> ... <<<` block contains `expect` statements that validate the response.

**Captures** -- The `>>>capture ... <<<` block extracts values from responses (here, `authorId`) for use in later requests, referenced as `{{getPost.authorId}}`.

**Dependencies** -- `# @depends getPost` ensures `getAuthor` runs after `getPost`, so the captured `authorId` is available.

## Try it in studio

Prefer an interactive workflow? Open the same file in the terminal UI:

```bash theme={null}
hitspec studio api.http
```

Studio lets you edit, run, and inspect requests in a tabbed response viewer, with
dedicated screens for stress, mock, contract, record, history, and more -- all
keyboard-first. See the [Studio guide](/studio).

## Next Steps

<Columns>
  <Card title="Installation" icon="download" href="/installation">
    Install hitspec via Homebrew, Go, or binary download.
  </Card>

  <Card title="Studio (Terminal UI)" icon="terminal" href="/studio">
    Edit, run, and inspect requests interactively in the terminal.
  </Card>

  <Card title="Editor Setup" icon="code" href="/editor-setup">
    Get syntax highlighting and completions in your editor.
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/file-format">
    Learn the file format, variables, assertions, and captures.
  </Card>
</Columns>


# Assertion Operators
Source: https://hitspec.dev/reference/assertion-operators

Complete reference for all 26 assertion operators in hitspec, with syntax and examples for each.

hitspec provides 26 assertion operators organized into six categories. Every assertion follows this pattern:

```
expect <subject> <operator> <value>
```

When the operator is `==`, you can omit it: `expect status 200` is shorthand for `expect status == 200`. An unknown operator (`contians`, `=`, `equals`) is a parse error with a suggestion, never a silent `==`; see [Assertions](/concepts/assertions) for the full expected-value grammar (a JSON literal, a `/regex/flags`, or the rest of the line verbatim).

***

## Equality and Comparison (6 operators)

| Operator | Syntax | Description |
| - | - | - |
| `==` | `expect status == 200` | Equals (deep equality for objects/arrays, numeric coercion for numbers) |
| `!=` | `expect body.error != null` | Not equals |
| `>` | `expect body.count > 0` | Greater than (numeric) |
| `>=` | `expect body.count >= 1` | Greater than or equal (numeric) |
| `<` | `expect duration < 1000` | Less than (numeric) |
| `<=` | `expect duration <= 500` | Less than or equal (numeric) |

```http theme={null}
>>>
expect status == 200
expect duration < 500
expect body.total > 0
expect body.page >= 1
expect body.errors != null
<<<
```

<Note>
  Numeric comparison coerces strings to numbers when possible. `"42"` and `42` are considered equal by `==`. Objects and arrays are compared as JSON (key order is ignored, numbers compare as numbers). `== null` matches only a real JSON `null`; a missing field is not null (use `!exists` for "absent or null").
</Note>

***

## String Operators (5 operators)

| Operator | Syntax | Description |
| - | - | - |
| `contains` | `expect body contains "success"` | Actual value contains the expected substring |
| `!contains` | `expect body !contains "error"` | Actual value does not contain the substring |
| `startsWith` | `expect body.url startsWith "https"` | Actual value starts with the expected prefix |
| `endsWith` | `expect body.email endsWith ".com"` | Actual value ends with the expected suffix |
| `matches` | `expect body.id matches /^\d+$/` | Actual value matches a regular expression |

```http theme={null}
>>>
expect body.email endsWith "@example.com"
expect body.website startsWith "https"
expect body.bio !contains "<script>"
expect body.phone matches /^\+?[\d\s\-()]+$/
<<<
```

<Note>
  Regular expressions use Go's `regexp` syntax and are enclosed in forward slashes: `/pattern/` or `/pattern/i` (flags `i`, `m`, `s`, `U`).
</Note>

On a JSON response, `contains`, `startsWith`, `endsWith` and `matches` applied to the whole `body` see the raw JSON text; applied to an object or array they see its compact JSON encoding.

***

## Existence and Type (3 operators)

| Operator | Syntax | Description |
| - | - | - |
| `exists` | `expect body.id exists` | Value is present and not null |
| `!exists` | `expect body.error !exists` | Value is absent or null |
| `type` | `expect body.items type array` | Value matches the expected type |

For `header` subjects, `exists` means the header is present in the response (an empty value still counts) and `!exists` means it is absent.

Supported type values: `null`, `boolean`, `number`, `string`, `array`, `object`. `expect body.deletedAt type null` passes for a JSON `null` and fails for an absent field.

```http theme={null}
>>>
expect body.id exists
expect body.name type string
expect body.age type number
expect body.active type boolean
expect body.tags type array
expect body.address type object
expect body.deletedAt !exists
<<<
```

***

## Length Operators (5 operators)

| Operator | Syntax | Description |
| - | - | - |
| `length` | `expect body.items length 10` | Length equals exact value |
| `length >` | `expect body.items length > 0` | Length greater than |
| `length >=` | `expect body.items length >= 1` | Length greater than or equal |
| `length <` | `expect body.items length < 100` | Length less than |
| `length <=` | `expect body.items length <= 50` | Length less than or equal |

Works on strings (counting characters, so `"日本語"` has length 3), arrays, and objects (counts keys).

```http theme={null}
>>>
expect body.users length > 0
expect body.users length <= 100
expect body.name length >= 1
<<<
```

***

## Array Operators (5 operators)

| Operator | Syntax | Description |
| - | - | - |
| `includes` | `expect body.tags includes "admin"` | Array contains the value |
| `!includes` | `expect body.tags !includes "test"` | Array does not contain the value |
| `in` | `expect status in [200, 201, 204]` | Value is one of the listed values |
| `!in` | `expect status !in [400, 404, 500]` | Value is not one of the listed values |
| `each` | `expect body.items each type object` | Assertion applied to every array element |

### includes / !includes

Checks whether an array contains (or does not contain) a specific value:

```http theme={null}
>>>
expect body.permissions includes "read"
expect body.permissions !includes "superadmin"
<<<
```

### in / !in

Checks whether a scalar value is a member of a set. List values in square brackets:

```http theme={null}
>>>
expect status in [200, 201]
expect body.role in ["admin", "editor", "viewer"]
expect body.status !in ["deleted", "banned"]
<<<
```

### each

Applies an assertion to every element in an array. Useful for validating list shapes. After `each` write an operator and a value, optionally preceded by a path inside the element:

```http theme={null}
>>>
expect body.users each type object
expect body.users each > 0
expect body.users each body.id exists
expect body.users each email matches /^.+@.+\..+$/
<<<
```

`body` (or a leading `.`) names the element itself. An empty array passes. You can also use `each` with an operator/value map:

```http theme={null}
>>>
expect body.items each {"operator": "type", "value": "object"}
<<<
```

***

## Schema and Snapshot (2 operators)

| Operator | Syntax | Description |
| - | - | - |
| `schema` | `expect body schema ./schema.json` | Validate against a JSON Schema file |
| `snapshot` | `expect body snapshot "name"` | Compare against a saved snapshot |

### schema

Validates the response body against a JSON Schema file. File paths are relative to the `.http` file.

```http theme={null}
>>>
expect body schema ./schemas/user.json
<<<
```

### snapshot

Compares the response body against a previously saved baseline. A plain run never creates a snapshot: if none exists the assertion fails with "snapshot does not exist (run with --update-snapshots to create)". Create the baseline once with `--update-snapshots`; after that, differences cause failure.

```http theme={null}
>>>
expect body snapshot "user-profile"
<<<
```

Create snapshots, or update them when the response intentionally changes:

```bash theme={null}
hitspec run tests/ --update-snapshots
```

***

## Quick Reference

| # | Operator | Category | Example |
| - | - | - | - |
| 1 | `==` | Equality | `expect status == 200` |
| 2 | `!=` | Equality | `expect body.error != null` |
| 3 | `>` | Comparison | `expect body.count > 0` |
| 4 | `>=` | Comparison | `expect body.count >= 1` |
| 5 | `<` | Comparison | `expect duration < 1000` |
| 6 | `<=` | Comparison | `expect duration <= 500` |
| 7 | `contains` | String | `expect body contains "ok"` |
| 8 | `!contains` | String | `expect body !contains "error"` |
| 9 | `startsWith` | String | `expect body.url startsWith "https"` |
| 10 | `endsWith` | String | `expect body.email endsWith ".com"` |
| 11 | `matches` | String | `expect body.id matches /^\d+$/` |
| 12 | `exists` | Existence | `expect body.id exists` |
| 13 | `!exists` | Existence | `expect body.error !exists` |
| 14 | `type` | Type | `expect body.items type array` |
| 15 | `length` | Length | `expect body.items length 10` |
| 16 | `length >` | Length | `expect body.items length > 0` |
| 17 | `length >=` | Length | `expect body.items length >= 1` |
| 18 | `length <` | Length | `expect body.items length < 100` |
| 19 | `length <=` | Length | `expect body.items length <= 50` |
| 20 | `includes` | Array | `expect body.tags includes "admin"` |
| 21 | `!includes` | Array | `expect body.tags !includes "test"` |
| 22 | `in` | Array | `expect status in [200, 201]` |
| 23 | `!in` | Array | `expect status !in [400, 500]` |
| 24 | `each` | Array | `expect body.items each type object` |
| 25 | `schema` | Validation | `expect body schema ./schema.json` |
| 26 | `snapshot` | Validation | `expect body snapshot "name"` |


# Assertion Subjects
Source: https://hitspec.dev/reference/assertion-subjects

Reference for all assertion subjects: status, duration, headers, body paths, and percentiles.

The assertion subject is the left-hand side of every `expect` statement. It specifies which part of the HTTP response to validate.

```
expect <subject> <operator> <value>
```

***

## status

The HTTP response status code as an integer.

```http theme={null}
>>>
expect status 200
expect status != 500
expect status in [200, 201, 204]
<<<
```

***

## duration

The response time in milliseconds (float). Measured from the start of the request to the end of the response.

```http theme={null}
>>>
expect duration < 500
expect duration <= 1000
<<<
```

***

## Percentile Subjects

For stress testing, percentile subjects represent latency distribution:

| Subject | Description |
| - | - |
| `p50` | 50th percentile (median) response time in ms |
| `p95` | 95th percentile response time in ms |
| `p99` | 99th percentile response time in ms |

```http theme={null}
>>>
expect p95 < 200
expect p99 < 500
<<<
```

<Note>
  For single (non-stress) requests, `p50`, `p95`, and `p99` all equal the `duration` value. These subjects are most useful in stress testing mode.
</Note>

***

## header

Response header values. Use `header <name>` to access a specific header.

```http theme={null}
>>>
expect header Content-Type contains "application/json"
expect header X-Request-Id exists
expect header X-RateLimit-Remaining > 0
expect header Cache-Control contains "no-cache"
<<<
```

Header names are case-insensitive as per HTTP specification.

For headers, `exists` means the header is present in the response (even with an
empty value) and `!exists` means it is absent:

```http theme={null}
>>>
expect header X-Request-Id exists
expect header X-Debug !exists
<<<
```

Using `header` without a name returns all headers as an object:

```http theme={null}
>>>
expect header exists
<<<
```

***

## body

The full response body. If the response is JSON, `body` gives you the parsed JSON value. Otherwise, it returns the raw body as a string.

A response counts as JSON when its `Content-Type` is `application/json`, `text/json` or any `+json` type (`application/problem+json`, `application/vnd.api+json`, ...), with or without parameters such as `; charset=utf-8`. A path into a response that is not JSON (`body.x`, `body[0]`, `jsonpath ...`) **fails with "response body is not JSON"**; it never falls back to the raw text, so `body.x exists` cannot pass on an HTML error page. The same applies to a JSON `Content-Type` with an invalid body.

With `contains`, `startsWith`, `endsWith` and `matches`, the whole `body` of a JSON response is matched as its raw JSON text.

```http theme={null}
>>>
expect body contains "success"
expect body type object
expect body length > 0
<<<
```

### JSON Path Access

Use dot notation to access nested JSON fields:

```http theme={null}
>>>
expect body.user.name == "John"
expect body.user.email endsWith "@example.com"
expect body.user.roles type array
<<<
```

### Array Index Access

Use bracket notation for array indices:

```http theme={null}
>>>
expect body[0].id exists
expect body.users[0].name == "Admin"
expect body.items[2].price > 0
<<<
```

### Nested Paths

Combine dot and bracket notation for deep access:

```http theme={null}
>>>
expect body.data.users[0].address.city == "New York"
expect body.results[0].tags[1] == "featured"
<<<
```

### Counts and Queries

Paths use [GJSON](https://github.com/tidwall/gjson) syntax, so `.#` counts array elements and `.#(...)` selects by a condition. The same paths work in [captures](/concepts/captures):

```http theme={null}
>>>
expect body.items.# == 3
expect body.items.#(name=="Jane Doe").id == 1
expect body.items.#(price>10)#.name length 2
expect body.items[*].id == [1, 2, 3]
<<<
```

`[*]` selects the member of every element (`items.#.id`). A path that matches nothing is *absent*: `exists` is false and most operators fail (see [null versus absent](/concepts/assertions#null-versus-absent)).

### Implicit body Prefix

When the subject doesn't match a known keyword (`status`, `duration`, `header`, `jsonpath`, etc.), hitspec treats it as a body path. These are equivalent:

```http theme={null}
>>>
expect body.user.name == "John"
expect user.name == "John"
<<<
```

***

## jsonpath

Alternative to body dot-notation using JSONPath-style expressions:

```http theme={null}
>>>
expect jsonpath $.users[0].id exists
expect jsonpath $.data.count > 0
expect jsonpath $.users[*].name includes "Admin"
<<<
```

The supported subset is `$` (the whole body), `.name`, `['name']`, `[0]` and `[*]`. Recursive descent (`..`), filters (`[?(...)]`), slices and unions are not supported and fail with an error rather than being guessed at. For queries use the GJSON `#(...)` form on `body.<path>`.

<Tip>
  For most cases, the `body.path` syntax is simpler and recommended. Use `jsonpath` when you need explicit JSONPath semantics.
</Tip>

***

## Quick Reference

| Subject | Type | Example |
| - | - | - |
| `status` | integer | `expect status 200` |
| `duration` | float (ms) | `expect duration < 500` |
| `p50` | float (ms) | `expect p50 < 100` |
| `p95` | float (ms) | `expect p95 < 200` |
| `p99` | float (ms) | `expect p99 < 500` |
| `header <name>` | string | `expect header Content-Type contains json` |
| `body` | any | `expect body contains "ok"` |
| `body.<path>` | any | `expect body.user.id exists` |
| `body[n]` | any | `expect body[0].id == 1` |
| `jsonpath <expr>` | any | `expect jsonpath $.users[0].id exists` |


# Authentication Types
Source: https://hitspec.dev/reference/auth-types

Reference for all 8 authentication methods supported by hitspec's @auth directive.

hitspec supports 8 authentication methods through the `# @auth` metadata directive. Instead of manually constructing `Authorization` headers, declare your auth method and hitspec handles the rest.

## Syntax

```
# @auth <method> <params...>
```

All parameters support `{{variable}}` interpolation.

Separate the parameters with commas (`basic alice, s3cret`) or with whitespace (`basic alice s3cret`). If the line contains a comma outside `{{ ... }}` it is split on commas, so a value may then contain spaces; a comma inside `{{ ... }}` (for example `{{$random(1, 5)}}`) never splits. For the OAuth2 grants, every parameter after the required ones is part of the scope list.

hitspec checks the method name and the number of parameters when it parses the file. An unknown method (`@auth magic foo`) or a wrong parameter count is a parse error: `hitspec validate` reports it and exits with code 2 instead of sending the request without credentials.

***

## Methods

### bearer

Sends an `Authorization: Bearer <token>` header.

```http theme={null}
# @auth bearer {{token}}
```

| Parameter | Description |
| - | - |
| `token` | The bearer token value |

**Generated header:** `Authorization: Bearer <token>`

***

### basic

Sends a Base64-encoded `Authorization: Basic <credentials>` header.

```http theme={null}
# @auth basic {{username}}, {{password}}
```

| Parameter | Description |
| - | - |
| `username` | Username |
| `password` | Password |

**Generated header:** `Authorization: Basic <base64(username:password)>`

***

### apiKey

Sends the API key as a custom request header.

```http theme={null}
# @auth apiKey X-API-Key, {{apiKey}}
```

| Parameter | Description |
| - | - |
| `headerName` | Name of the header to set |
| `value` | API key value |

**Generated header:** `<headerName>: <value>`

***

### apiKeyQuery

Appends the API key as a URL query parameter.

```http theme={null}
# @auth apiKeyQuery api_key, {{apiKey}}
```

| Parameter | Description |
| - | - |
| `paramName` | Query parameter name |
| `value` | API key value |

**Effect:** Appends `?api_key=<value>` to the request URL.

***

### digest

HTTP Digest authentication. hitspec handles the challenge-response handshake automatically.

```http theme={null}
# @auth digest {{username}}, {{password}}
```

| Parameter | Description |
| - | - |
| `username` | Username |
| `password` | Password |

***

### aws

Signs requests using AWS Signature Version 4 for AWS services or compatible APIs (e.g., MinIO, LocalStack).

```http theme={null}
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}
```

With temporary credentials, add the session token as a fifth argument:

```http theme={null}
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}, {{sessionToken}}
```

| Parameter | Required | Description |
| - | - | - |
| `accessKey` | Yes | AWS Access Key ID |
| `secretKey` | Yes | AWS Secret Access Key |
| `region` | Yes | AWS region (e.g., `us-east-1`) |
| `service` | Yes | AWS service name (e.g., `s3`, `execute-api`) |
| `sessionToken` | No | Session token of temporary credentials. Sent as `X-Amz-Security-Token` and signed |

If the fifth argument is left out and the access key equals `$AWS_ACCESS_KEY_ID`, hitspec uses `$AWS_SESSION_TOKEN` when it is set. A `>>>multipart` body is signed over the exact bytes sent.

***

### oauth2 client\_credentials

Fetches an access token using the OAuth2 Client Credentials grant, then sends it as a Bearer token.

```http theme={null}
# @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2
```

| Parameter | Required | Description |
| - | - | - |
| `tokenUrl` | Yes | OAuth2 token endpoint |
| `clientId` | Yes | Application client ID |
| `clientSecret` | Yes | Application client secret |
| `scopes` | No | Comma-separated list of scopes |

***

### oauth2 password

Fetches an access token using the OAuth2 Resource Owner Password Credentials grant.

```http theme={null}
# @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2
```

| Parameter | Required | Description |
| - | - | - |
| `tokenUrl` | Yes | OAuth2 token endpoint |
| `clientId` | Yes | Application client ID |
| `clientSecret` | Yes | Application client secret |
| `username` | Yes | Resource owner username |
| `password` | Yes | Resource owner password |
| `scopes` | No | Comma-separated list of scopes |

***

## Quick Reference

| Method | Syntax | Params |
| - | - | - |
| Bearer | `# @auth bearer <token>` | 1 |
| Basic | `# @auth basic <user>, <pass>` | 2 |
| API Key (Header) | `# @auth apiKey <header>, <value>` | 2 |
| API Key (Query) | `# @auth apiKeyQuery <param>, <value>` | 2 |
| Digest | `# @auth digest <user>, <pass>` | 2 |
| AWS Sig v4 | `# @auth aws <key>, <secret>, <region>, <service>[, <sessionToken>]` | 4-5 |
| OAuth2 Client Creds | `# @auth oauth2 client_credentials <url>, <id>, <secret>, <scopes>` | 3-4 |
| OAuth2 Password | `# @auth oauth2 password <url>, <id>, <secret>, <user>, <pass>, <scopes>` | 5-6 |

***

## Using Auth with Captures

Capture a token from a login response and use it in subsequent requests:

```http theme={null}
### Login
# @name login

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

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

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

### Protected resource
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<
```

<Tip>
  Store credentials in environment variables or `hitspec.yaml` environments to keep them out of your test files. Reference them with `{{$env(VAR)}}` or `{{variableName}}`.
</Tip>


# Built-in Functions
Source: https://hitspec.dev/reference/builtin-functions

Reference for all 17 built-in functions available in hitspec variable interpolation.

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

```http theme={null}
POST {{baseUrl}}/users
Content-Type: application/json

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

***

## Identity and Randomness

### \$uuid()

Generates a random UUID v4 string.

```http theme={null}
X-Request-Id: {{$uuid()}}
```

**Returns:** `string` -- e.g., `550e8400-e29b-41d4-a716-446655440000`

***

### \$random(min, max)

Generates a random integer between `min` and `max` (inclusive). Defaults to `0`-`100` when called without arguments.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `min` | integer | `0` | Minimum value (inclusive) |
| `max` | integer | `100` | Maximum value (inclusive) |

```http theme={null}
{
  "quantity": {{$random(1, 10)}},
  "score": {{$random(0, 100)}}
}
```

**Returns:** `integer`

***

### \$randomString(length)

Generates a random string of mixed-case alphanumeric characters.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `length` | integer | `16` | Length of the generated string |

```http theme={null}
{
  "password": "{{$randomString(32)}}"
}
```

**Returns:** `string` -- e.g., `aB3kL9mNpQ7rS2tU`

***

### \$randomAlphanumeric(length)

Generates a random alphanumeric string. Functionally identical to `$randomString`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `length` | integer | `8` | Length of the generated string |

**Returns:** `string`

***

### \$randomEmail()

Generates a random email address.

```http theme={null}
{
  "email": "{{$randomEmail()}}"
}
```

**Returns:** `string` -- e.g., `abcdefgh@klmnop.com`

***

## Date and Time

### \$now()

Returns the current UTC date and time in RFC 3339 format.

```http theme={null}
{
  "createdAt": "{{$now()}}"
}
```

**Returns:** `string` -- e.g., `2026-02-09T15:04:05Z`

***

### \$timestamp()

Returns the current Unix timestamp in seconds.

```http theme={null}
X-Timestamp: {{$timestamp()}}
```

**Returns:** `integer` -- e.g., `1707490800`

***

### \$timestampMs()

Returns the current Unix timestamp in milliseconds.

```http theme={null}
{
  "sentAt": {{$timestampMs()}}
}
```

**Returns:** `integer` -- e.g., `1707490800000`

***

### \$date(format)

Returns the current UTC date formatted with a custom Go time layout. Defaults to `2006-01-02` (ISO date).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `format` | string | `2006-01-02` | Go reference time layout |

```http theme={null}
{
  "date": "{{$date()}}",
  "datetime": "{{$date(2006-01-02T15:04:05Z)}}"
}
```

**Returns:** `string` -- e.g., `2026-02-09`

<Note>
  Go time layouts use the reference date `Mon Jan 2 15:04:05 MST 2006`. For example, `{{$date(2006-01-02)}}` produces `2026-02-09`, and `{{$date(01/02/2006)}}` produces `02/09/2026`.
</Note>

***

## Encoding and Hashing

### \$base64(value)

Base64-encodes the given string.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | String to encode |

```http theme={null}
Authorization: Basic {{$base64(admin:secret)}}
```

**Returns:** `string` -- e.g., `YWRtaW46c2VjcmV0`

***

### \$base64Decode(value)

Decodes a Base64-encoded string.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | Base64 string to decode |

**Returns:** `string` -- Returns empty string on decode error.

***

### \$md5(value)

Returns the MD5 hex digest of the given string.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | String to hash |

```http theme={null}
{
  "checksum": "{{$md5(file-contents)}}"
}
```

**Returns:** `string` -- 32-character hex string

***

### \$sha256(value)

Returns the SHA-256 hex digest of the given string.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | String to hash |

**Returns:** `string` -- 64-character hex string

***

### \$urlEncode(value)

URL-encodes the given string (percent-encoding).

| Parameter | Type | Description |
| - | - | - |
| `value` | string | String to encode |

```http theme={null}
GET {{baseUrl}}/search?q={{$urlEncode(hello world)}}
```

**Returns:** `string` -- e.g., `hello+world`

***

### \$urlDecode(value)

URL-decodes a percent-encoded string.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | URL-encoded string to decode |

**Returns:** `string` -- Returns the original string on decode error.

***

## Utilities

### \$json(value)

Passes through the value as-is. Useful for embedding raw JSON strings in variable interpolation contexts.

| Parameter | Type | Description |
| - | - | - |
| `value` | string | JSON string to pass through |

**Returns:** `string`

***

### \$env(name, default)

Reads a system environment variable. Returns the optional default value if the variable is not set or empty.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | string | *(required)* | Environment variable name |
| `default` | string | `""` | Fallback value |

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

**Returns:** `string`

<Tip>
  Use `$env()` to keep secrets out of your test files. Store API tokens, passwords, and connection strings in environment variables and reference them with `{{$env(VAR_NAME)}}`.
</Tip>

***

## Quick Reference Table

| Function | Arguments | Default Args | Returns |
| - | - | - | - |
| `$now()` | -- | -- | RFC 3339 datetime |
| `$timestamp()` | -- | -- | Unix seconds |
| `$timestampMs()` | -- | -- | Unix milliseconds |
| `$uuid()` | -- | -- | UUID v4 string |
| `$random(min, max)` | min, max | 0, 100 | Random integer |
| `$randomString(len)` | length | 16 | Random string |
| `$randomAlphanumeric(len)` | length | 8 | Random string |
| `$randomEmail()` | -- | -- | Random email |
| `$base64(val)` | value | -- | Base64 encoded |
| `$base64Decode(val)` | value | -- | Decoded string |
| `$md5(val)` | value | -- | MD5 hex digest |
| `$sha256(val)` | value | -- | SHA-256 hex digest |
| `$urlEncode(val)` | value | -- | URL-encoded string |
| `$urlDecode(val)` | value | -- | URL-decoded string |
| `$date(fmt)` | format | `2006-01-02` | Formatted date |
| `$json(val)` | value | -- | Passthrough string |
| `$env(name, def)` | name, default | -- | Env var value |


# hitspec completion
Source: https://hitspec.dev/reference/completion

Generate shell completion scripts for bash, zsh, fish, and PowerShell.

# hitspec completion

Generate a shell completion script so `hitspec` can tab-complete commands, flags,
and arguments.

```bash theme={null}
hitspec completion <shell>
```

`<shell>` is one of `bash`, `zsh`, `fish`, or `powershell`. The command prints the
script to stdout; redirect or source it as shown below.

## Setup

<Tabs>
  <Tab title="Bash">
    Load completions for the current session:

    ```bash theme={null}
    source <(hitspec completion bash)
    ```

    Load them for every session:

    ```bash theme={null}
    # Linux
    hitspec completion bash > /etc/bash_completion.d/hitspec

    # macOS (Homebrew)
    hitspec completion bash > $(brew --prefix)/etc/bash_completion.d/hitspec
    ```

    <Note>Bash completions require the `bash-completion` package to be installed.</Note>
  </Tab>

  <Tab title="Zsh">
    If completion isn't already enabled, add this once to `~/.zshrc`:

    ```bash theme={null}
    echo "autoload -U compinit; compinit" >> ~/.zshrc
    ```

    Then install the completion (start a new shell afterward):

    ```bash theme={null}
    hitspec completion zsh > "${fpath[1]}/_hitspec"
    ```
  </Tab>

  <Tab title="Fish">
    Load completions for the current session:

    ```bash theme={null}
    hitspec completion fish | source
    ```

    Load them for every session:

    ```bash theme={null}
    hitspec completion fish > ~/.config/fish/completions/hitspec.fish
    ```
  </Tab>

  <Tab title="PowerShell">
    Load completions for the current session:

    ```powershell theme={null}
    hitspec completion powershell | Out-String | Invoke-Expression
    ```

    To load them for every session, add the line above to your PowerShell profile.
  </Tab>
</Tabs>

<Tip>
  If you installed hitspec with Homebrew, completions for the shells Homebrew
  manages are typically wired up automatically.
</Tip>


# Configuration Reference
Source: https://hitspec.dev/reference/configuration

Complete reference for hitspec.yaml configuration file options with defaults and examples.

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](#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:

```bash theme={null}
hitspec init
```

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

***

## Full Configuration Reference

```yaml theme={null}
# 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](/features/tls-and-cookies).

### Headers

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

```yaml theme={null}
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 |

<Note>
  `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.
</Note>

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

```yaml theme={null}
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:

```yaml theme={null}
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`:

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
hitspec run api.http --stress --profile load
```

***

## Config File Search

hitspec picks the config file in this order:

1. the path given with `--config` (or `HITSPEC_CONFIG`) -- used as is;
2. 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:

```text theme={null}
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:

1. a command-line flag (for example `--timeout`),
2. a `HITSPEC_*` environment variable,
3. `hitspec.yaml`,
4. 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:

```bash theme={null}
# 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
```


# hitspec contract & diff
Source: https://hitspec.dev/reference/contract-diff

Contract testing against live providers and comparing test results

# hitspec contract

Verify API contracts against a live provider.

```bash theme={null}
hitspec contract verify <contracts-dir> [flags]
```

## Arguments

| Argument | Description |
| - | - |
| `<contracts-dir>` | Directory containing contract `.http` files (or a single file) |

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--provider` | `-p` | Provider URL (required) | |
| `--state-handler` | | Path to a state handler script | |
| `--verbose` | `-v` | Enable verbose output | `false` |

## Contract Annotations

Define contract metadata using annotations in your `.http` files:

```http theme={null}
### Get User
# @name getUser
# @contract.provider UserService
# @contract.state "user exists with id 1"
GET {{provider}}/users/1

>>>
expect status == 200
expect body.id == 1
expect body.name type string
<<<
```

| Annotation | Description |
| - | - |
| `@contract.provider` | Name of the provider service |
| `@contract.state` | Provider state required for this interaction |

## State Handler

The `--state-handler` flag specifies a script that sets up provider state before each interaction. The script receives the state description as an argument:

```bash theme={null}
#!/bin/bash
# setup-states.sh
case "$1" in
  "user exists with id 1")
    curl -s -X POST http://localhost:3000/_setup -d '{"user_id": 1}'
    ;;
  "no users exist")
    curl -s -X POST http://localhost:3000/_reset
    ;;
esac
```

## Examples

<CodeGroup>
  ```bash Basic verification theme={null}
  hitspec contract verify contracts/ --provider http://localhost:3000
  ```

  ```bash With state handler theme={null}
  hitspec contract verify contracts/ \
    --provider http://localhost:3000 \
    --state-handler ./setup-states.sh
  ```

  ```bash Verbose output theme={null}
  hitspec contract verify contracts/ --provider http://localhost:3000 -v
  ```
</CodeGroup>

### Sample Output

```
Contract Verification Results

contracts/user-service.http
  + getUser [passed] (45ms)
  + createUser [passed] (120ms)
  x deleteUser [failed] (89ms)
    -> status ==
      Expected: 204
      Actual:   404

Summary
  Contracts: 1 file(s)
  Interactions: 2 passed, 1 failed, 3 total
```

## Use Cases

* **Consumer-driven contracts** -- Define what your service expects from its dependencies, then verify those contracts against the real provider.
* **API versioning** -- Ensure that provider changes do not break existing consumers.
* **CI/CD gates** -- Run contract verification as part of the provider's deployment pipeline.

***

# hitspec diff

Compare two JSON test result files to identify regressions, improvements, and changes between test runs.

```bash theme={null}
hitspec diff <results1.json> <results2.json> [flags]
```

## Arguments

| Argument | Description |
| - | - |
| `<results1.json>` | Baseline test results (JSON output from `hitspec run --output json`) |
| `<results2.json>` | Current test results to compare against the baseline |

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--output` | `-o` | Output format: `console`, `json`, `html` | `console` |
| `--threshold` | | Fail if any test is slower by this percentage (e.g., `10%`) | |

## How It Works

The diff command compares tests by name and file, then categorizes each as:

| Status | Meaning |
| - | - |
| **improved** | Test now passes (previously failed) or is >10% faster |
| **regressed** | Test now fails (previously passed) or is >10% slower |
| **unchanged** | No significant change in status or duration |
| **skipped** | Test was skipped in the second run. Skipped tests are counted separately and never as failures |
| **new** | Test exists only in the second result file |
| **removed** | Test exists only in the first result file |

Tests are listed grouped by file (alphabetical) and in request order within each
file, so the output is identical on every run.

A test that was skipped in the first run has no baseline: its 0 ms duration is
not compared, so it is never reported as improved or regressed because of a
change in speed. If it now fails, it is reported as regressed; if it now passes,
it is unchanged. When the first run has a duration of 0 ms for a test that ran,
the percentage change is not defined, so the test is reported as unchanged and
excluded from `--threshold`.

## Generating Input Files

First, generate JSON results from your test runs:

```bash theme={null}
# Baseline run
hitspec run tests/ --output json --output-file baseline.json

# After changes
hitspec run tests/ --output json --output-file current.json
```

## Examples

<CodeGroup>
  ```bash Basic comparison theme={null}
  hitspec diff baseline.json current.json
  ```

  ```bash With regression threshold theme={null}
  hitspec diff baseline.json current.json --threshold 10%
  ```

  ```bash HTML report theme={null}
  hitspec diff baseline.json current.json --output html > diff-report.html
  ```

  ```bash JSON output theme={null}
  hitspec diff baseline.json current.json --output json
  ```
</CodeGroup>

### Console Output

```
Test Results Comparison
  File 1: baseline.json
  File 2: current.json

Summary
  Total Tests:    5
  Improved:       1
  Regressed:      1
  Unchanged:      3
  Skipped:        1

Duration
  Total (File 1): 450ms
  Total (File 2): 520ms
  Avg (File 1):   90ms
  Avg (File 2):   104ms

Test Details
  ^ healthCheck  45ms -> 42ms  -6.7%
  = login        120ms -> 125ms +4.2%
  v getProfile   89ms -> 150ms +68.5%
  + newEndpoint  (new, 30ms)
  - oldEndpoint  (removed)

x Threshold check failed (some tests exceeded 10% regression)
```

### Threshold Check

When `--threshold` is set, the command exits with a non-zero status if any test's duration increases by more than the specified percentage. This is useful for catching performance regressions in CI:

```bash theme={null}
hitspec diff baseline.json current.json --threshold 15%
# Exit code 0 if all tests are within 15% of baseline
# Exit code 1 if any test regressed by more than 15%
```

## CI/CD Integration

```yaml theme={null}
# GitHub Actions
- name: Run baseline tests
  run: hitspec run tests/ --output json --output-file baseline.json

- name: Apply changes
  run: # ... your deployment or code change steps

- name: Run current tests
  run: hitspec run tests/ --output json --output-file current.json

- name: Check for regressions
  run: hitspec diff baseline.json current.json --threshold 10%
```


# hitspec docs, studio & serve
Source: https://hitspec.dev/reference/docs-serve

Reference for the docs command, the interactive studio app, and the REST/WebSocket API server.

# hitspec docs

Output AI-readable documentation (`llms.txt`) for AI agents to learn hitspec syntax.

```bash theme={null}
hitspec docs
```

This prints the complete hitspec specification in a format optimized for LLM consumption.

***

# hitspec studio

Open the keyboard-first interactive app for working with hitspec files, right in the terminal.

```bash theme={null}
hitspec studio [file|directory] [flags]
```

## What It Provides

* Inline `.http` and `.hitspec` source editing with syntax highlighting and save
* File tree, request table, response viewer, headers, assertions, and history
* Stress, mock, contract, record, import, cookies, and settings screens
* Copy/export as curl, HTTPie, Python, fetch, or Go; workspace search; environment switching
* Command palette and keyboard-first navigation
* Real-time file watching and execution progress

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--watch` | `-w` | Watch for file changes | `true` |
| `--read-only` | | Refuse workspace and `hitspec.yaml` writes (running requests still works) | `false` |
| `--env` | `-e` | Default environment | `dev` |
| `--config` | | Path to `hitspec.yaml` | |
| `--verbose` | `-v` | Verbose logging | `false` |
| `--allow-shell` | | Allow shell command execution | `false` |
| `--allow-db` | | Allow database assertions | `false` |
| `--log-format` | | Log format: `text` or `json` | `text` |
| `--log-level` | | Log level: `debug`, `info`, `warn`, `error` | `info` |
| `--theme` | | Color theme (see below) | `Nord` |
| `--mouse` | | Capture the mouse for wheel scrolling | `false` |

## Themes

studio ships with five built-in color themes: **Nord**, **Catppuccin Mocha**, **Dracula**, **Tokyo Night**, and **Gruvbox Dark**. Switch at any time with `ctrl+t` (or the command palette), or set one at launch with `--theme`:

```bash theme={null}
hitspec studio --theme "Tokyo Night"
```

## Examples

```bash theme={null}
# Open the current directory
hitspec studio

# Open a specific workspace
hitspec studio ./tests/

# Open a single file
hitspec studio ./tests/users.http

# Run requests without changing any file
hitspec studio --read-only --env staging
```

***

# hitspec serve

Start the REST/WebSocket API server for scripts and integrations. With no flags it
opens `hitspec studio`; pass `--api-only` to run just the API with no interactive UI.

```bash theme={null}
hitspec serve [file|directory] [flags]
```

## What It Provides

* REST endpoints under `/api/v1/*`
* Realtime events over WebSocket at `/api/v1/ws`
* The same parser, runner, history store, and engines as the CLI

No web SPA is served; non-API browser routes are not part of `serve`.

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--api-only` | | REST/WebSocket API only, no interactive UI | `false` |
| `--port` | `-p` | API server port | `4000` |
| `--host` | | API bind address | `localhost` |
| `--cors` | | Enable CORS headers | `false` |
| `--watch` | `-w` | Watch for file changes | `true` |
| `--read-only` | | Refuse workspace and `hitspec.yaml` writes (running requests still works). See [Read-only mode](/reference/rest-api#read-only-mode) | `false` |
| `--env` | `-e` | Default environment | `dev` |
| `--config` | | Path to `hitspec.yaml` | |
| `--verbose` | `-v` | Verbose logging | `false` |
| `--allow-shell` | | Allow shell command execution | `false` |
| `--allow-db` | | Allow database assertions | `false` |
| `--log-format` | | Log format: `text` or `json` | `text` |
| `--log-level` | | Log level: `debug`, `info`, `warn`, `error` | `info` |
| `--parent-pid` | | Shut down when this process exits (for supervisors such as the desktop app) | `0` |
| `--api-token` | | Require a bearer token for all REST/WebSocket requests (env: `HITSPEC_API_TOKEN`, preferred because arguments are visible in `ps`) | |

## Security

The REST/WebSocket API can read/write and delete files, execute arbitrary
requests (SSRF), and run shell commands when `--allow-shell` is set. By default it
binds to `localhost` only, which limits exposure to your machine. If you bind to a
network address (`--host 0.0.0.0`) or expose the port, **set `--api-token`** (or
the `HITSPEC_API_TOKEN` env var) to require a shared secret. Clients must then send
`Authorization: Bearer <token>` (REST) or `?token=<token>` (WebSocket, which cannot
set headers on the upgrade request). Requests with a missing or mismatched token
get `401 Unauthorized`.

If the server is bound to a non-loopback address, or `--allow-shell` /
`--allow-db` is set, and you did not configure a token, hitspec generates a random
one and prints it once to stderr.

Even on localhost the server defends against web pages that try to reach it
through your browser: JSON bodies must be sent as `application/json` (`415`
otherwise), the `Host` header must be `localhost`, `127.0.0.1` or `[::1]` (`403`),
and a request with an `Origin` header must come from a localhost origin on the
server's port, or on any port with `--cors` (`403`). See
[REST API](/reference/rest-api#security-and-request-requirements).

`stateHandler` in `POST /contract/verify` runs a program, so it needs
`--allow-shell` and must point inside the workspace.

## Examples

```bash theme={null}
# Start the REST/WebSocket API for integrations
hitspec serve --api-only --port 8080 --cors

# API server bound to localhost
hitspec serve --api-only --host localhost --port 4000

# Require a token before exposing the API on the network
HITSPEC_API_TOKEN=$SECRET hitspec serve --api-only --host 0.0.0.0 --port 4000
# clients: curl -H "Authorization: Bearer $SECRET" http://host:4000/api/v1/workspace
```


# Environment Variables
Source: https://hitspec.dev/reference/environment-variables

Complete list of HITSPEC_* environment variables for configuring hitspec without flags.

All hitspec CLI flags that support environment variables are listed here. Environment variables are read at startup and can be overridden by explicit CLI flags.

## Core Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_ENV` | `--env` | `dev` | Active environment name |
| `HITSPEC_ENV_FILE` | `--env-file` | | Path to `.env` file; a file that does not exist is an error (exit code 3) |
| `HITSPEC_CONFIG` | `--config` | | Path to config file (default: the nearest `hitspec.yaml` from the working directory upward) |
| `HITSPEC_TAGS` | `--tags` | | Tags filter (comma-separated) |

## Output Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_OUTPUT` | `--output` | `console` | Output format |
| `HITSPEC_OUTPUT_FILE` | `--output-file` | | Output file path |
| `HITSPEC_QUIET` | `--quiet` | `false` | Suppress the report on stdout (failures are still listed on stderr) |
| `HITSPEC_NO_COLOR` | `--no-color` | `false` | Disable colored output |

## Execution Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_TIMEOUT` | `--timeout` | `30s` | Request timeout |
| `HITSPEC_BAIL` | `--bail` | `false` | Stop on first failure |
| `HITSPEC_PARALLEL` | `--parallel` | `false` | Run in parallel |
| `HITSPEC_CONCURRENCY` | `--concurrency` | `5` | Max concurrent requests |

## Network Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_PROXY` | `--proxy` | | HTTP proxy URL |
| `HITSPEC_INSECURE` | `--insecure` | `false` | Disable SSL validation |
| `HITSPEC_CACERT` | `--cacert` | | PEM CA bundle to trust in addition to the system roots |
| `HITSPEC_CERT` | `--cert` | | PEM client certificate for mutual TLS (needs `HITSPEC_KEY`) |
| `HITSPEC_KEY` | `--key` | | PEM private key for the client certificate |
| `HITSPEC_HTTP1` | `--http1.1` | `false` | Do not negotiate HTTP/2 |
| `HITSPEC_COOKIES` | `--cookies` | `false` | Keep a cookie jar for the run |
| `HITSPEC_MAX_RESPONSE_BYTES` | `--max-response-bytes` | `104857600` | Largest response body to read in bytes; `-1` for no limit |
| `HITSPEC_REDIRECT_FORWARD_HEADERS` | `--redirect-forward-headers` | `false` | Keep request headers on redirects to another origin |

## Metrics Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_METRICS` | `--metrics` | | Metrics export format |
| `HITSPEC_METRICS_PORT` | `--metrics-port` | `9090` | Prometheus endpoint port |
| `HITSPEC_METRICS_HOST` | `--metrics-host` | `127.0.0.1` | Interface the Prometheus endpoint binds (`0.0.0.0` exposes it) |
| `HITSPEC_METRICS_FILE` | `--metrics-file` | | JSON metrics output file |
| `DD_API_KEY` | `--datadog-api-key` | | DataDog API key |
| `DD_SITE` | `--datadog-site` | `datadoghq.com` | DataDog site |
| `DD_TAGS` | `--datadog-tags` | | DataDog tags (comma-separated) |

## Notification Variables

| Variable | Flag | Default | Description |
| - | - | - | - |
| `HITSPEC_NOTIFY` | `--notify` | | Notification service |
| `HITSPEC_NOTIFY_ON` | `--notify-on` | `failure` | When to notify |
| `SLACK_WEBHOOK` | `--slack-webhook` | | Slack webhook URL |
| `SLACK_CHANNEL` | `--slack-channel` | | Slack channel override |
| `TEAMS_WEBHOOK` | `--teams-webhook` | | Teams webhook URL |

## Usage

Set variables in your shell profile, `.env` file, or CI/CD configuration:

```bash theme={null}
# Shell profile
export HITSPEC_ENV=staging
export HITSPEC_TIMEOUT=60s
export HITSPEC_OUTPUT=json
export HITSPEC_BAIL=true
```

```bash theme={null}
# CI/CD environment
HITSPEC_ENV=staging \
HITSPEC_OUTPUT=junit \
HITSPEC_OUTPUT_FILE=results.xml \
  hitspec run tests/
```

<Note>
  Boolean variables accept `true`, `1`, or `yes` as truthy values. Everything else is falsy.
</Note>


# Exit Codes
Source: https://hitspec.dev/reference/exit-codes

Reference for all hitspec CLI exit codes for use in scripts and CI/CD pipelines.

hitspec uses specific exit codes to indicate the result of a test run. These are useful for scripting and CI/CD integration.

## Exit Codes

| Code | Constant | Description |
| - | - | - |
| `0` | `ExitSuccess` | All tests passed |
| `1` | `ExitTestFailure` | One or more tests failed or thresholds exceeded |
| `2` | `ExitParseError` | A file could not be loaded: invalid syntax, a duplicate `@name`, or a circular `@depends` in a `.http` / `.hitspec` file |
| `3` | `ExitConfigError` | Configuration error: a `hitspec.yaml` (or `--config` file) that is missing or cannot be parsed, an `--env-file` that does not exist, a missing or invalid `--cacert`, `--cert`, `--key` or `--proxy`, an unknown or conflicting `reporters` entry in `hitspec.yaml` (or an `outputDir` that cannot be created), or a port that is already in use (`--metrics-port`, or the `hitspec mock` / `hitspec record` port). These stop the command before any request is sent. `validate`, `studio`, `serve` and `contract` also exit `3` on a broken `hitspec.yaml` |
| `4` | `ExitNetworkError` | At least one request got no response because the connection failed: connection refused or unreachable, DNS resolution failure, TLS handshake or certificate error, the request timeout expiring before a connection was established, or the connection reset or closed before a response arrived. This includes an unreachable OAuth2 token endpoint and an unreachable `@waitFor` target |
| `64` | `ExitUsageError` | Usage error: an unknown flag or command, a flag value the parser rejects (for example `--concurrency abc`), a missing required flag, the wrong number of arguments, `-` combined with other files, `--watch` or `--stress`, `--dry-run` combined with `--stress`, invalid `hitspec mcp` arguments, or `--name` / `--tags` that matched no request in any file. hitspec prints `Run 'hitspec <cmd> --help' for usage.` for these. Errors a command finds while doing its work keep their own code: a missing file or an unknown export format exits `1` |
| `130` | `ExitInterrupted` | The run was stopped with Ctrl+C (SIGINT) or SIGTERM. The results of the requests that finished are printed, `--output-file` is written, and requests that had not started are marked as cancelled. A second Ctrl+C exits immediately |

## Precedence

`hitspec run` always runs every file it can, even when another file fails to load. When several outcomes apply, the exit code follows this order: `2` (a file could not be loaded) over `4` (a request hit a network error) over `1` (a request failed) over `64` (filters matched nothing) over `0`. A run with a broken file never exits `0`, so a broken file cannot hide behind green results. An interrupted run exits `130` whatever else happened.

### Network errors and timeouts

Exit `4` means hitspec could not reach the server, so there is nothing to assert on: use it to tell "the API is down or unreachable" apart from "the API answered wrongly" (`1`). It applies only to connection-level errors. A request that connects but then exceeds `@timeout` or `--timeout` while waiting for the response is an ordinary test failure (`1`), and so is a response whose body breaks off part-way, because a response did arrive. Requests skipped because a dependency failed do not change the exit code on their own.

## Usage in Scripts

```bash theme={null}
hitspec run tests/ --env staging
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "All tests passed" ;;
  1) echo "Tests failed" ;;
  2) echo "Parse error in test files" ;;
  3) echo "Configuration error" ;;
  4) echo "Network error: the API could not be reached" ;;
  64) echo "Invalid CLI usage" ;;
  130) echo "Interrupted" ;;
  *) echo "Unknown exit code: $EXIT_CODE" ;;
esac
```

## CI/CD Usage

Most CI systems treat any non-zero exit code as failure. hitspec's exit codes let you distinguish between test failures and infrastructure issues. A step that accepts only `0` and `1` must also handle `4` (the API could not be reached) and `130` (interrupted):

```yaml theme={null}
# GitHub Actions
- name: Run API tests
  run: hitspec run tests/ --output junit --output-file results.xml
  continue-on-error: true

- name: Check results
  run: |
    if [ ${{ steps.test.outcome }} == 'failure' ]; then
      echo "Tests failed - check results.xml"
    fi
```

<Tip>
  Use `--bail` to stop on the first failure and exit immediately with that failure's code (`1` for a failed test, `4` for a network error). Without `--bail`, hitspec runs all tests before exiting.
</Tip>


# Fetch responses
Source: https://hitspec.dev/reference/fetch

Fetch one HTTP response as raw bytes, readable text, Markdown, or JSON

`hitspec fetch` is the response-body counterpart to `hitspec run`. It executes
exactly one request and writes exactly one payload. `run --output` still controls
test reports; `fetch --format` controls the representation of one response.

```bash theme={null}
# Raw body bytes (the default)
hitspec fetch https://api.example.com/users

# Readable text or a self-contained Markdown artifact
hitspec fetch https://example.com/docs --format text
hitspec fetch https://example.com/docs --format markdown -o docs-response.md

# One saved request
hitspec fetch api.http --name getUsers --env staging --format json
hitspec fetch api.http --index 2
```

## Formats

| Format | Behavior |
| - | - |
| `raw` | Exact decoded response-body bytes with no metadata or added newline. This is the default. |
| `text` | UTF-8 text; JSON is pretty-printed and HTML is reduced to visible text. Binary content is rejected. |
| `markdown` | A response document with sanitized provenance, status, timing, size, and body. HTML links are resolved against the final URL. |
| `json` | A machine-safe metadata envelope. Binary bodies are base64 encoded and sensitive response headers are omitted. |

URL credentials are rejected. Query strings are used for the HTTP request but
removed from Markdown and JSON provenance. `raw` is the only byte-exact mode.

## Ad-hoc request flags

```bash theme={null}
hitspec fetch https://api.example.com/items \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"name":"example"}' \
  --timeout 20s
```

`-X/--request`, `-H/--header`, and `-d/--data` apply only to URL sources. When
`--data` is present and no method is supplied, the method defaults to `POST`.

## Flag reference

| Flag | Applies to | Default and behavior |
| - | - | - |
| `--request`, `-X` | URL | HTTP method. Defaults to `GET`, or `POST` when `--data` is non-empty. |
| `--header`, `-H` | URL | Adds one `Name: value` request header. Repeat the flag for multiple headers. |
| `--data`, `-d` | URL | Sends the supplied string as the request body. |
| `--format` | Both | `raw`. Accepts `raw`, `text`, `markdown`, or `json`. |
| `--output-file`, `-o` | Both | Writes the payload to this path instead of stdout. |
| `--force` | Both | Replaces an existing regular output file. Without it, an existing destination is an error. |
| `--fail`, `-f` | Both | Returns a non-zero status for a non-2xx response, after writing its payload. |
| `--timeout` | Both | Positive Go duration such as `30s` or `2m`. Direct URLs default to `30s`; saved-request precedence is this flag, request `@timeout`, config timeout, then `30s`. |
| `--max-bytes` | Both | `67108864` bytes (64 MiB). The response fails if its body exceeds this limit. |
| `--max-redirects` | Both | `10`. Must be greater than zero, even when redirects are disabled. |
| `--no-follow` | Both | Stops at the first redirect. A saved request also honors a config that disables redirects. |
| `--insecure`, `-k` | Both | Disables TLS certificate verification. A saved request also honors `validateSSL: false` from its config. |
| `--proxy` | Both | Uses the supplied HTTP proxy URL. For a saved request, it overrides the config proxy. |
| `--env`, `-e` | Saved file | Selects an environment. Defaults to the config's default environment, then `dev`. |
| `--env-file` | Saved file | Loads a dotenv file before resolving request variables. |
| `--config` | Saved file | Uses this Hitspec config instead of config discovery from the request file's directory. |
| `--name`, `-n` | Saved file | Selects the uniquely named request. Mutually exclusive with `--index`. |
| `--index` | Saved file | Selects a request by its one-based position. Mutually exclusive with `--name`. |

## Saved request rules

* A file with multiple requests requires `--name` or the one-based `--index`.
* `--name` and `--index` are mutually exclusive.
* The file's variables, selected environment, dotenv file, request auth,
  timeout, proxy, TLS, default headers, and body files are resolved normally.
* `hitspec fetch` runs as you, so `{{$env(NAME)}}` and `${NAME}` read your
  process environment. The MCP `hitspec_fetch` tool does not: it resolves saved
  requests in an isolated mode that ignores the server's environment unless the
  operator allows a variable (see the [MCP reference](/reference/mcp)).
* Assertions, captures, conditions, hooks, shell blocks, database assertions,
  and `@waitFor` are not executed.
* A request declaring `@depends` is rejected. Use `hitspec run` for a dependent
  flow rather than fetching an ambiguous partial sequence.

## HTTP and file behavior

HTTP 4xx and 5xx responses still emit their body and exit successfully by
default. Add `--fail` to return a non-zero status after the payload has been
written. Transport, timeout, rendering, size-limit, and file errors are always
failures.

The default response limit is 64 MiB; change it with `--max-bytes`. A response
that crosses the limit fails explicitly and is never silently truncated.

`--output-file` writes with mode `0600`, refuses to follow a destination
symlink, and does not replace an existing file unless `--force` is supplied.
The final placement is atomic within the destination directory.

<Warning>
  `--insecure` disables TLS certificate verification. Use it only for a local or
  otherwise trusted development endpoint.
</Warning>


# hitspec import & export
Source: https://hitspec.dev/reference/import-export

Import from OpenAPI, Postman, curl, and Insomnia; export to curl, fetch, wget, python, httpie, go, and ruby

# hitspec import

Import API specifications from various formats and convert them to hitspec `.http` files.

```bash theme={null}
hitspec import <format> <source> [flags]
```

## Supported Formats

| Format | Description |
| - | - |
| `openapi` | OpenAPI 3.0/3.1 specs (YAML or JSON, local file or URL) |
| `postman` | Postman Collection v2.1 JSON files |
| `curl` | curl commands (inline or from a file) |
| `insomnia` | Insomnia export files (v4 format) |

## Nothing is dropped silently

Anything an importer cannot carry over is reported on stderr as
`warning: ...`. When the problem belongs to one request, it is also left in the
generated file as a `# TODO:` comment above that request (for example an
untranslated Postman test script or an unsupported curl flag). Every importer
output passes `hitspec validate`.

`-o` accepts a file or a directory (a trailing `/`, or an existing directory).
For a directory, `openapi` writes one file per tag and the other formats write
`<source-name>.http`.

***

## hitspec import openapi

Import from an OpenAPI/Swagger specification.

```bash theme={null}
hitspec import openapi <spec-file-or-url> [flags]
```

### Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--output` | `-o` | Output file, or a directory for one file per tag | stdout |
| `--base-url` | | Override the base URL from the spec | |
| `--tags` | | Filter operations by tags (comma-separated) | all |
| `--no-tests` | | Skip generating test assertions | `false` |

### Path parameters

`/users/{id}` becomes `{{id}}`, and the file defines `@id` with the parameter's
`example`, then `default`, then first `enum` value, then a value for its type
(`1`, `example`, a fixed UUID, ...). If two operations use the same parameter
name with different defaults, the second gets its own variable named
`<operationId>_<param>`.

### One file per tag

With `-o tests/` (or any existing directory) each tag becomes `tests/<tag>.http`.
Operations without tags are grouped by their first path segment. Each file
carries the `@baseUrl` and the path variables its own requests use.

### Examples

<CodeGroup>
  ```bash From a local file theme={null}
  hitspec import openapi api-spec.yaml -o tests/api.http
  ```

  ```bash One file per tag theme={null}
  hitspec import openapi api-spec.yaml -o tests/
  ```

  ```bash From a URL theme={null}
  hitspec import openapi https://petstore.swagger.io/v2/swagger.json -o petstore.http
  ```

  ```bash Filter by tags theme={null}
  hitspec import openapi spec.yaml --tags users,auth -o api.http
  ```

  ```bash Override base URL theme={null}
  hitspec import openapi spec.yaml --base-url http://localhost:3000 -o api.http
  ```

  ```bash Without test assertions theme={null}
  hitspec import openapi spec.yaml --no-tests -o api.http
  ```
</CodeGroup>

***

## hitspec import postman

Import from a Postman Collection v2.1 file.

```bash theme={null}
hitspec import postman <collection.json> [flags]
```

### Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--output` | `-o` | Output file or directory path | stdout |

### Features

* Converts Postman folders into request groups
* Maps Postman dynamic variables to hitspec built-in functions (`{{$guid}}` becomes `{{$uuid()}}`)
* Collection variables become `@name = value` lines
* A Postman **environment** export becomes an `environments:` entry in `hitspec.yaml`
  (written next to the output, or printed when writing to stdout)
* Converts Bearer, Basic, API Key and Digest authentication to `@auth`, honoring
  the request, folder and collection levels (other types are reported)
* Supports raw, URL-encoded, form-data (`>>>multipart`), GraphQL and file bodies
* Translates `pm.test` scripts for the common patterns: `pm.response.to.have.status(N)`,
  `pm.expect(pm.response.code).to.eql(N)`, response time, header checks and
  `pm.expect(jsonData.x).to.eql(y)` (becomes `expect body.x == y`). Everything
  else is kept as `# TODO: untranslated test: ...`. Requests without tests get no
  assertions.

### Examples

<CodeGroup>
  ```bash Basic import theme={null}
  hitspec import postman collection.json -o tests/api.http
  ```

  ```bash Print to stdout theme={null}
  hitspec import postman collection.json
  ```
</CodeGroup>

***

## hitspec import curl

Convert curl commands to hitspec format.

```bash theme={null}
hitspec import curl <command-or-file> [flags]
```

### Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--output` | `-o` | Output file or directory path | stdout |
| `--no-tests` | | Skip generating test assertions | `false` |

### Supported curl flags

| curl Flag | Result |
| - | - |
| `-X, --request` | HTTP method |
| `-H, --header` | Request header (command-line order is kept) |
| `-d, --data, --data-ascii, --data-binary` | Request body. Repeated flags are joined with `&`; `-d @file` becomes `< ./file` |
| `--data-raw` | Request body (a leading `@` is literal) |
| `--data-urlencode` | Percent-encoded body part (`name=value`, `=value`, `value`) |
| `--json` | JSON body plus `Content-Type` and `Accept: application/json` |
| `-F, --form` | `>>>multipart` block (`name=value`, `name=@file`) |
| `-G, --get` | Sends the data as a query string |
| `-I, --head` | `HEAD` request |
| `-T, --upload-file` | `PUT` with a `< ./file` body |
| `-u, --user` | `# @auth basic user, password` (`--digest` gives `digest`) |
| `--oauth2-bearer` | `# @auth bearer <token>` |
| `-m, --max-time` | `# @timeout <ms>` |
| `-A, --user-agent` | User-Agent header |
| `-e, --referer` | Referer header |
| `-b, --cookie` | Cookie header |
| `-k, --insecure` | Warning only: set `validateSSL: false` in `hitspec.yaml` |

Flags that only change how curl prints or transfers (`-s`, `-S`, `-v`, `-i`,
`-f`, `--compressed`, ...) are ignored. Any other flag produces a warning, and
a `# TODO:` above the request. Browser "Copy as cURL" commands (with `$'...'`
quoting) are supported.

<Note>
  An uploaded file field keeps its form field name: `-F avatar=@me.png` becomes
  `file avatar @me.png`. The Postman, Insomnia and OpenAPI importers do the same.
  A field name that contains a space cannot be written that way; it falls back to
  `file @path` (field name `file`) with a warning.
</Note>

### Examples

<CodeGroup>
  ```bash Inline curl command theme={null}
  hitspec import curl "curl -X POST https://api.example.com/users -H 'Content-Type: application/json' -d '{\"name\":\"John\"}'"
  ```

  ```bash From a file (one command per line) theme={null}
  hitspec import curl @commands.txt -o tests/api.http
  ```

  ```bash Without test assertions theme={null}
  hitspec import curl @commands.txt --no-tests -o tests/api.http
  ```
</CodeGroup>

<Note>
  Use `@filename` syntax to read curl commands from a file. The file supports line continuations with `\`.
</Note>

***

## hitspec import insomnia

Import from an Insomnia export file (v4 format).

```bash theme={null}
hitspec import insomnia <export-file> [flags]
```

### Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--output` | `-o` | Output file or directory path | stdout |
| `--no-tests` | | Skip generating test assertions | `false` |

### Features

* Request folders as name prefixes
* Environments: a lone base environment becomes `@name = value` lines. When sub
  environments exist, all variables go to a `hitspec.yaml` `environments:`
  section (a `base` entry plus one per sub environment, each merged over the
  base), written next to the output, or printed to stderr when writing to stdout.
  An existing `hitspec.yaml` is never overwritten (`hitspec.imported.yaml` is
  written instead).
  hitspec finds `hitspec.yaml` from the working directory upward, so for a
  file written elsewhere pass it explicitly:
  `hitspec run tests/api.http --config tests/hitspec.yaml --env dev`.
* Authentication (Bearer, Basic, API Key, Digest) as `@auth`
* Request bodies (JSON, raw, form-urlencoded, multipart, GraphQL, file)
* Headers and query parameters
* Insomnia template tags (`{% ... %}`) are reported, not translated

### Examples

<CodeGroup>
  ```bash Basic import theme={null}
  hitspec import insomnia insomnia-export.json -o tests/api.http
  ```

  ```bash Without test assertions theme={null}
  hitspec import insomnia insomnia-export.json --no-tests -o tests/api.http
  ```
</CodeGroup>

***

# hitspec export

Export hitspec requests as runnable commands or client code.

```bash theme={null}
hitspec export [format] <file> [flags]
hitspec export --format <format> <file> [flags]
```

## Formats

The same names the Studio export action uses.

| Format | Output |
| - | - |
| `curl` (default) | curl commands |
| `fetch` | JavaScript `fetch` (aliases: `javascript`, `js`) |
| `wget` | wget commands |
| `python` | Python `requests` |
| `httpie` | HTTPie commands |
| `go` | Go `net/http` |
| `ruby` | Ruby `Net::HTTP` |

Query parameters (`? key = value` lines) and `@auth` (bearer, basic, API key) are
included in every format. A form block (`& key = value` lines) is exported as the
percent-encoded body the client sends (`name=John%20Smith&e=a%26b`), in `curl` and in
the snippet formats. A request a format cannot express (multipart or file
bodies outside `curl`) is skipped with a `warning:` on stderr and a
`SKIPPED` comment in the output; if no request can be exported the command fails.

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--format` | `-f` | Export format (when not given as the first argument) | `curl` |
| `--name` | `-n` | Filter by request name (glob pattern) | all |
| `--tags` | `-t` | Filter by tags (comma-separated) | all |
| `--output` | `-o` | Output file path | stdout |
| `--env` | `-e` | Environment for variable resolution | none |
| `--exec` | | Execute the curl command directly (curl only) | `false` |
| `--verbose` | `-v` | Include `-v` in curl output (curl only) | `false` |

The exported command is run through `sh` (on Windows, the `sh` from Git for Windows, or `cmd` when there is none), so `bash` is not required. `curl` itself must be installed.

<Warning>
  The `--exec` flag requires exactly one matching request. Use `--name` to filter to a single request when using `--exec`.
</Warning>

## Auth Conversion (curl)

| hitspec | curl |
| - | - |
| `@auth bearer <token>` | `-H 'Authorization: Bearer <token>'` |
| `@auth basic <user>, <pass>` | `-u '<user>:<pass>'` |
| `@auth apiKey <header>, <key>` | `-H '<header>: <key>'` |
| `@auth digest <user>, <pass>` | `--digest -u '<user>:<pass>'` |

## Examples

<CodeGroup>
  ```bash Export all requests as curl theme={null}
  hitspec export curl tests/api.http
  ```

  ```bash Python requests theme={null}
  hitspec export --format python tests/api.http
  ```

  ```bash fetch to a file theme={null}
  hitspec export fetch tests/api.http -o snippets.js
  ```

  ```bash Filter by name theme={null}
  hitspec export curl tests/api.http --name "Login*"
  ```

  ```bash Filter by tags theme={null}
  hitspec export curl tests/api.http --tags smoke,auth
  ```

  ```bash Execute directly theme={null}
  hitspec export curl tests/api.http --name "Login" --exec
  ```

  ```bash Resolve variables from environment theme={null}
  hitspec export curl tests/api.http --env staging
  ```
</CodeGroup>

### Sample Output

```bash theme={null}
# Request: Login
curl -X POST 'https://api.example.com/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username": "john", "password": "secret"}'

# Request: Get Profile
curl -X GET 'https://api.example.com/profile' \
  -H 'Authorization: Bearer {{login.token}}'
```

## Use Cases

* Debug failing tests by running the raw curl command
* Share API calls with teammates who do not use hitspec
* Use exported commands in shell scripts or other tools
* Quickly test an endpoint outside the test framework


# hitspec init
Source: https://hitspec.dev/reference/init

Initialize a new hitspec project with a config file and example test.

# hitspec init

Initialize a new hitspec project in the current directory.

```bash theme={null}
hitspec init [flags]
```

## What It Creates

| File | Description |
| - | - |
| `hitspec.yaml` | Configuration file with default environments (dev, staging, prod) |
| `example.http` | Example requests (health check, create, get) with assertions, a capture, and `>>>mock` blocks so `hitspec mock` can serve them |

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--force` | `-f` | Overwrite existing files | `false` |

## Examples

```bash theme={null}
# Initialize a new project
hitspec init

# Overwrite existing files
hitspec init --force
```

## Generated Config

The generated `hitspec.yaml` includes:

```yaml theme={null}
defaultEnvironment: dev
timeout: 30000
retries: 0
followRedirects: true
maxRedirects: 10
validateSSL: true
headers:
  User-Agent: hitspec
environments:
  dev:
    baseUrl: http://localhost:3000
  staging:
    baseUrl: https://staging.api.example.com
  prod:
    baseUrl: https://api.example.com
```

## Generated Example

The generated `example.http` demonstrates:

* Variable definitions with `@baseUrl`
* Request metadata (`@name`, `@description`, `@tags`)
* Assertion blocks with `>>>` / `<<<`
* Capture blocks with `>>>capture` / `<<<`
* Dependencies with `@depends`

## Run the Example

The example is self-contained: `hitspec mock` serves it from its own `>>>mock` blocks, so it passes without an API of your own. Use two terminals:

```bash theme={null}
# Terminal 1: serve example.http on the dev baseUrl (http://localhost:3000)
hitspec mock example.http --port 3000

# Terminal 2: run it
hitspec run example.http
```

`hitspec run` ignores `>>>mock` blocks. To test a real API, set `baseUrl` in `hitspec.yaml` and replace the requests in `example.http`.

The line `@baseUrl = {{baseUrl}}` at the top of `example.http` makes the file default to the `baseUrl` of the active environment. See [Variables](/concepts/variables).


# MCP client and server
Source: https://hitspec.dev/reference/mcp

Probe and call MCP servers, or expose Hitspec tools over stdio

## Test an MCP server

Hitspec can test local stdio servers and remote Streamable HTTP endpoints from
the same CLI. `probe` completes protocol negotiation, follows every
`tools/list` page, resolves each advertised input/output JSON Schema, and
returns a failed test when a required tool is missing.

<Tabs>
  <Tab title="stdio">
    Put the server executable and each argument after `--`. Hitspec executes
    the argv directly and does not invoke a shell.

    ```bash theme={null}
    hitspec mcp probe \
      --require-tool echo \
      --require-tool health \
      -- ./my-mcp-server --config ./server.json
    ```
  </Tab>

  <Tab title="Streamable HTTP">
    ```bash theme={null}
    hitspec mcp probe \
      --url http://127.0.0.1:3000/mcp \
      --require-tool echo \
      --json
    ```
  </Tab>
</Tabs>

The client uses the official Go SDK, whose current release supports stable MCP
`2025-11-25`, and reports the protocol version actually negotiated with the
server in both human and JSON output.

### Call a tool

`call` first verifies that the server advertises the exact, case-sensitive tool
name, then sends one explicit `tools/call` request:

```bash theme={null}
# Inline JSON arguments over stdio
hitspec mcp call echo \
  --args '{"message":"hello"}' \
  -- ./my-mcp-server

# Arguments from a bounded JSON file over Streamable HTTP
hitspec mcp call weather \
  --args @weather.json \
  --url https://mcp.example.com/mcp \
  --json
```

Arguments must be a JSON object and are limited to 1 MiB when read from a file.
Before execution, Hitspec validates them against the advertised `inputSchema`;
successful structured output is validated against `outputSchema` when present.
Hitspec prints tool content before exiting. A protocol or transport error exits
with code `4`; a contract mismatch, an advertised tool that returns
`isError: true`, an unknown tool, or a missing `--require-tool` exits with code
`1`. This preserves MCP's distinction between a failed tool execution and a
failed protocol request.

<Warning>
  `mcp call` executes the selected tool and may cause external changes. Review
  the tool and arguments before running it. Tool annotations, descriptions, and
  output are server-provided data, not trusted authorization metadata.
</Warning>

### Client flags

| Flag | Applies to | Default | Behavior |
| - | - | - | - |
| `--url` | Both | unset | Streamable HTTP endpoint. Mutually exclusive with a stdio argv. |
| `--timeout` | Both | `30s` | Maximum duration for connect, discovery, and call. |
| `--json` | Both | `false` | Emit a stable machine-readable report. |
| `--header` | HTTP | unset | Repeatable `Name: Value` header. Transport-managed MCP headers are rejected. |
| `--env` | stdio | inherited | Repeatable `KEY=VALUE` child-process override. Hitspec does not echo values; child stderr is forwarded. |
| `--cwd` | stdio | current directory | Child-process working directory. |
| `--require-tool` | `probe` | unset | Require a tool name. Repeat the flag or pass comma-separated names. |
| `--args` | `call` | `{}` | Inline JSON object or `@path` to a JSON file. |

HTTP redirects are rejected so credentials cannot cross endpoint boundaries.
URLs containing credentials are also rejected; send authorization explicitly
with `--header`. For repeatable automation, inject sensitive values through the
calling environment or secret manager and avoid committing them to scripts.

## Run Hitspec as an MCP server

Run Hitspec as a workspace-scoped Model Context Protocol server:

```bash theme={null}
hitspec mcp serve --workspace /absolute/path/to/api-workspace
```

stdout is reserved exclusively for MCP JSON-RPC. The server does not start run
history or a file watcher or execute shell hooks or database assertions. Web
search and durable capture are registered only when their
operator-owned provider and artifact sink, respectively, are configured at
startup. MCP initialization instructions are built from that registered
surface, so clients are not prompted to use unconfigured search or capture
tools. They also state whether `hitspec_fetch` is public-only or has
operator-enabled non-public HTTP(S) authority, including private, loopback,
link-local, and reserved targets; this does not broaden the public-only capture
policy.

## Tools

| Tool | Purpose | Registered when |
| - | - | - |
| `hitspec_fetch` | Fetch one direct URL or one saved request as `raw`, `text`, `markdown`, or `json`. | Always |
| `hitspec_search_web` | Search the live public web and return normalized discovery candidates without persistence. | A search provider is configured |
| `hitspec_capture_webpage` | GET one public webpage, render Markdown, and preserve it in file.cheap. | An artifact sink is configured |
| `hitspec_list_requests` | List names, methods, source lines, and tags in workspace Hitspec files. | Always |
| `hitspec_validate` | Parse and structurally validate one workspace file without executing it. | Always |

Hitspec is the only model-visible web surface. Tavily is the initial internal
search provider and can be replaced without changing these tool names or
schemas.

### `hitspec_fetch` input

| Field | Type | Applies to | Default and behavior |
| - | - | - | - |
| `url` | string | Direct URL | HTTP(S) URL. Supply exactly one of `url` or `file`. |
| `file` | string | Saved request | Workspace-relative `.http` or `.hitspec` file. Supply exactly one of `file` or `url`. |
| `name` | string | Saved request | Selects a uniquely named request. Mutually exclusive with `index`. |
| `index` | integer | Saved request | Selects a request by its one-based position. Mutually exclusive with `name`. |
| `environment` | string | Saved request | Environment name. Defaults to the config's default environment, then `dev`. |
| `env_file` | string | Saved request | Workspace-relative dotenv file. |
| `config_file` | string | Saved request | Workspace-relative Hitspec config file. |
| `method` | string | Direct URL | HTTP method. Defaults to `GET`, or `POST` when `body` is non-empty. |
| `headers` | object | Direct URL | Map of request header names to string values. |
| `body` | string | Direct URL | UTF-8 request body. |
| `format` | string | Both | `text`. Accepts `raw`, `text`, `markdown`, or `json`. |
| `no_follow` | boolean | Both | `false`. When true, stops at the first redirect. Redirect chains otherwise have a fixed limit of 10. |

A file containing multiple requests requires `name` or `index`. A saved request
that declares `@depends` is rejected. Assertions, captures, conditions, hooks,
shell blocks, database assertions, and `@waitFor` are not executed.
`hitspec_fetch` never persists the response; use `hitspec_capture_webpage` for a
durable artifact.

### Live web search and capture

`hitspec_search_web` has this provider-neutral tool input:

| Field | Type | Default and behavior |
| - | - | - |
| `query` | string | Required; maximum 512 Unicode characters. |
| `max_results` | integer | `5`; accepts 1–10. |
| `language` | string | Optional BCP 47 language hint. A provider returns an explicit error when it cannot apply the filter; Tavily does not currently support it. |
| `freshness` | string | `any`; accepts `any`, `day`, `week`, `month`, or `year`. |
| `include_domains` | string\[] | Optional; at most 20 normalized public domains. |
| `exclude_domains` | string\[] | Optional; at most 20 normalized public domains. A domain cannot appear in both lists. |

The tool does not accept a provider, endpoint, API key, authorization header,
arbitrary headers, generated-answer switch, or raw-content switch. Tavily is an
internal adapter selected by the server operator, not a separate model-visible
tool.

The JSON document is capped at 64 KiB. It contains `kind: "discovery"`,
normalized `query`, `results`, and `truncated`. Each result contains only
`title`, `url`, `domain`, `snippet`, optional `published_at`, and a response-local
`citation_id`. `truncated` is `true` whenever candidates are
omitted by the result limit or response cap; for the latter, Hitspec removes
trailing results. Provider-specific request IDs and scores, generated answers,
raw page content, and credentials are never exposed. Search snippets are
discovery candidates, not verified or durable evidence.

`hitspec_capture_webpage` has this compatibility-preserving input:

| Field | Type | Default and behavior |
| - | - | - |
| `url` | string | Required public HTTP(S) webpage URL. |
| `name` | string | Optional file.cheap stash name; defaults to the HTML title. |
| `tags` | string\[] | Optional extra tags; `web` and `markdown` are always included. |
| `ttl` | string | Optional file.cheap retention such as `24h`, `7d`, `30d`, or `2026-12-31`. |
| `index` | boolean | `true`; index the Markdown immediately for `fcheap search`. |

The tool performs one public-network GET, renders static HTML as Markdown, and
saves it through the fixed file.cheap adapter. It returns a compact receipt,
not the page body or rendered Markdown:

```json theme={null}
{
  "url": "https://example.com/docs",
  "final_url": "https://example.com/docs",
  "title": "Example documentation",
  "http_status": 200,
  "content_type": "text/html",
  "markdown_bytes": 1842,
  "stash": {
    "id": "stash-id",
    "name": "Example documentation",
    "status": "saved",
    "created_at": "2026-07-13T12:00:00Z",
    "tags": ["web", "markdown"],
    "content_hash": "e3b0c442...",
    "file_count": 1,
    "total_size": 1842,
    "index_requested": true,
    "indexed": true
  }
}
```

The stash object includes `file_count` and `total_size` and may also include
`expires_at`. Inspect `status`, `indexed`, and `failed` when present before
deciding whether follow-up is needed.

### Request discovery and validation input

* `hitspec_list_requests` accepts an optional `path`: a workspace-relative
  directory or `.http`/`.hitspec` file. It defaults to the workspace root and
  searches directories recursively. If any discovered Hitspec file is invalid,
  the tool returns an error instead of an incomplete list.
* `hitspec_validate` requires `file`, a workspace-relative `.http` or `.hitspec`
  file. Its result reports the file, validity, request count, and parse or
  structural errors.

Saved file, dotenv, config, and discovery paths are workspace-relative and are
checked after symlink resolution.

### Tool result content

Every successful tool call includes an MCP `TextContent` representation so
clients that do not pass through structured output can still consume it:

* `hitspec_fetch` with `raw` returns a JSON text envelope containing sanitized
  source, status, content type, byte size, `encoding: "base64"`, and `data`.
* `text` and `markdown` return their rendered documents as text content. `json`
  returns the machine-safe response envelope serialized as text content.
* Discovery and validation return their JSON documents serialized as text
  content.
* Search returns the bounded discovery JSON as text content. Webpage capture
  also publishes its typed compact receipt as structured content when the client
  supports it.

## Server flags

| Flag | Default | Behavior |
| - | - | - |
| `--workspace` | `.` | Fixes the filesystem boundary exposed to all tools. Use an absolute path in client configuration. The server refuses to start when the workspace is your home directory, a directory that contains it, or the filesystem root. |
| `--allow-broad-workspace` | `false` | Deliberately permits one of those broad workspaces. |
| `--allow-env` | none | Repeatable. Names a process environment variable that saved requests may read (see [Saved-request environment isolation](#saved-request-environment-isolation)). |
| `--max-body-bytes` | `1048576` (1 MiB) | Maximum fetched response-body size. |
| `--timeout` | `30s` | Maximum duration of one HTTP request. |
| `--allow-private-network` | `false` | Allows private, loopback, and other non-public targets; it also enables the standard saved-request modes described below. |
| `--search-provider` | `none` | Live search provider. Currently `none` or `tavily`; may also come from `HITSPEC_SEARCH_PROVIDER`. |
| `--fcheap-path` | unset | Fixed file.cheap executable for webpage capture; may also come from `HITSPEC_FCHEAP_PATH`. |
| `--fcheap-stash-dir` | file.cheap default | Optional fixed stash directory; may also come from `HITSPEC_FCHEAP_STASH_DIR`. |

Tavily authentication comes only from the server process's `TAVILY_API_KEY`.
The key is never accepted as a tool argument or returned in output. The
file.cheap child receives an allowlisted environment that excludes this key.
The server also removes `TAVILY_API_KEY` from its own process environment once
it has read it at startup, so nothing evaluated later can read it back.

### Saved-request environment isolation

A workspace can be a cloned repository or a pull request, so its `.http` files
and `hitspec.yaml` are untrusted input. When `hitspec_fetch` runs a saved
request it resolves `{{NAME}}`, `{{$NAME}}`, `{{$env(NAME)}}`, and `${NAME}` in
`hitspec.yaml` environments from the workspace only: the config's selected
environment, the optional `env_file`, and the file's own variables. The server's
process environment is not consulted, so a request cannot place a secret such as
an API key in a URL, header, or body.

The operator can make specific process variables visible with `--allow-env NAME`
(repeatable). The list is empty by default and is never model-controlled. An
`env_file` is read into that one call only; it is not exported into the process
and does not persist into later tool calls.

Tool errors name files workspace-relative. A path that does not exist and a path
outside the workspace return the same `path not found or not allowed` message.

## Limits and network policy

* The default body limit is 1 MiB (`--max-body-bytes`). Crossing it is an error,
  never a truncated success.
* The default request timeout is 30 seconds (`--timeout`).
* Direct URLs and saved requests allow only public HTTP(S) destinations by
  default. The initial host, redirects, DNS answers, and dial target are checked.
* URL credentials are rejected and response provenance omits URL query strings.
* A saved request that uses digest, AWS, or OAuth2 authentication, multipart
  data, or a configured proxy is rejected under the public-only policy. The
  proxy is not silently ignored.
* Redirect chains are limited to 10; callers can set `no_follow` to disable
  redirects entirely.

To test a local API, the person starting the server must grant that authority:

```bash theme={null}
hitspec mcp serve \
  --workspace "$PWD" \
  --allow-private-network
```

This operator grant also switches saved requests to the standard Hitspec HTTP
client, enabling configured proxies and digest, AWS, OAuth2, and multipart
request modes. Grant it only to agents and workspaces that need that authority.

`hitspec_fetch` is annotated `destructiveHint: true` and not read-only because
it can send `POST`, `PUT`, `PATCH`, and `DELETE` requests. Durable webpage
capture is not marked read-only because artifact writes have external effects.
The discovery-only `hitspec_search_web` tool is marked read-only and open-world.

## Approval boundaries

| Tool | Recommended policy |
| - | - |
| `hitspec_search_web` | Eligible for AUTO only when this exact bounded tool is explicitly allowlisted. |
| `hitspec_capture_webpage` | Treat as a public-network read plus durable write; allowlist only when both effects are approved. |
| `hitspec_fetch` | Keep approval-gated because callers can choose methods, headers, and bodies. It never persists content. |

AUTO never enables private-network access or relaxes URL, redirect, DNS, body,
or workspace checks.

## Direct MCP client configuration

```json theme={null}
{
  "mcpServers": {
    "hitspec": {
      "command": "hitspec",
      "args": [
        "mcp", "serve",
        "--workspace", "/absolute/api-workspace",
        "--search-provider", "tavily",
        "--fcheap-path", "/absolute/path/to/fcheap"
      ]
    }
  }
}
```

Inject `TAVILY_API_KEY` into the server process through the MCP host or tvault;
do not write its value into this configuration.

See [Agent artifact workflow](/integrations/agent-artifacts) for MCPHub, Local
Agent, and file.cheap composition.


# hitspec mock & record
Source: https://hitspec.dev/reference/mock-record

Start a mock HTTP server or recording proxy from hitspec files

# hitspec mock

Start an HTTP mock server that responds based on requests and assertions defined in your hitspec files.

```bash theme={null}
hitspec mock <file|directory> [flags]
```

## Arguments

| Argument | Description |
| - | - |
| `<file>` | Single `.http` or `.hitspec` file to derive routes from |
| `<directory>` | Directory containing test files (searched recursively) |

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--port` | `-p` | Port to run the mock server on | `3000` |
| `--host` | | Address to bind. Use `0.0.0.0` to accept connections from other machines or from outside a container | `127.0.0.1` |
| `--cors` | | Answer CORS preflights and add `Access-Control-Allow-*` headers to every response | `false` |
| `--delay` | `-d` | Artificial delay for all responses (e.g., `100ms`, `1s`) | `0` |
| `--verbose` | `-v` | Enable verbose logging | `false` |

## Behavior

The mock server:

* Parses your `.http` files to extract routes (method + URL path)
* Generates mock responses from assertion blocks or explicit mock definitions
* Supports path parameters (e.g., `/users/{{id}}`)
* Adds configurable response delays to simulate network latency
* Answers `405 Method Not Allowed` with an `Allow` header when the path exists for another method
* Serves `HEAD` from the `GET` route of the same path
* Listens on `127.0.0.1` only; pass `--host 0.0.0.0` to expose it (for example in Docker)
* Exits `3` when the port is already in use
* Handles graceful shutdown on `Ctrl+C` (SIGINT/SIGTERM)

## Examples

<CodeGroup>
  ```bash Basic mock server theme={null}
  hitspec mock api.http
  ```

  ```bash Custom port theme={null}
  hitspec mock api.http --port 8080
  ```

  ```bash With simulated latency theme={null}
  hitspec mock api.http --port 3000 --delay 100ms
  ```

  ```bash From a directory theme={null}
  hitspec mock tests/ --verbose
  ```

  ```bash Reachable from a container or another machine theme={null}
  hitspec mock api.http --host 0.0.0.0
  ```

  ```bash For a browser app on another origin theme={null}
  hitspec mock api.http --cors
  ```
</CodeGroup>

### Sample Output

```
Mock server: loaded 12 route(s) from 3 file(s)
Mock server listening on http://127.0.0.1:3000
```

## Use Cases

* **Frontend development** -- Run a mock backend while building the UI without needing the real API.
* **Offline testing** -- Test client code against a local server when the real API is unavailable.
* **Prototyping** -- Quickly stand up a fake API from your test definitions.
* **Integration tests** -- Use the mock server as a dependency in your CI pipeline.

***

# hitspec record

Start an HTTP recording proxy that captures requests and responses, then exports them to hitspec format.

```bash theme={null}
hitspec record [flags]
```

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--port` | `-p` | Port to run the proxy on | `8080` |
| `--host` | | Address to bind. Use `0.0.0.0` to expose the proxy beyond this machine | `127.0.0.1` |
| `--no-redact` | | Record secrets verbatim instead of replacing them with `{{PLACEHOLDER}}` references | `false` |
| `--target` | `-t` | Target URL to proxy to (required) | |
| `--output` | `-o` | Output file path | stdout |
| `--exclude` | | Paths to exclude from recording (comma-separated) | |
| `--verbose` | `-v` | Enable verbose logging | `false` |
| `--dedupe` | | Skip duplicate requests (same method + path) | `false` |
| `--json` | | Export as JSON instead of `.http` format | `false` |

## Behavior

The recording proxy:

* Forwards all requests to the target server (reverse proxy mode)
* Records both requests and responses
* Streams responses to the client as they arrive: server-sent events and chunked bodies are not buffered. The recording keeps up to 1 MiB of each body (the client always gets all of it), and the recording is stored when the response ends
* Redacts secrets by default: the `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key` and `Api-Key` headers, and JSON fields named `password`, `secret`, `token` or `apiKey` (including `access_token`, `clientSecret` and similar names that end in one of those) in request and response bodies. Values become `{{AUTHORIZATION}}`, `{{ACCESS_TOKEN}}`, ... so the exported file can be run with those variables defined. Use `--no-redact` to keep everything
* Records the full target URL, including a path prefix in `--target` (`--target https://api.example.com/v2` records `https://api.example.com/v2/users`)
* Listens on `127.0.0.1` only; pass `--host 0.0.0.0` to expose it
* Exits `3` when the port is already in use
* Exports to `.http` format on shutdown (`Ctrl+C`)
* Supports deduplication of repeated requests

## Examples

<CodeGroup>
  ```bash Basic recording theme={null}
  hitspec record --target https://api.example.com -o recorded.http
  ```

  ```bash Custom port theme={null}
  hitspec record --port 9090 --target https://api.example.com
  ```

  ```bash Exclude health/metrics endpoints theme={null}
  hitspec record --target https://api.example.com --exclude "/health,/metrics" -o api.http
  ```

  ```bash Deduplicate requests theme={null}
  hitspec record --target https://api.example.com --dedupe -o api.http
  ```

  ```bash Export as JSON theme={null}
  hitspec record --target https://api.example.com --json -o recordings.json
  ```
</CodeGroup>

### Workflow

1. Start the recording proxy pointing at your real API:
   ```bash theme={null}
   hitspec record --target https://api.example.com --port 8080 -o tests/api.http
   ```

2. Configure your client or browser to use `http://localhost:8080` as the API base URL.

3. Perform the actions you want to capture (login, CRUD operations, etc.).

4. Press `Ctrl+C` to stop the proxy. The recorded requests are exported to the output file.

5. Edit the generated `.http` file to add assertions and parameterize values.

### Sample Output

```
Recording proxy listening on http://127.0.0.1:8080
Proxying to: https://api.example.com

Recorded 5 requests
Exported to tests/api.http
```

## Use Cases

* **Bootstrap test suites** -- Record real API traffic and convert it into test files automatically.
* **Regression testing** -- Capture a working session and replay it as tests.
* **API exploration** -- Discover endpoints and their expected responses by interacting with the real API.
* **Documentation** -- Generate `.http` files that document actual API usage patterns.


# Output Formats
Source: https://hitspec.dev/reference/output-formats

Reference for all 5 output formats supported by hitspec: console, JSON, JUnit XML, TAP, and HTML.

hitspec supports 5 output formats for test results. Select the format with the `--output` flag (or `-o`).

```bash theme={null}
hitspec run tests/ --output json
hitspec run tests/ -o junit --output-file results.xml
```

***

## console (default)

Human-readable colored terminal output with pass/fail indicators, response times, and a summary.

```bash theme={null}
hitspec run tests/
```

A failed request always shows what was sent and what came back: the request line (method and the URL as sent), the response status line with its duration, and an excerpt of the response body. JSON is pretty-printed and the excerpt is capped at about 2 KB or 30 lines, with a note saying how much was cut. A request that errored before getting a response shows the request line and the error. Credentials are masked in the console, JUnit and TAP reports. Header values for `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` and any header whose name contains `api-key`, `token`, `secret` or `password` print as `[REDACTED]`. So do the password in a URL's `user:password@` and the value of query parameters named like `api_key` or `access_token`, in the request line and in error messages. The JSON and HTML reports redact header values but record the URL exactly as sent.

```text theme={null}
  ✗ getUser (12ms)
    → status == (line 5)
      Expected: 200
      Actual:   404
      expected 200, got 404
    Request:  GET https://api.example.com/users/42
    Response: 404 Not Found (9ms)
    Body:
      {
        "error": "user not found",
        "id": 42
      }
```

Verbosity levels add detail for every request, not only failures:

| Flag | Adds |
| - | - |
| (none) | Failures only get the request, response and body excerpt |
| `-v` | The request line and response status of every request, plus captures and SSE events |
| `-vv` | Request and response headers (credentials redacted) |
| `-vvv` | The full request and response bodies, uncapped |

Warnings print in yellow under the request they belong to: a capture that matched nothing, or a `{{reference}}` that was still unresolved when the request was sent. A warning never changes pass/fail or the exit code.

Options:

* `--no-color` -- disable colored output
* `--quiet` -- suppress all output except errors

***

## json

Machine-readable JSON output containing test results, durations, and assertion details. Useful for integration with other tools.

```bash theme={null}
hitspec run tests/ --output json
hitspec run tests/ --output json --output-file results.json
```

Output structure:

```json theme={null}
{
  "summary": {
    "total": 10,
    "passed": 9,
    "failed": 1,
    "skipped": 0
  },
  "tests": [
    {
      "name": "getUser",
      "file": "tests/api.http",
      "passed": true,
      "duration": 45.2
    }
  ],
  "duration": 1234.5
}
```

Every test also carries `request` (`method`, `url`, `headers`) and `response` (`statusCode`, `status`, `headers`, `duration`) when a request was sent; header credentials are redacted. For a failed or errored request, `response.bodyExcerpt` holds the pretty-printed body (capped at about 2 KB or 30 lines, with `response.bodyTruncated: true` when it was cut). A test with warnings has a `warnings` array of strings.

<Tip>
  JSON output is the format used by `hitspec diff` for comparing test runs.
</Tip>

***

## junit

JUnit XML format compatible with CI/CD systems like GitHub Actions, GitLab CI, Jenkins, and CircleCI.

```bash theme={null}
hitspec run tests/ --output junit --output-file test-results.xml
```

Most CI systems can parse JUnit XML natively for test result visualization.

A `<failure>` or `<error>` body carries the failed assertions followed by the request line, the response status line and a capped body excerpt, so the CI report is enough to see why a request failed. Warnings (a capture that matched nothing, an unresolved `{{reference}}`) are written to the test case's `<system-out>`.

### GitHub Actions Example

```yaml theme={null}
- name: Run API tests
  run: hitspec run tests/ --output junit --output-file results.xml

- name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: ${{ !cancelled() }}
  with:
    files: results.xml
    comment_mode: off
```

Grant the workflow or job token `checks: write` when publishing check runs.

***

## tap

[Test Anything Protocol](https://testanything.org/) output, compatible with TAP consumers and harnesses.

```bash theme={null}
hitspec run tests/ --output tap
```

Output:

```
TAP version 13
1..10
ok 1 - getUser (45ms)
ok 2 - createUser (120ms)
not ok 3 - deleteUser
  ---
  failures:
    - "status ==: expected 204, got 403"
  request: "DELETE https://api.example.com/users/7"
  response:
    status: "403 Forbidden"
    durationMs: 89
    body: |2-
      {
        "error": "forbidden"
      }
  ...
```

The diagnostics of a failed request carry the request line, the response status and duration, and the body excerpt (a literal block; `bodyTruncated` says how much was cut). Warnings are listed under `warnings:`.

***

## html

Self-contained HTML report with styling, suitable for sharing or archiving.

```bash theme={null}
hitspec run tests/ --output html --output-file report.html
```

The report includes:

* Summary dashboard with pass/fail counts
* Individual test results with durations
* Assertion details for failed tests
* Request and response details, with credentials in headers redacted
* Warnings for each test
* Dark theme styling

***

## Writing to Files

By default, all formats write to stdout. Use `--output-file` to write to a file instead:

```bash theme={null}
hitspec run tests/ --output json --output-file results.json
hitspec run tests/ --output junit --output-file results.xml
hitspec run tests/ --output html --output-file report.html
```

***

## Quick Reference

| Format | Flag | Use Case |
| - | - | - |
| `console` | `--output console` | Development, interactive use |
| `json` | `--output json` | Tool integration, `hitspec diff` |
| `junit` | `--output junit` | CI/CD test reporting |
| `tap` | `--output tap` | TAP-compatible tools |
| `html` | `--output html` | Shareable test reports |


# REST API
Source: https://hitspec.dev/reference/rest-api

Complete reference for the hitspec server HTTP API

The hitspec server exposes a REST API when you run `hitspec serve --api-only`. All endpoints are prefixed with `/api/v1`. Responses are JSON with `Content-Type: application/json`.

```bash theme={null}
hitspec serve --api-only --port 8080
```

## Security and Request Requirements

The API can read, write and delete workspace files and send arbitrary requests, so the server protects itself against web pages that try to reach it through your browser:

* **JSON bodies need `Content-Type: application/json`.** A request that has a JSON body but any other content type (`text/plain`, `application/x-www-form-urlencoded`, none at all) is rejected with `415 Unsupported Media Type`. `curl -d` sends form-encoded data by default, so add `-H "Content-Type: application/json"`. Requests without a body (for example `POST /stress/stop`) need no content type. `PUT /files/{path}` takes the raw file text and is not affected.
* **Host.** When the server is bound to a loopback address, the `Host` header must be `localhost`, `127.0.0.1` or `[::1]` (optionally with the server's port); anything else gets `403 Forbidden` (DNS-rebinding protection).
* **Origin.** A request that carries an `Origin` header (browsers always send one cross-site) must come from `http(s)://localhost`, `127.0.0.1` or `[::1]` on the server's own port, or on any port when `--cors` is set; otherwise `403 Forbidden`. This also applies to the WebSocket upgrade. Requests without `Origin` (curl, scripts, server-side code) are not affected.
* **Token.** If `--api-token` / `HITSPEC_API_TOKEN` is set, every request needs `Authorization: Bearer <token>` (scheme is case-insensitive) or `?token=<token>`, else `401`. If the server binds to a non-loopback address, or `--allow-shell` / `--allow-db` is set, and no token is configured, a random token is generated and printed once to stderr.
* **CORS preflights.** With `--cors`, `OPTIONS` preflights from an allowed origin are answered with `204` and CORS headers without a token; the actual request still needs it.
* **Workspace file references.** A `< file` body or a multipart file that points outside the workspace is refused (`file reference ... is outside the workspace`). This applies to run, execute, stress and contract verification. `hitspec run` is not subject to this.

### Read-only mode

With `--read-only`, writes to files, `hitspec.yaml`, environments (switching the active environment is still allowed), stress profiles and history return `403`. Running requests, stress, mock, record start/stop, contract verification, export/curl, import (`POST /import/*`) and `POST /record/export` keep working, because they only return text and write nothing. Runs in read-only mode do not persist cookies.

### Timeouts and shutdown

`/run` and `/execute` are not subject to the 60s response timeout. On shutdown the server lets in-flight requests finish for up to 10s; a second signal exits at once. `--parent-pid <pid>` shuts the server down when that process exits, so a supervisor that dies without cleaning up does not leave it running.

## Error Format

All error responses follow a consistent structure:

```json theme={null}
{
  "error": "Bad Request",
  "message": "file is required"
}
```

| Field | Type | Description |
| - | - | - |
| `error` | string | HTTP status text (e.g., `"Bad Request"`, `"Not Found"`) |
| `message` | string | Human-readable error detail |

***

## Workspace & Files

### Get Workspace Overview

Returns the workspace file tree, total request count, active environment, and whether a config file exists.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/workspace
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "root": "/Users/you/project",
  "files": [
    {
      "path": "tests",
      "name": "tests",
      "dir": "",
      "isDir": true,
      "children": [
        {
          "path": "tests/api.http",
          "name": "api.http",
          "dir": "tests",
          "isDir": false,
          "requestCount": 5
        }
      ]
    },
    {
      "path": "smoke.http",
      "name": "smoke.http",
      "dir": "",
      "isDir": false,
      "requestCount": 3
    }
  ],
  "totalRequests": 8,
  "environment": "dev",
  "hasConfig": true
}
```

***

### List Files

Returns a flat list of all `.http` and `.hitspec` files in the workspace with metadata.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/files
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
[
  {
    "path": "/Users/you/project/tests/api.http",
    "relativePath": "tests/api.http",
    "name": "api.http",
    "size": 1234,
    "modTime": "2026-02-10T12:00:00Z",
    "requestCount": 5
  }
]
```

***

### Get Parsed File

Returns the fully parsed content of a single `.http` or `.hitspec` file, including all requests, variables, assertions, and captures.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/files/tests/api.http
  ```
</CodeGroup>

<ParamField type="string">
  Relative path to the file within the workspace. Uses wildcard path matching (`{path...}`).
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "path": "tests/api.http",
  "variables": [
    { "name": "baseUrl", "value": "http://localhost:3000", "line": 1 }
  ],
  "requests": [
    {
      "name": "Get Users",
      "description": "Fetch all users",
      "tags": ["users"],
      "method": "GET",
      "url": "{{baseUrl}}/users",
      "headers": [
        { "key": "Accept", "value": "application/json", "line": 5 }
      ],
      "queryParams": [
        { "key": "limit", "value": "10", "line": 6 }
      ],
      "assertions": [
        { "subject": "status", "operator": "equals", "expected": 200, "line": 8 }
      ],
      "captures": [
        { "name": "userId", "source": "body", "path": "$.data[0].id", "line": 9 }
      ],
      "line": 3,
      "metadata": {
        "timeout": 5000,
        "retry": 2,
        "depends": ["Auth Login"]
      }
    }
  ]
}
```

***

### Get Raw File Content

Returns the raw text content of a file. Use this for source editing.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/files/raw/tests/api.http
  ```
</CodeGroup>

<ParamField type="string">
  Relative path to the file within the workspace.
</ParamField>

**Response** `200 OK` with `Content-Type: text/plain`

```
@baseUrl = https://api.example.com

### Get Users
GET {{baseUrl}}/users
```

***

### Create File

Create a new `.http` or `.hitspec` file in the workspace.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/files \
    -H "Content-Type: application/json" \
    -d '{"path": "tests/new-api.http", "content": "### Health Check\nGET https://api.example.com/health\n"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  path: string;      // Required. Relative path for the new file
  content?: string;  // Optional. Initial file content
}
```

<ParamField type="string">
  Relative path for the new file. Must end in `.http` or `.hitspec` and be within the workspace.
</ParamField>

**Response** `201 Created`

```json theme={null}
{ "path": "tests/new-api.http" }
```

***

### Save File

Save raw text content to an existing file. The file watcher suppresses the corresponding change notification to prevent UI reload loops.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT http://localhost:8080/api/v1/files/tests/api.http \
    -H "Content-Type: text/plain" \
    -d '@baseUrl = https://api.example.com

  ### Get Users
  GET {{baseUrl}}/users
  '
  ```
</CodeGroup>

<ParamField type="string">
  Relative path to the file within the workspace.
</ParamField>

**Request Body:** Raw file content as `text/plain`.

**Response** `200 OK`

```json theme={null}
{ "path": "tests/api.http" }
```

***

### Delete File

Delete a `.http` or `.hitspec` file from the workspace.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/files/tests/old-api.http
  ```
</CodeGroup>

<ParamField type="string">
  Relative path to the file within the workspace.
</ParamField>

**Response** `204 No Content`

***

## Execution

### Execute Request

Execute one or more requests from a specific file. When `requestName` is provided, only that request runs (filtered by name). When omitted, all requests in the file execute.

Real-time progress is broadcast over the [WebSocket](#websocket) connection during execution.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/execute \
    -H "Content-Type: application/json" \
    -d '{"file": "tests/api.http", "requestName": "Get Users", "environment": "dev"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  file: string;          // Required. Relative path to the .http/.hitspec file
  requestName?: string;  // Optional. Filter to a single request by name
  environment?: string;  // Optional. Override the active environment
}
```

<ParamField type="string">
  Relative path to the `.http` or `.hitspec` file within the workspace.
</ParamField>

<ParamField type="string">
  Name of a specific request to execute. When omitted, all requests in the file are executed.
</ParamField>

<ParamField type="string">
  Environment name to use for variable interpolation. Overrides the server's active environment.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "file": "tests/api.http",
  "duration": 245,
  "passed": 1,
  "failed": 0,
  "skipped": 0,
  "results": [
    {
      "name": "Get Users",
      "description": "Fetch all users",
      "passed": true,
      "duration": 245,
      "request": {
        "method": "GET",
        "url": "http://localhost:3000/users",
        "headers": { "Accept": "application/json" }
      },
      "response": {
        "statusCode": 200,
        "status": "200 OK",
        "headers": { "Content-Type": "application/json" },
        "body": "{\"data\":[{\"id\":1,\"name\":\"Alice\"}]}",
        "duration": 243,
        "size": 42
      },
      "assertions": [
        {
          "subject": "status",
          "operator": "equals",
          "expected": 200,
          "actual": 200,
          "passed": true
        }
      ],
      "captures": { "userId": 1 }
    }
  ]
}
```

A result may also carry `warnings`, an array of strings with non-fatal findings (a capture that matched nothing, a `{{reference}}` sent unresolved). It is omitted when empty.

***

### Run File

Run all requests in a file. Similar to `execute` but always runs every request (no name filter).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/run \
    -H "Content-Type: application/json" \
    -d '{"file": "tests/api.http", "environment": "staging"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  file: string;          // Required. Relative path to the file
  environment?: string;  // Optional. Override the active environment
}
```

<ParamField type="string">
  Relative path to the `.http` or `.hitspec` file within the workspace.
</ParamField>

<ParamField type="string">
  Environment name to use. Overrides the server's active environment.
</ParamField>

**Response** `200 OK` -- same `RunResultDTO` structure as the [Execute Request](#execute-request) endpoint.

***

## Environments

### List Environments

Returns all environments defined in `hitspec.yaml`, including the currently active environment.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/environments
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
[
  {
    "name": "dev",
    "variables": {
      "baseUrl": "http://localhost:3000",
      "token": "dev-token"
    }
  },
  {
    "name": "staging",
    "variables": {
      "baseUrl": "https://staging.api.example.com",
      "token": "staging-token"
    }
  }
]
```

***

### Set Active Environment

Switch the server's active environment. Broadcasts an `environment_changed` event over WebSocket.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT http://localhost:8080/api/v1/environments/active \
    -H "Content-Type: application/json" \
    -d '{"name": "staging"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  name: string;  // Required. Environment name to activate
}
```

<ParamField type="string">
  The name of the environment to set as active.
</ParamField>

**Response** `204 No Content`

***

### Get Environment

Get the variables for a specific environment.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/environments/dev
  ```
</CodeGroup>

<ParamField type="string">
  Environment name.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "name": "dev",
  "variables": {
    "baseUrl": "http://localhost:3000",
    "token": "dev-token"
  }
}
```

***

### Update Environment

Create or update the variables for a named environment.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT http://localhost:8080/api/v1/environments/dev \
    -H "Content-Type: application/json" \
    -d '{"variables": {"baseUrl": "http://localhost:4000", "token": "new-token"}}'
  ```
</CodeGroup>

<ParamField type="string">
  Environment name.
</ParamField>

**Request Body**

```typescript theme={null}
{
  variables: Record<string, any>;  // Key-value pairs of environment variables
}
```

<ParamField type="object">
  Map of variable names to values for this environment.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "name": "dev",
  "variables": {
    "baseUrl": "http://localhost:4000",
    "token": "new-token"
  }
}
```

***

## Config

### Get Configuration

Returns the current `hitspec.yaml` configuration. Returns an empty object if no config file is present.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/config
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "defaultEnvironment": "dev",
  "timeout": 30000,
  "retries": 0,
  "retryDelay": 1000,
  "followRedirects": true,
  "maxRedirects": 10,
  "validateSSL": true,
  "proxy": "",
  "headers": {
    "User-Agent": "hitspec/1.0"
  },
  "parallel": false,
  "concurrency": 5
}
```

***

### Update Configuration

Partially update the server configuration. Only provided fields are updated; omitted fields remain unchanged. Changes are persisted to the `hitspec.yaml` config file on disk. If no config file exists, one is created in the workspace root.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT http://localhost:8080/api/v1/config \
    -H "Content-Type: application/json" \
    -d '{"timeout": 60000, "parallel": true, "concurrency": 10}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  defaultEnvironment?: string;
  timeout?: number;              // Milliseconds
  retries?: number;
  retryDelay?: number;           // Milliseconds
  followRedirects?: boolean;
  maxRedirects?: number;
  validateSSL?: boolean;
  proxy?: string;
  headers?: Record<string, string>;
  parallel?: boolean;
  concurrency?: number;
}
```

<ParamField type="number">
  Request timeout in milliseconds. `0` resets it to the default (30000).
</ParamField>

<ParamField type="number">
  Number of automatic retries on failure. `0` disables retries.
</ParamField>

<ParamField type="boolean">
  Whether to follow HTTP 3xx redirects.
</ParamField>

<ParamField type="boolean">
  Whether to validate SSL/TLS certificates.
</ParamField>

<ParamField type="string">
  HTTP proxy URL (e.g., `http://proxy:8080`).
</ParamField>

<ParamField type="boolean">
  Whether to run independent requests in parallel.
</ParamField>

<ParamField type="number">
  Maximum number of concurrent requests in parallel mode. `0` resets it to the default (5).
</ParamField>

A key that is present is applied even when it is `0` or `""`: `retries: 0` disables retries and `proxy: ""` clears the proxy. For `timeout`, `retryDelay`, `maxRedirects` and `concurrency`, `0` resets the value to its default. Negative numbers return `400`.

**Response** `200 OK` -- returns the resulting configuration.

***

## History

hitspec maintains two layers of history: a lightweight in-memory history for the current session and a persistent SQLite-backed history stored at `~/.hitspec/history.db`.

### Get In-Memory History

Returns the in-memory execution history for the current server session.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/history
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
[
  {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "requestName": "Get Users",
    "method": "GET",
    "url": "http://localhost:3000/users",
    "statusCode": 200,
    "duration": 245,
    "passed": true,
    "timestamp": "2026-02-10T12:00:00Z"
  }
]
```

***

### Clear In-Memory History

Clear all in-memory history entries.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/history
  ```
</CodeGroup>

**Response** `204 No Content`

***

### List Persistent Runs

Returns paginated persistent run history from the SQLite database.

<CodeGroup>
  ```bash curl theme={null}
  curl "http://localhost:8080/api/v1/history/runs?limit=20&offset=0"
  ```
</CodeGroup>

<ParamField type="number">
  Number of runs to return. Maximum 100.
</ParamField>

<ParamField type="number">
  Number of runs to skip for pagination.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "runs": [
    {
      "id": 42,
      "filePath": "tests/api.http",
      "environment": "dev",
      "startedAt": "2026-02-10T12:00:00Z",
      "finishedAt": "2026-02-10T12:00:01Z",
      "durationMs": 1200,
      "passed": 5,
      "failed": 0,
      "skipped": 1,
      "total": 6
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}
```

***

### Get Run Details

Returns a single run with its full results and assertion details.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/history/runs/42
  ```
</CodeGroup>

<ParamField type="number">
  Numeric run ID.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "id": 42,
  "filePath": "tests/api.http",
  "environment": "dev",
  "startedAt": "2026-02-10T12:00:00Z",
  "finishedAt": "2026-02-10T12:00:01Z",
  "durationMs": 1200,
  "passed": 5,
  "failed": 0,
  "skipped": 1,
  "total": 6,
  "results": [
    {
      "id": 101,
      "requestName": "Get Users",
      "method": "GET",
      "url": "http://localhost:3000/users",
      "statusCode": 200,
      "durationMs": 243,
      "passed": true,
      "description": "Fetch all users",
      "bodyPreview": "{\"data\":[{\"id\":1,\"name\":\"Alice\"}]}",
      "warnings": ["{{nobody.token}} was not resolved and was sent literally (in header X-Token)"],
      "assertions": [
        {
          "id": 201,
          "operator": "equals",
          "subject": "status",
          "expected": "200",
          "actual": "200",
          "passed": true
        }
      ]
    }
  ]
}
```

A result carries `warnings` (an array of strings, omitted when empty) when its request produced non-fatal findings. Runs stored by older versions have none.

***

### Delete a Run

Delete a specific run and all its associated results and assertions (cascade delete).

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/history/runs/42
  ```
</CodeGroup>

<ParamField type="number">
  Numeric run ID.
</ParamField>

**Response** `204 No Content`

***

### Delete All Runs

Delete all persistent run history.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/history/runs
  ```
</CodeGroup>

**Response** `204 No Content`

***

### List Results by Request Name

Retrieve historical results for a specific request, filtered by file path. Useful for comparing how a single request's responses have changed over time. Results are ordered by run start time (newest first).

<CodeGroup>
  ```bash curl theme={null}
  curl "http://localhost:8080/api/v1/history/results?requestName=GetUsers&filePath=api.http&limit=20&offset=0"
  ```
</CodeGroup>

<ParamField type="string">
  The name of the request to look up.
</ParamField>

<ParamField type="string">
  The file path containing the request.
</ParamField>

<ParamField type="number">
  Maximum number of results to return (1–100).
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "results": [
    {
      "id": 101,
      "runId": 42,
      "requestName": "GetUsers",
      "method": "GET",
      "url": "https://api.example.com/users",
      "statusCode": 200,
      "durationMs": 134,
      "passed": true,
      "skipped": false,
      "error": null,
      "bodyPreview": "{\"users\": [...]}",
      "filePath": "api.http",
      "environment": "staging",
      "runStartedAt": "2026-02-19T15:30:00Z",
      "assertions": []
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}
```

***

## Stress Testing

### Start Stress Test

Start a load test against the requests defined in one or more files. Metrics are broadcast in real time over the [WebSocket](#websocket) connection via `stress_update` messages.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/stress/start \
    -H "Content-Type: application/json" \
    -d '{
      "files": ["tests/api.http"],
      "duration": "30s",
      "rate": 50,
      "vus": 10,
      "maxVUs": 20
    }'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  files: string[];       // Required. List of .http/.hitspec files (relative paths)
  duration?: string;     // Required unless profile is set. Go duration string (e.g., "30s", "5m", "1h")
  rate?: number;         // Optional. Target requests per second
  vus?: number;          // Optional. Number of virtual users (switches to VU mode)
  maxVUs?: number;       // Optional. Maximum concurrent virtual users
  profile?: string;      // Optional. Name of a saved stress profile (stress.profiles in hitspec.yaml)
}
```

<ParamField type="string[]">
  List of `.http` or `.hitspec` file paths relative to the workspace.
</ParamField>

<ParamField type="string">
  Duration of the stress test as a Go duration string (e.g., `"30s"`, `"5m"`, `"1h"`). Required unless `profile` is set, in which case the profile's duration is used.
</ParamField>

<ParamField type="string">
  Name of a saved stress profile. The profile's duration, rate, VUs, max VUs, think time, ramp-up and thresholds are the base for the run; `duration`, `rate`, `vus` and `maxVUs` in the request win over the profile's. A threshold written without an operator gets the metric's natural one (`rps` means `>`, the others `<`), and one written with an operator keeps it. An unknown profile is a `400 Bad Request`.
</ParamField>

<ParamField type="number">
  Target requests per second in rate mode.
</ParamField>

<ParamField type="number">
  Number of virtual users. Setting this switches from rate mode to VU mode.
</ParamField>

<ParamField type="number">
  Maximum number of concurrent virtual users.
</ParamField>

**Response** `200 OK`

```json theme={null}
{ "status": "started" }
```

**Error** `409 Conflict` if a stress test is already running.

***

### Stop Stress Test

Stop a running stress test. If no test is currently running, the endpoint returns `200 OK` with an `"already_stopped"` status instead of an error.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/stress/stop
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{ "status": "stopping" }
```

When no test is running:

```json theme={null}
{ "status": "already_stopped" }
```

***

### Get Stress Test Status

Returns whether a stress test is running and, if so, the current metrics.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/stress/status
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "running": true,
  "elapsed": 15.3,
  "duration": 60,
  "stats": {
    "total": 750,
    "success": 745,
    "errors": 5,
    "rps": 49.8,
    "p50Ms": 12.5,
    "p95Ms": 45.2,
    "p99Ms": 120.0,
    "maxMs": 350.0,
    "errorRate": 0.0067,
    "activeVUs": 10,
    "incomplete": 3,
    "assertionChecks": 745,
    "assertionFailures": 2
  }
}
```

`incomplete` counts requests still in flight, and `assertionChecks` / `assertionFailures` count responses that were checked against `expect` lines and those that failed one. Assertion failures are not part of `errors`. The three fields are omitted when zero, and the same fields appear in `stress_update` messages. `duration` is the run's configured length in seconds (from the request or its `profile`), so a client can draw progress as `elapsed / duration`; it is omitted when unknown.

When no stress test is running:

```json theme={null}
{ "running": false, "elapsed": 0, "stats": null }
```

***

### Get Stress Test Result

Returns the result of the last completed stress test, including summary metrics, latency percentiles, and per-request breakdown.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/stress/result
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "durationMs": 30000,
  "total": 1500,
  "success": 1485,
  "errors": 15,
  "timeouts": 0,
  "rps": 50.0,
  "successRate": 0.99,
  "errorRate": 0.01,
  "p50Ms": 12.5,
  "p95Ms": 45.2,
  "p99Ms": 120.0,
  "minMs": 2.1,
  "maxMs": 350.0,
  "meanMs": 25.3,
  "stdDevMs": 18.7,
  "incomplete": 4,
  "assertionChecks": 1485,
  "assertionFailures": 3,
  "assertionFailRate": 0.002,
  "warnings": ["target rate 50/s was not reached (achieved 41/s)"],
  "thresholds": [
    { "name": "p95", "passed": true, "expected": "< 200ms", "actual": "45.2ms" }
  ],
  "breakdown": [
    {
      "name": "Get Users",
      "total": 750,
      "success": 745,
      "errors": 5,
      "p50Ms": 11.0,
      "p95Ms": 40.0,
      "p99Ms": 100.0,
      "meanMs": 22.1,
      "assertionFailures": 2
    }
  ],
  "timeSeries": [],
  "timestamp": "2026-02-10T12:00:30Z"
}
```

`incomplete`, `assertionChecks`, `assertionFailures`, `assertionFailRate`, `warnings`, `thresholds` and `breakdown[].assertionFailures` are omitted when empty or zero. `incomplete` requests were still in flight when the window closed and are not counted in `total` or `errors`. `warnings` describe the run itself, for example a target rate that was not reached.

When the run could not start (invalid settings, a failed setup request), the result has an `error` field saying why and its counters are zero. The final `stress_update` WebSocket event (`"completed": true`) carries the same `error`.

When no result is available:

```json theme={null}
{ "error": "Not Found", "message": "no stress test result available" }
```

***

### List Stress Profiles

Returns the stress test profiles defined in `hitspec.yaml`.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/stress/profiles
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
[
  {
    "name": "smoke",
    "duration": "10s",
    "rate": 5
  },
  {
    "name": "load",
    "duration": "5m",
    "rate": 100,
    "thresholds": {
      "p95": "200ms",
      "errors": "1%"
    }
  },
  {
    "name": "spike",
    "duration": "2m",
    "vus": 200,
    "maxVUs": 500,
    "rampUp": "30s",
    "thinkTime": "500ms"
  }
]
```

***

### Create Stress Profile

Create a new stress profile. The profile is persisted to `hitspec.yaml`.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/stress/profiles \
    -H "Content-Type: application/json" \
    -d '{
      "name": "smoke",
      "duration": "30s",
      "rate": 10,
      "maxVUs": 5
    }'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  name: string;           // Required. Unique profile name
  duration: string;       // Required. Go duration string (e.g., "30s", "5m")
  rate?: number;          // Optional. Target requests per second
  vus?: number;           // Optional. Number of virtual users
  maxVUs?: number;        // Optional. Maximum concurrent virtual users
  rampUp?: string;        // Optional. Ramp-up duration
  thinkTime?: string;     // Optional. Think time between requests per VU
  thresholds?: {          // Optional. Pass/fail thresholds
    p95?: string;
    p99?: string;
    errors?: string;
  };
}
```

<ParamField type="string">
  Unique name for the profile. Must not conflict with an existing profile.
</ParamField>

<ParamField type="string">
  Duration of the stress test as a Go duration string.
</ParamField>

**Response** `201 Created`

```json theme={null}
{ "name": "smoke" }
```

**Error** `409 Conflict` if a profile with the same name already exists.

***

### Update Stress Profile

Update an existing stress profile. The changes are persisted to `hitspec.yaml`.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT http://localhost:8080/api/v1/stress/profiles/smoke \
    -H "Content-Type: application/json" \
    -d '{"duration": "1m", "rate": 20, "maxVUs": 10}'
  ```
</CodeGroup>

<ParamField type="string">
  Name of the profile to update.
</ParamField>

**Request Body:** Same fields as [Create Stress Profile](#create-stress-profile) (except `name`).

**Response** `200 OK`

```json theme={null}
{ "name": "smoke" }
```

**Error** `404 Not Found` if the profile does not exist.

***

### Delete Stress Profile

Delete a stress profile. The deletion is persisted to `hitspec.yaml`.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/stress/profiles/smoke
  ```
</CodeGroup>

<ParamField type="string">
  Name of the profile to delete.
</ParamField>

**Response** `204 No Content`

**Error** `404 Not Found` if the profile does not exist.

***

## Mock Server

### Start Mock Server

Start a mock server that serves responses based on the request/response pairs defined in your `.http` files. Incoming requests to the mock server are broadcast over WebSocket as `mock_request` events.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/mock/start \
    -H "Content-Type: application/json" \
    -d '{"files": ["mocks/users.http"], "port": 3000, "delay": "100ms"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  files: string[];    // Required. List of .http/.hitspec files with mock definitions
  port?: number;      // Optional. Port for the mock server (default: 3000)
  delay?: string;     // Optional. Artificial response delay (Go duration, e.g., "100ms")
}
```

<ParamField type="string[]">
  List of `.http` or `.hitspec` file paths containing request/response pairs.
</ParamField>

<ParamField type="number">
  Port on which the mock server will listen.
</ParamField>

<ParamField type="string">
  Artificial delay before each response, as a Go duration string (e.g., `"100ms"`, `"1s"`).
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "running": true,
  "port": 3000,
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "name": "Get Users",
      "statusCode": 200,
      "contentType": "application/json"
    },
    {
      "method": "POST",
      "path": "/users",
      "name": "Create User",
      "statusCode": 201,
      "contentType": "application/json"
    }
  ]
}
```

**Error** `409 Conflict` if a mock server is already running, or if the port is busy or the address cannot be bound.

***

### Stop Mock Server

Stop the running mock server.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/mock/stop
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{ "status": "stopping" }
```

***

### Get Mock Routes

Returns the current status and registered routes of the mock server.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/mock/routes
  ```
</CodeGroup>

**Response** `200 OK` (when running)

```json theme={null}
{
  "running": true,
  "port": 3000,
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "name": "Get Users",
      "statusCode": 200,
      "contentType": "application/json"
    }
  ]
}
```

**Response** `200 OK` (when not running)

```json theme={null}
{ "running": false }
```

***

## Contract Testing

### Verify Contracts

Run contract verification against a live provider. Sends each request defined in the contract files to the provider URL and validates the responses match expectations.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/contract/verify \
    -H "Content-Type: application/json" \
    -d '{
      "providerUrl": "http://localhost:3000",
      "stateHandler": "./scripts/setup-state.sh",
      "files": ["contracts/users.http"]
    }'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  providerUrl: string;      // Required. Base URL of the provider to verify against
  stateHandler?: string;    // Optional. Path to an executable that sets up provider state (needs --allow-shell)
  files?: string[];         // Optional. Specific contract files (defaults to all workspace files)
}
```

<ParamField type="string">
  The base URL of the provider service to verify contracts against.
</ParamField>

<ParamField type="string">
  Path to a script that is run with the state name as its argument before each interaction that declares a state. Because this executes a program on the server, the request is rejected with `403 Forbidden` unless the server was started with `--allow-shell`, and the script (after resolving symlinks) must be inside the workspace. Relative paths are resolved from the workspace root.
</ParamField>

<ParamField type="string[]">
  List of contract file paths. When omitted, all `.http`/`.hitspec` files in the workspace are used.
</ParamField>

**Response** `200 OK`

```json theme={null}
[
  {
    "file": "contracts/users.http",
    "passed": 3,
    "failed": 0,
    "skipped": 0,
    "duration": 450,
    "results": [
      {
        "name": "Get Users",
        "provider": "UserService",
        "state": "users exist",
        "passed": true,
        "duration": 150
      },
      {
        "name": "Create User",
        "provider": "UserService",
        "state": "no users",
        "passed": true,
        "duration": 200
      }
    ]
  }
]
```

***

### List Contract Files

Returns all `.http`/`.hitspec` files in the workspace that can be used as contract files.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/contract/files
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "files": [
    "contracts/users.http",
    "contracts/orders.http",
    "tests/api.http"
  ]
}
```

***

## Recording Proxy

### Start Recording

Start a recording proxy that captures HTTP traffic passing through it. The proxy forwards requests to the target URL and records both request and response.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/record/start \
    -H "Content-Type: application/json" \
    -d '{
      "targetUrl": "http://localhost:3000",
      "port": 8081,
      "deduplicate": true
    }'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  targetUrl: string;       // Required. URL to proxy requests to
  port?: number;           // Optional. Proxy listen port (default: 8081)
  deduplicate?: boolean;   // Optional. Remove duplicate request recordings
  exclude?: string[];      // Optional. URL patterns to exclude from recording
  sanitize?: string[];     // Optional. Header names to sanitize in recordings
}
```

<ParamField type="string">
  The upstream URL that the proxy forwards requests to.
</ParamField>

<ParamField type="number">
  Port on which the recording proxy will listen.
</ParamField>

<ParamField type="boolean">
  When true, duplicate requests with the same method and path are only recorded once.
</ParamField>

<ParamField type="string[]">
  List of URL path patterns to exclude from recording.
</ParamField>

<ParamField type="string[]">
  List of header names whose values should be sanitized (replaced with placeholders) in the recorded output.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "status": "started",
  "port": 8081
}
```

**Error** `409 Conflict` if a recording proxy is already running, or if the port is busy or the address cannot be bound. `400 Bad Request` if `targetUrl` is missing or is not a valid URL.

***

### Stop Recording

Stop the recording proxy.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/record/stop
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{ "status": "stopping" }
```

***

### Get Recording Status

Returns whether the recording proxy is running, how many requests have been captured, and the captured request details.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/record/status
  ```
</CodeGroup>

**Response** `200 OK` (when running)

```json theme={null}
{
  "running": true,
  "targetUrl": "http://localhost:3000",
  "port": 8081,
  "count": 12,
  "recordings": [
    {
      "method": "GET",
      "path": "/users",
      "url": "http://localhost:3000/users",
      "contentType": "application/json",
      "statusCode": 200,
      "duration": 45
    },
    {
      "method": "POST",
      "path": "/users",
      "url": "http://localhost:3000/users",
      "contentType": "application/json",
      "statusCode": 201,
      "duration": 67
    }
  ]
}
```

**Response** `200 OK` (when not running)

```json theme={null}
{ "running": false, "count": 0 }
```

***

### Export Recordings

Export all captured recordings as `.http` file content. The proxy must be running.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://localhost:8080/api/v1/record/export
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "content": "### Get Users\nGET http://localhost:3000/users\nAccept: application/json\n\n### Create User\nPOST http://localhost:3000/users\nContent-Type: application/json\n\n{\"name\": \"Alice\"}\n"
}
```

***

### Clear Recordings

Clear all captured recordings without stopping the proxy.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://localhost:8080/api/v1/record/clear
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{ "status": "cleared" }
```

***

## Import

### Import curl

Convert a curl command or a file containing curl commands into `.http` format.

<CodeGroup>
  ```bash curl theme={null}
  # From a command string
  curl -X POST http://localhost:8080/api/v1/import/curl \
    -H "Content-Type: application/json" \
    -d '{"command": "curl -X GET https://api.example.com/users -H \"Authorization: Bearer token\""}'

  # From a file
  curl -X POST http://localhost:8080/api/v1/import/curl \
    -H "Content-Type: application/json" \
    -d '{"filePath": "exports/commands.sh"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  command?: string;    // A curl command string to convert
  filePath?: string;   // Path to a file containing curl commands (relative to workspace)
}
```

One of `command` or `filePath` is required.

<ParamField type="string">
  A curl command string to convert to `.http` format.
</ParamField>

<ParamField type="string">
  Path to a file containing curl commands, relative to the workspace.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "content": "### Imported Request\nGET https://api.example.com/users\nAuthorization: Bearer token\n",
  "requestCount": 1
}
```

***

### Import Insomnia

Convert an Insomnia export (JSON) into `.http` format.

<CodeGroup>
  ```bash curl theme={null}
  # From inline JSON data
  curl -X POST http://localhost:8080/api/v1/import/insomnia \
    -H "Content-Type: application/json" \
    -d '{"data": "{\"_type\":\"export\",\"resources\":[...]}"}'

  # From a file
  curl -X POST http://localhost:8080/api/v1/import/insomnia \
    -H "Content-Type: application/json" \
    -d '{"filePath": "insomnia-export.json"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  data?: string;       // Insomnia export JSON as a string
  filePath?: string;   // Path to an Insomnia export file (relative to workspace)
}
```

One of `data` or `filePath` is required.

<ParamField type="string">
  Insomnia export JSON content as a string.
</ParamField>

<ParamField type="string">
  Path to an Insomnia JSON export file, relative to the workspace.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "content": "### Get Users\nGET https://api.example.com/users\n\n### Create User\nPOST https://api.example.com/users\nContent-Type: application/json\n\n{\"name\":\"Alice\"}\n",
  "requestCount": 2
}
```

***

### Import OpenAPI

Convert an OpenAPI specification (YAML or JSON, v2 or v3) into `.http` format. The spec can be a local file path or a URL.

<CodeGroup>
  ```bash curl theme={null}
  # From a local file
  curl -X POST http://localhost:8080/api/v1/import/openapi \
    -H "Content-Type: application/json" \
    -d '{"specPath": "openapi.yaml", "baseUrl": "http://localhost:3000"}'

  # From a URL
  curl -X POST http://localhost:8080/api/v1/import/openapi \
    -H "Content-Type: application/json" \
    -d '{"specPath": "https://petstore.swagger.io/v2/swagger.json"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  specPath: string;    // Required. Path or URL to the OpenAPI spec
  baseUrl?: string;    // Optional. Override the base URL in the spec
}
```

<ParamField type="string">
  Path to the OpenAPI specification file (relative to workspace) or a URL. Supports YAML and JSON, OpenAPI v2 and v3.
</ParamField>

<ParamField type="string">
  Override the base URL from the spec. Useful when the spec references a production URL but you want to target localhost.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "content": "### List Pets\nGET http://localhost:3000/pets\n\n### Create Pet\nPOST http://localhost:3000/pets\nContent-Type: application/json\n\n{\"name\":\"Fido\",\"tag\":\"dog\"}\n",
  "requestCount": 2
}
```

***

## Export

### Export as curl

Convert requests from a `.http`/`.hitspec` file into curl commands.

<CodeGroup>
  ```bash curl theme={null}
  # Export all requests in a file
  curl -X POST http://localhost:8080/api/v1/export/curl \
    -H "Content-Type: application/json" \
    -d '{"file": "tests/api.http"}'

  # Export a specific request
  curl -X POST http://localhost:8080/api/v1/export/curl \
    -H "Content-Type: application/json" \
    -d '{"file": "tests/api.http", "requestName": "Create User"}'
  ```
</CodeGroup>

**Request Body**

```typescript theme={null}
{
  file: string;            // Required. Relative path to the file
  requestName?: string;    // Optional. Export only this named request
}
```

<ParamField type="string">
  Relative path to the `.http` or `.hitspec` file in the workspace.
</ParamField>

<ParamField type="string">
  Name of a specific request to export. When omitted, all requests are exported.
</ParamField>

**Response** `200 OK`

```json theme={null}
{
  "commands": [
    "curl -X GET 'http://localhost:3000/users' -H 'Accept: application/json'",
    "curl -X POST 'http://localhost:3000/users' -H 'Content-Type: application/json' -d '{\"name\":\"Alice\"}'"
  ]
}
```

***

## System

### Get System Info

Returns version, build time, Go version, and platform information.

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/api/v1/system/info
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "version": "2.6.0",
  "buildTime": "2026-02-10T12:00:00Z",
  "goVersion": "go1.25.0",
  "os": "darwin",
  "arch": "arm64"
}
```

***

## WebSocket

### Connect

Establish a WebSocket connection for real-time event streaming. The server pushes events as they occur -- no polling required.

```
ws://localhost:8080/api/v1/ws
```

<Note>
  The WebSocket endpoint accepts connections from `localhost`, `127.0.0.1`, and `[::1]` origins only.
</Note>

**Connection Example**

```javascript theme={null}
const ws = new WebSocket('ws://localhost:8080/api/v1/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.payload);
};

// Keep alive with ping/pong
setInterval(() => {
  ws.send(JSON.stringify({ type: 'ping' }));
}, 30000);
```

### Message Envelope

All WebSocket messages use this envelope format:

```typescript theme={null}
{
  type: string;        // Message type identifier
  payload: any;        // Type-specific payload
  timestamp: string;   // ISO 8601 timestamp (UTC)
}
```

### Message Types

#### `execution_start`

Sent when a request execution begins.

```json theme={null}
{
  "type": "execution_start",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "started",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `request_progress`

Sent for each individual request as it starts and completes during an execution.

```json theme={null}
{
  "type": "request_progress",
  "payload": {
    "execId": "a1b2c3d4",
    "file": "tests/api.http",
    "requestName": "Get Users",
    "status": "completed",
    "index": 0,
    "total": 3,
    "passed": true,
    "duration": 245,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

The `status` field is either `"started"` or `"completed"`. The `passed`, `duration` and `warnings` fields are only present when status is `"completed"`; `warnings` is an array of strings and is omitted when empty.

#### `execution_complete`

Sent when an entire execution finishes. The `result` payload contains the full `RunResultDTO`.

```json theme={null}
{
  "type": "execution_complete",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "completed",
    "result": { "file": "tests/api.http", "duration": 500, "passed": 3, "failed": 0, "skipped": 0, "results": [] },
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `error`

Sent when an execution fails with an error.

```json theme={null}
{
  "type": "error",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "error",
    "error": "parse error: unexpected token at line 5",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `environment_changed`

Sent when the active environment is switched via `PUT /api/v1/environments/active`.

```json theme={null}
{
  "type": "environment_changed",
  "payload": {
    "name": "staging",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `file_changed`

Sent when a `.http` or `.hitspec` file is created, modified, or deleted in the workspace (via filesystem watcher).

```json theme={null}
{
  "type": "file_changed",
  "payload": {
    "path": "tests/api.http",
    "operation": "write",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `stress_update`

Sent every 500ms during an active stress test with current metrics. The `running` and `completed` booleans indicate the test lifecycle -- the UI uses these to detect when a test finishes naturally (without an explicit stop) and transition to the results view.

```json theme={null}
{
  "type": "stress_update",
  "payload": {
    "running": true,
    "completed": false,
    "stats": {
      "total": 750,
      "success": 745,
      "errors": 5,
      "rps": 49.8,
      "p50Ms": 12.5,
      "p95Ms": 45.2,
      "p99Ms": 120.0,
      "maxMs": 350.0,
      "errorRate": 0.0067,
      "activeVUs": 10
    },
    "elapsed": 15.3,
    "duration": 60,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

#### `mock_request`

Sent when the mock server receives a request, or when it starts/stops.

```json theme={null}
{
  "type": "mock_request",
  "payload": {
    "event": "request",
    "method": "GET",
    "path": "/users",
    "status": 200,
    "duration": 1.2,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

The `event` field can be `"started"`, `"stopped"`, or `"request"`.

#### `ping` / `pong`

Clients can send `{"type": "ping"}` messages and the server will respond with a `pong`:

```json theme={null}
{
  "type": "pong",
  "payload": null,
  "timestamp": "2026-02-10T12:00:00Z"
}
```


# hitspec run
Source: https://hitspec.dev/reference/run

Run HTTP API tests from .http and .hitspec files

# hitspec run

Run HTTP API tests defined in `.http` or `.hitspec` files.

```bash theme={null}
hitspec run <file|directory> [flags]
```

## Arguments

| Argument | Description |
| - | - |
| `<file>` | Single `.http` or `.hitspec` file to run |
| `<directory>` | Directory containing test files (searched recursively) |
| `<glob>` | A quoted pattern such as `'tests/**/*.http'` |
| `-` | Read one document from stdin |

You can pass multiple files, directories and patterns as arguments. See [Inputs](#inputs).

## Flags

### Core Flags

| Flag | Short | Description | Default | Env Var |
| - | - | - | - | - |
| `--env` | `-e` | Environment name to use. Order: flag, then `HITSPEC_ENV`, then `defaultEnvironment` in `hitspec.yaml`, then `dev` | `defaultEnvironment`, else `dev` | `HITSPEC_ENV` |
| `--env-file` | | Path to `.env` file for variable interpolation; a missing file is an error (exit code 3) | | `HITSPEC_ENV_FILE` |
| `--config` | | Path to config file (`hitspec.yaml`); default: the nearest one from the working directory upward | | `HITSPEC_CONFIG` |
| `--name` | `-n` | Run only tests matching name pattern | | |
| `--tags` | `-t` | Run only tests with specified tags (comma-separated) | | `HITSPEC_TAGS` |

### Output Flags

| Flag | Short | Description | Default | Env Var |
| - | - | - | - | - |
| `--verbose` | `-v` | Verbose output, repeatable: `-v`, `-vv`, `-vvv` for more detail (see [Verbose Output](#verbose-output)) | `false` | |
| `--quiet` | `-q` | Suppress the report on stdout. Failures are still listed on stderr and `--output-file` is still written | `false` | `HITSPEC_QUIET` |
| `--no-color` | | Disable colored output | `false` | `HITSPEC_NO_COLOR` |
| `--output` | `-o` | Output format: `console`, `json`, `junit`, `tap`, `html`. Overrides `reporters` and `outputDir` in `hitspec.yaml` | `console` | `HITSPEC_OUTPUT` |
| `--output-file` | | Write output to a file instead of stdout. Overrides `reporters` and `outputDir` in `hitspec.yaml` | | `HITSPEC_OUTPUT_FILE` |

### Execution Flags

| Flag | Short | Description | Default | Env Var |
| - | - | - | - | - |
| `--bail` | | Stop on first failure | `false` | `HITSPEC_BAIL` |
| `--timeout` | | Request timeout (e.g., `30s`, `1m`, `500ms`) | `30s` | `HITSPEC_TIMEOUT` |
| `--dry-run` | | Parse each file and list the requests that would run (method, resolved URL, tags, dependencies, skip reasons) without sending anything (see [Dry Run](#dry-run)) | `false` | |
| `--parallel` | `-p` | Run independent requests in parallel | `false` | `HITSPEC_PARALLEL` |
| `--concurrency` | | Max concurrent requests when running in parallel | `5` | `HITSPEC_CONCURRENCY` |
| `--watch` | `-w` | Watch files for changes and re-run tests | `false` | |

### Network Flags

| Flag | Short | Description | Default | Env Var |
| - | - | - | - | - |
| `--proxy` | | Proxy URL for HTTP requests | | `HITSPEC_PROXY` |
| `--insecure` | `-k` | Disable SSL certificate validation | `false` | `HITSPEC_INSECURE` |
| `--cacert` | | PEM CA bundle to trust in addition to the system roots | | `HITSPEC_CACERT` |
| `--cert` | | PEM client certificate for mutual TLS; needs `--key` | | `HITSPEC_CERT` |
| `--key` | | PEM private key for `--cert` | | `HITSPEC_KEY` |
| `--http1.1` | | Do not negotiate HTTP/2 | `false` | `HITSPEC_HTTP1` |
| `--cookies` | | Keep a cookie jar for the run: `Set-Cookie` from one response is sent on later requests | `false` | `HITSPEC_COOKIES` |
| `--max-response-bytes` | | Largest response body to read, in bytes; `-1` for no limit | `104857600` | `HITSPEC_MAX_RESPONSE_BYTES` |
| `--redirect-forward-headers` | | Keep your request headers on redirects to another origin | `false` | `HITSPEC_REDIRECT_FORWARD_HEADERS` |

A CA, certificate or key file that is missing or not valid PEM, and a malformed `--proxy` URL, exit with code 3 before any request is sent. Each of these also has a `hitspec.yaml` key; see [Configuration](/reference/configuration) and [TLS, cookies and HTTP options](/features/tls-and-cookies).

### History Flags

Every run is recorded to a local history database (also browsable in
[studio](/studio)'s History screen).

| Flag | Description | Default | Env Var |
| - | - | - | - |
| `--history-db` | Path to the run-history database | `~/.hitspec/history.db` | `HITSPEC_HISTORY_DB` |
| `--no-history` | Disable run-history recording for this run | `false` | `HITSPEC_NO_HISTORY` |

### Snapshot Flags

| Flag | Description | Default |
| - | - | - |
| `--update-snapshots` | Update snapshot files instead of comparing against them | `false` |

### Security Flags

| Flag | Description | Default |
| - | - | - |
| `--allow-shell` | Allow shell command execution (`>>>shell` blocks and hooks) | `false` |
| `--allow-db` | Allow database assertions (`>>>db` blocks) | `false` |

### Coverage Flags

| Flag | Description | Default |
| - | - | - |
| `--coverage` | Generate API coverage report against OpenAPI spec | `false` |
| `--openapi` | Path to OpenAPI spec file for coverage analysis | |

<Warning>
  Shell and database blocks are disabled by default for security. You must explicitly opt in with `--allow-shell` or `--allow-db` when your test files use these features.
</Warning>

### Stress Testing Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--stress` | | Enable stress testing mode | `false` |
| `--duration` | `-d` | Stress test duration (e.g., `30s`, `5m`, `1h`) | `30s` |
| `--rate` | `-r` | Target requests per second | `10` |
| `--vus` | | Number of virtual users (alternative to `--rate`) | `0` |
| `--max-vus` | | Maximum concurrent requests | `100` |
| `--think-time` | | Think time between requests per virtual user | `0s` |
| `--ramp-up` | | Ramp-up time to reach target rate/VUs | `0s` |
| `--threshold` | | Pass/fail thresholds (e.g., `"p95<200ms,errors<0.1%"`). Metrics: `p50`, `p95`, `p99`, `max`, `errors` (transport errors and non-2xx), `assertions` (assertion failure share), `rps` | |
| `--profile` | | Load a stress profile from config file | |
| `--no-progress` | | Disable real-time progress display | `false` |
| `--stress-json` | | Output stress results as JSON | `false` |

### Metrics Flags

| Flag | Description | Default | Env Var |
| - | - | - | - |
| `--metrics` | Export format: `prometheus`, `datadog`, `json`. Only applies with `--stress`; without it a warning is printed and nothing is exported | | `HITSPEC_METRICS` |
| `--metrics-port` | Port for Prometheus metrics HTTP endpoint | `9090` | `HITSPEC_METRICS_PORT` |
| `--metrics-host` | Interface the Prometheus endpoint binds; `0.0.0.0` exposes it to the network | `127.0.0.1` | `HITSPEC_METRICS_HOST` |
| `--metrics-file` | Output file for JSON metrics | | `HITSPEC_METRICS_FILE` |
| `--datadog-api-key` | DataDog API key | | `DD_API_KEY` |
| `--datadog-site` | DataDog site | `datadoghq.com` | `DD_SITE` |
| `--datadog-tags` | Comma-separated DataDog tags | | `DD_TAGS` |

### Notification Flags

| Flag | Description | Default | Env Var |
| - | - | - | - |
| `--notify` | Notification service: `slack`, `teams` | | `HITSPEC_NOTIFY` |
| `--notify-on` | When to notify: `always`, `failure`, `success`, `recovery` | `failure` | `HITSPEC_NOTIFY_ON` |
| `--slack-webhook` | Slack webhook URL | | `SLACK_WEBHOOK` |
| `--slack-channel` | Slack channel override | | `SLACK_CHANNEL` |
| `--teams-webhook` | Microsoft Teams webhook URL | | `TEAMS_WEBHOOK` |

## Examples

### Basic Usage

<CodeGroup>
  ```bash Run a single file theme={null}
  hitspec run tests/api.http
  ```

  ```bash Run a directory theme={null}
  hitspec run tests/
  ```

  ```bash Run with a specific environment theme={null}
  hitspec run tests/ --env staging
  ```

  ```bash Run specific tests by name theme={null}
  hitspec run tests/ --name "Login"
  ```

  ```bash Run tests by tag theme={null}
  hitspec run tests/ --tags smoke
  ```
</CodeGroup>

### Filtering

```bash theme={null}
# Run only smoke-tagged tests
hitspec run tests/ --tags smoke

# Multiple tags (OR logic)
hitspec run tests/ --tags smoke,critical

# Filter by name pattern (glob matching)
hitspec run tests/ --name "User*"
hitspec run tests/ --name "*Profile"

# Combine filters
hitspec run tests/ --tags smoke --name "*Auth*"
```

If the filters select no request in any of the files (for example a typo such as `--tags smok`), hitspec prints `no requests matched --tags "smok"` to stderr and exits with code `64`. A filter only needs to match in one of the files of the run. Requests skipped on purpose with `@skip` still count as matches.

When a selected request has `@depends`, the requests it depends on are run too (transitively) even if the filters would exclude them, and they are reported like any other request. A dependency that fails still causes its dependents to be skipped.

### Quiet Mode

`--quiet` keeps stdout empty, but it never hides failures:

* With `--output-file`, the formatted report is still written to the file.
* When anything fails, one line per failed request is written to stderr with the request name and the first failing assertion or error.
* Exit codes are unchanged.

```bash theme={null}
hitspec run tests/ --quiet --output junit --output-file results.xml
```

### Files That Cannot Be Loaded

A file with a syntax error, a duplicate `@name`, or a circular `@depends` does not stop the run. The remaining files still run, the error is written to stderr (for example `1 file failed to parse`), and the run exits with code `2`. With `--output json`, `junit`, `tap` or `html`, the broken file also appears in the report as an error entry.

### Parallel Execution

```bash theme={null}
# Run independent requests in parallel
hitspec run tests/ --parallel

# Set concurrency limit
hitspec run tests/ --parallel --concurrency 10
```

<Note>
  Requests with dependencies (`@depends`) always run sequentially. Only independent requests run in parallel. Captured variables are not shared between parallel requests.
</Note>

### Watch Mode

```bash theme={null}
# Watch files and re-run on changes
hitspec run tests/ --watch

# Combine with tags for focused development
hitspec run tests/ --watch --tags dev
```

`--watch` re-runs when a test file changes, including editors that save by renaming a temp file over it, and when `hitspec.yaml`, `--config` or the env file changes. The settings are reloaded before the next pass, and `--output-file` is rewritten each time. `node_modules`, `vendor` and `.git` are not watched. With `--cookies`, the cookie jar is kept across re-runs.

### Inputs

`hitspec run -` reads one document from stdin. Relative paths in it resolve against the working directory. It cannot be combined with other files, `--watch` or `--stress`; `--dry-run` works with it.

```bash theme={null}
hitspec run - < api.http
```

Quote glob patterns so the shell does not expand them: `hitspec run 'tests/**/*.http'`. `**` matches any depth.

Directories are searched recursively, skipping `.git`, `node_modules` and `vendor` unless you name one of them explicitly. A file given more than once runs once. A pattern or path that matches no `.http` or `.hitspec` file is an error (exit code `1`); so is empty stdin. Combining `-` with other files, `--watch` or `--stress` exits with code `64`.

Ctrl+C (or SIGTERM) stops the run: hitspec reports the requests that finished, marks the rest as cancelled, writes `--output-file`, and exits with code `130`. A second Ctrl+C exits immediately.

### Verbose Output

`-v` can be repeated; each level adds detail for every request, not only failures.

| Flag | Output |
| - | - |
| (none) | One line per request. A failed request also shows the request line, the response status line with its duration, and a capped body excerpt. |
| `-v` | The request line and response status of every request, plus captures, SSE events and structured diffs. Also prints the `hitspec.yaml` in use (`config: <path>`) on stderr. |
| `-vv` | Adds request and response headers. Credentials (`Authorization`, `Cookie`, `Set-Cookie`, anything with `api-key`, `token`, `secret` or `password` in its name) print as `[REDACTED]`. |
| `-vvv` | Adds the full request and response bodies, uncapped. |

Warnings (a capture that matched nothing, a `{{reference}}` sent unresolved) print in yellow under the request at every level, and are also written to stderr. They never change the exit code.

### Dry Run

`--dry-run` parses each file and prints what would run, in execution order, without sending anything or touching the history database.

```text theme={null}
Would run: api.http (2 to run, 1 skipped)
  1.  login  POST https://api.example.com/auth/login?v=2
        tags: smoke, auth
  -   legacy  GET https://api.example.com/legacy
        skipped: down for maintenance
  2.  profile  GET https://api.example.com/me?token={{login.token}}
        tags: auth
        depends: login
```

Environment and file variables are resolved in the URL. References to captured values (`{{login.token}}`) are left as written. Requests that would not run are marked `-` with the reason: the `@skip` text, `filtered out`, `condition not met`, or `dependency will not run`. An `@if` that depends on a captured value is listed with a note, because only a real run can decide it. `--name` and `--tags` apply as in a real run.

`--dry-run` cannot be combined with `--stress` (usage error, exit `64`; nothing is sent). With `--dry-run`, `-o` and `--output-file` are ignored: the plan is always text (a note on stderr says so) and the output file is not created.

Exit codes: `0` on success, `2` if a file cannot be loaded (syntax error, duplicate `@name`, `@depends` cycle), `64` if the filters match nothing.

### Output Formats

<CodeGroup>
  ```bash Console (default) theme={null}
  hitspec run tests/
  ```

  ```bash JSON theme={null}
  hitspec run tests/ --output json
  ```

  ```bash JUnit XML (for CI/CD) theme={null}
  hitspec run tests/ --output junit --output-file results.xml
  ```

  ```bash TAP theme={null}
  hitspec run tests/ --output tap
  ```

  ```bash HTML theme={null}
  hitspec run tests/ --output html --output-file report.html
  ```
</CodeGroup>

### Stress Testing

<CodeGroup>
  ```bash Rate-based stress test theme={null}
  hitspec run api.http --stress --duration 1m --rate 100
  ```

  ```bash Virtual user mode theme={null}
  hitspec run api.http --stress --vus 50 --think-time 1s
  ```

  ```bash With pass/fail thresholds theme={null}
  hitspec run api.http --stress -d 1m -r 100 --threshold "p95<200ms,errors<0.1%"
  ```

  ```bash Load profile from config theme={null}
  hitspec run api.http --stress --profile load --env staging
  ```
</CodeGroup>

### CI/CD Integration

```bash theme={null}
# GitHub Actions example
hitspec run tests/ \
  --env staging \
  --output junit \
  --output-file test-results.xml \
  --bail
```

```bash theme={null}
# With notifications on failure
hitspec run tests/ \
  --env staging \
  --notify slack \
  --slack-webhook "$SLACK_WEBHOOK" \
  --notify-on failure
```

### Snapshot Testing

```bash theme={null}
# First run creates snapshots in __snapshots__/
hitspec run tests/

# Update snapshots when expected changes occur
hitspec run tests/ --update-snapshots
```

### Security Flags

```bash theme={null}
# Allow shell blocks and database assertions
hitspec run tests/ --allow-shell --allow-db

# Only allow shell execution
hitspec run tests/ --allow-shell
```

## Exit Codes

| Code | Constant | Description |
| - | - | - |
| `0` | `ExitSuccess` | All tests passed |
| `1` | `ExitTestFailure` | One or more tests failed |
| `2` | `ExitParseError` | A file could not be loaded (invalid syntax, duplicate `@name`, `@depends` cycle) |
| `3` | `ExitConfigError` | Configuration error (a `hitspec.yaml` that cannot be parsed, an `--env-file` that does not exist, a missing or invalid `--cacert`, `--cert`, `--key` or `--proxy`) |
| `4` | `ExitNetworkError` | A request got no response because the connection failed (refused, unreachable, DNS, TLS, reset before a response, timeout before connecting, unreachable OAuth2 token endpoint). A timeout after connecting is a failure (`1`) |
| `64` | `ExitUsageError` | Usage error (unknown flag, bad flag value, missing argument, `-` combined with other files, `--dry-run` with `--stress`), or `--name`/`--tags` matched no request |
| `130` | `ExitInterrupted` | Interrupted (Ctrl+C or SIGTERM): partial results printed, `--output-file` written |

When several apply: `130`, then `2`, then `4`, then `1`, then `64`. See [Exit Codes](/reference/exit-codes).

## Environment Variables

All flags that support environment variables are listed in the flag tables above. Environment variables are read at startup and can be overridden by explicit flags.

Common variables:

```bash theme={null}
export HITSPEC_ENV=staging
export HITSPEC_TIMEOUT=60s
export HITSPEC_OUTPUT=json
export HITSPEC_BAIL=true
export HITSPEC_PARALLEL=true
export HITSPEC_CONCURRENCY=10
```


# hitspec validate & list
Source: https://hitspec.dev/reference/validate-list

Validate syntax and list requests in hitspec files

# hitspec validate

Validate `.http` and `.hitspec` files for syntax errors without executing them.

```bash theme={null}
hitspec validate [--strict] [--json] <file|directory>
```

## Arguments

| Argument | Description |
| - | - |
| `<file>` | Single `.http` or `.hitspec` file to validate |
| `<directory>` | Directory to search recursively for test files |

## Flags

| Flag | Description |
| - | - |
| `--strict` | Treat warnings as errors, and also require every `{{variable}}` to be defined somewhere |
| `--json` | Print the results as JSON (`file`, `ok`, `errors`, `warnings`) |

## Behavior

The `validate` command parses each file without running it. Findings are either **errors** or **warnings**.

**Errors** are constructs that would give a wrong result, or that `hitspec run` refuses. They are reported with `file:line:column` and the command exits with code 2 (the same code `run` uses for a file that fails to load):

* An unknown assertion operator (`contians`, `=`, `===`, `equals`), with a "did you mean" hint
* An operator without a value, or extra values (`expect status 200 201`)
* A misspelt `expect`, block type (`>>>captur`) or `type` name, and lines inside `>>>` or `>>>capture` blocks that are not assertions or captures
* Invalid `matches` regular expressions, and `@auth` problems
* Unclosed `>>>` blocks, and blocks that are not inside a request
* Duplicate request names, and circular `@depends`
* An empty file or a request without a URL

**Warnings** are constructs that are probably mistakes but may be intentional. They are printed under the file's `OK` line and do not change the exit code:

* An unknown `# @directive` (a typo such as `# @tag` instead of `# @tags`). Custom directives start with `x-` (`# @x-owner`); `@contract.*` is also accepted
* An invalid `@timeout`, `@retry`, `@retryDelay` or `@retryOn` value
* `# @directive` lines at the top of a file that lead into no request
* A `@depends` on a request that does not exist in the file
* A capture path containing spaces (it can never match)
* An unknown key in `hitspec.yaml` (for example `tiemout`), with a "did you mean" hint. `validate` checks the nearest `hitspec.yaml` from the working directory upward and lists it before the test files

With `--strict`, every warning is an error (exit code 2), including an unknown `hitspec.yaml` key, and `validate` additionally checks variables:

* `{{name}}` must be defined in the file (`@name = ...`), by a `>>>capture` block, in an `environments:` entry of the nearest `hitspec.yaml`, in a `.env` file next to the file or in the working directory, or in the process environment. `{{$uuid()}}`, `{{$env(NAME)}}` and other built-ins are never flagged.
* `{{request.capture}}` must name a capture that request has, and the using request should `# @depends` on it.

<Note>
  Variable checking is a static check. It cannot know which environment a later `hitspec run --env` selects or what a CI job injects, so it accepts a name defined in *any* environment and in the current process environment. That is why it is only enabled by `--strict`.
</Note>

If all files are valid, each is printed as `OK    <file>`. If any file has errors, the command prints each error and exits with code 2. A `hitspec.yaml` that cannot be parsed stops `validate` with exit code 3 (a configuration error) and a `file:line` message.

## Examples

<CodeGroup>
  ```bash Validate a single file theme={null}
  hitspec validate tests/api.http
  ```

  ```bash Validate all files in a directory theme={null}
  hitspec validate tests/
  ```
</CodeGroup>

### Sample Output

```
OK    tests/auth.http
OK    tests/users.http
      warning: tests/users.http:4:1: unknown directive @tag (did you mean @tags?)
FAIL  tests/broken.http
      tests/broken.http:15:18: unknown operator "contians" (did you mean "contains"?)
  expect body.name contians "Jane"
                   ^

3 file(s) checked, 1 error(s), 1 warning(s)
```

### Use in CI/CD

```bash theme={null}
# Validate before running tests
hitspec validate tests/ && hitspec run tests/ --env staging

# Fail on warnings too
hitspec validate --strict tests/
```

```yaml theme={null}
# GitHub Actions
- name: Validate test files
  run: hitspec validate --strict tests/
```

***

# hitspec list

List all requests defined in `.http` and `.hitspec` files.

```bash theme={null}
hitspec list <file|directory>
```

## Arguments

| Argument | Description |
| - | - |
| `<file>` | Single `.http` or `.hitspec` file |
| `<directory>` | Directory to search recursively for test files |

## Behavior

The `list` command parses each file and prints each request with its name and tags. If a request has no `@name` annotation, the method and URL are used as the display name.

## Examples

<CodeGroup>
  ```bash List requests in a file theme={null}
  hitspec list tests/api.http
  ```

  ```bash List all requests in a directory theme={null}
  hitspec list tests/
  ```
</CodeGroup>

### Sample Output

```
tests/api.http:
  - healthCheck
    tags: [smoke]
  - login
    tags: [auth]
  - getProfile
    tags: [users]
  - updateProfile
    tags: [users]
```

### Use Cases

* Discover available tests in a project
* Verify request names before filtering with `--name`
* Audit tag coverage across test files
* Quick inventory of API endpoints under test


# hitspec version
Source: https://hitspec.dev/reference/version

Print the installed hitspec version and build information.

# hitspec version

Print version information for the installed hitspec binary.

```bash theme={null}
hitspec version
```

Output includes the release version and the build time:

```
hitspec version 2.14.1
Built: 2026-06-15_19:20:00
```

<Note>
  A binary built from source without release metadata reports `dev` for the
  version and `unknown` for the build time.
</Note>

## Shortcut flag

The root command also accepts `-v` / `--version` to print the version:

```bash theme={null}
hitspec --version
hitspec -v
```

Use `hitspec version` when you want the full version-plus-build-time output, or in
scripts and bug reports.


# hitspec studio — a keyboard-first terminal API client
Source: https://hitspec.dev/studio

hitspec studio is a keyboard-first terminal UI for .http files — edit, run, and inspect requests with a tabbed viewer, plus stress, mock, record, and history.

`hitspec studio` opens an interactive, keyboard-first workspace for your `.http`
files without leaving the terminal. It is the fastest way to explore an API: edit
a request, run it, inspect the tabbed response, and copy it out as curl or code --
all from one screen.

```bash theme={null}
hitspec studio                 # open the current directory
hitspec studio ./tests/        # open a directory
hitspec studio ./tests/users.http   # open a single file
hitspec studio --read-only     # browse and run, but refuse file and settings writes
```

<Note>
  `ui` is an alias for `studio`, so `hitspec ui` does the same thing. The older
  `hitspec serve` command still opens studio for backward compatibility, but
  `hitspec studio` is the dedicated command. Use `hitspec serve --api-only` when
  you want the REST/WebSocket API server instead of the UI.
</Note>

## What you get

* **Inline editing** -- a syntax-highlighted source pane you can edit and save (`ctrl+s`).
* **Run + tabbed response viewer** -- body, headers, assertions, timing, and captures.
* **Nine screens** -- workspace, stress, mock, contract, record, history, import, cookies, and settings.
* **Command palette** (`ctrl+p`) -- every action, searchable.
* **Copy/export** -- copy a request as curl, HTTPie, Python, JS `fetch`, Go, Ruby, or wget, including method, URL, headers, and body.
* **Environment + theme switchers** -- change the active environment (`ctrl+e`) or color theme (`ctrl+t`) live.
* **Workspace search** (`ctrl+f`) and **file watching** -- the file list and runs update as files change on disk.

## Layout

The workspace screen is split into panes you cycle through with `tab` /
`shift+tab`:

| Pane | What it shows |
| - | - |
| **Files** | The `.http` / `.hitspec` files in the workspace |
| **Requests** | The named requests inside the selected file |
| **Source** | The raw, syntax-highlighted request source (editable) |
| **Response** | The tabbed response viewer after a run |

A top bar shows the active environment and version; a bottom navigation strip and
status line show the current screen, contextual key hints, and toasts.

The layout adapts to the terminal. From 120 columns the source and response sit
side by side; below that they share one panel, and studio switches that panel to
the response when a run finishes (`tab` brings the source back). On a short
terminal (under 30 rows) the headers and assertions row is dropped so the
request list and the main panel keep their room. The headers and assertions
panels follow the request highlighted in the list: what the file declares for it,
or what it returned on its last run.

## Screens

Press a number key (or use the palette) to switch screens:

| Key | Screen | Purpose |
| - | - | - |
| `1` | Workspace | Browse, edit, and run requests |
| `2` | Stress | Run a load test and watch live metrics (progress follows the run's own duration) |
| `3` | Mock | Start/stop a mock server from your files |
| `4` | Contract | Contract-test against an OpenAPI spec |
| `5` | Record | Start/stop a recording proxy and export captured traffic |
| `6` | History | Browse persistent run history with drill-down |
| `7` | Import | Import from curl, OpenAPI, Postman, or Insomnia |
| `8` | Cookies | Inspect the local cookie store (one global file shared by every workspace) |
| `9` | Settings | View/edit config and environments |

## Keyboard shortcuts

Press `?` at any time for the in-app keyboard reference.

### Screens

| Key | Action |
| - | - |
| `1`-`9` | Jump to workspace, stress, mock, contract, record, history, import, cookies, settings |

### Workspace

| Key | Action |
| - | - |
| `enter` | Open / select |
| `e` | Edit source (focus the inline editor) |
| `ctrl+s` | Save the edited file |
| `r` | Run the active request |
| `R` | Run every request in the file |
| `x` | Cancel the run in progress |
| `<` / `>` (or `,` / `.`) | In the response pane, show the previous / next request of a file run |
| `ctrl+r` | Refresh the workspace (rescan files + config) |
| `n` | New scratch file |
| `g` | Generate a sample project (`hitspec.yaml` + `example.http`) |
| `D` | Delete the selected file |

`r` and `R` run what is in the editor, including edits you have not saved yet;
the file on disk is not touched. A run takes the whole terminal's attention: a
second `r` while one is running is ignored, and `x` (or `ctrl+c`) cancels it --
requests that had not started are skipped. After a file run, `<` and `>` step
through every request's response; the run opens on its first failing request.

### Unsaved edits

Studio never drops your edits silently. Opening another file (`enter` in the file
list, search), creating one, importing, renaming or duplicating, generating a
sample, and quitting (`q` or `ctrl+c`) all ask first when the editor has unsaved
changes. `ctrl+s` also checks the file on disk: if it was modified outside studio
since you opened it, studio asks before overwriting it. If the open file is
deleted outside studio while you have unsaved edits, studio keeps them, warns that
the file was deleted on disk, and `ctrl+s` recreates the file from the editor.

### Forms (stress, mock, contract, record, import, cookies, settings)

The screens that start something show a form with empty fields; the placeholder
is the value used when a field is left blank. Nothing starts until you ask:

| Key | Action |
| - | - |
| `e` or `enter` | Edit the fields |
| `tab` / `shift+tab` or `enter` | Next / previous field (while editing) |
| `ctrl+s` | Submit while editing the fields |
| `s` | Submit when not editing the fields |
| `x` | Stop (stress, mock, record) |
| `esc` | Leave the fields, then go back to the workspace |

`enter` never submits a form, so a stray key cannot start a load test.

### Stress profiles

The last field of the stress form is `profile`. Type the name of a stress
profile saved in `hitspec.yaml` and start the test: the profile's duration, rate,
VUs and thresholds apply. With a profile named, a blank `duration`, `rate`,
`vus` or `max vus` keeps the profile's value, and a value you type wins over it.
Without a profile, blank fields use the defaults shown (30s at 5 RPS). The idle
stress screen lists the saved profile names; an unknown name shows an error and
starts nothing.

### Global

| Key | Action |
| - | - |
| `ctrl+p` | Command palette |
| `ctrl+e` | Switch environment |
| `ctrl+t` | Switch theme |
| `ctrl+f` | Search requests (`enter` opens the file and selects the request) |
| `tab` / `shift+tab` | Next / previous pane |
| `esc` | Cancel / close an overlay |
| `?` | Help overlay |
| `q` / `ctrl+c` | Quit (`ctrl+c` cancels a run in progress first) |

## Command palette

Press `ctrl+p` to open the command palette -- a searchable list of every action.
Type `/` then a short, unique query to filter, then `enter` to run the highlighted
command. The palette covers everything in the keymap plus actions that have no
dedicated key, including:

* **Run** the active request or whole file, **save**, **edit**, **refresh**.
* **File operations** -- new, rename, duplicate, delete, and generate a sample project.
* **Copy/export** the selected request as curl, HTTPie, Python, JS `fetch`, or Go, and copy the last response body.
* **Quick request (ad-hoc)** -- run a one-off request by URL without saving a file.
* **Stress / mock / record** -- start and stop the load test, mock server, and recording proxy; export or clear recordings.
* **History / cookies / settings** -- open those screens, or clear run history.
* **Go to** `<screen>` -- jump to any of the nine screens by name.

## Copy a request as code

Select a request and use the palette (`ctrl+p`) to copy it in the format you need:

| Command | Output |
| - | - |
| Copy request as curl | A complete `curl` command |
| Copy request as HTTPie | An `http` (HTTPie) command |
| Copy request as Python | Python `requests` code |
| Copy request as fetch | A JavaScript `fetch()` snippet |
| Copy request as Go | Go `net/http` code |
| Copy response body | The last response body |

Each snippet includes the request's method, URL, headers, and body, so it is a
runnable copy you can paste and tweak. It is the request highlighted in the list
(named or not) as it is in the editor, and `{{variables}}` are filled in from the
file and the active environment, the same values a run would use.

<Note>
  Every format includes query parameters and renders `@auth bearer`, `basic`,
  `apiKey` and `apiKeyQuery` as the matching header or query parameter; other
  `@auth` types get a comment asking you to add the credentials. The **curl**
  export is the most complete: the other formats skip requests with multipart or
  file bodies and show a `SKIPPED` comment in their place.
</Note>

## Ad-hoc requests

Use **Quick request (ad-hoc)** from the palette to fire a one-off request by URL
and view the response without creating a file -- handy for a quick probe while you
work.

## Environments

Press `ctrl+e` to open the environment switcher and pick the active environment.
The default environment is the `defaultEnvironment` from `hitspec.yaml`, else `dev`;
override it at launch with `--env` (and point at a specific config file with `--config`):

```bash theme={null}
hitspec studio ./tests/ --env staging
hitspec studio ./tests/ --config ./ci/hitspec.yaml
```

Requests, stress runs, the mock server and contract verification all resolve
`{{variables}}` such as `{{baseUrl}}` from the active environment.

The top bar always shows which environment is active, and the Settings screen
(`9`) lets you view and edit environment variables. See
[Environments](/concepts/environments) for how environments are defined.

The Settings screen also edits `hitspec.yaml` values such as `timeout`, `proxy`,
`headers`, `validateSSL` and `followRedirects`. Studio uses them for every request
it sends -- single requests, file runs, ad-hoc requests, stress runs and contract
checks -- exactly as `hitspec run` does, and a change you save applies to the next
run. The `HITSPEC_TIMEOUT`, `HITSPEC_PROXY`, `HITSPEC_INSECURE`,
`HITSPEC_PARALLEL`, `HITSPEC_CONCURRENCY` and `HITSPEC_BAIL` environment variables
take precedence over `hitspec.yaml` (the environment itself is chosen with
`--env`). See the
[configuration reference](/reference/configuration) for the full list.

## Themes

Press `ctrl+t` to open the theme picker, or set a theme at launch with `--theme`:

```bash theme={null}
hitspec studio --theme "Tokyo Night"
```

Built-in themes:

* Nord
* Catppuccin Mocha
* Dracula
* Tokyo Night
* Gruvbox Dark

## File watching

Studio watches the workspace by default (`--watch`, on by default) and refreshes
the file list and live execution progress as files change on disk. Disable it with
`--watch=false` if you prefer a static view.

## Flags

| Flag | Short | Description | Default |
| - | - | - | - |
| `--watch` | `-w` | Watch for file changes | `true` |
| `--read-only` | | Refuse workspace and `hitspec.yaml` writes (running requests still works) | `false` |
| `--env` | `-e` | Default environment | `defaultEnvironment` from config, else `dev` |
| `--config` | | Path to `hitspec.yaml` | |
| `--verbose` | `-v` | Verbose logging | `false` |
| `--allow-shell` | | Allow shell command execution | `false` |
| `--allow-db` | | Allow database assertions | `false` |
| `--log-format` | | Log format: `text` or `json` | `text` |
| `--log-level` | | Log level: `debug`, `info`, `warn`, `error` | `info` |
| `--theme` | | Color theme (see [Themes](#themes)) | |
| `--mouse` | | Capture the mouse for wheel scrolling | `false` |

Studio does not capture the mouse by default, so your terminal can select and copy
text as usual. Pass `--mouse` if you want the wheel to scroll the response pane;
the terminal's own selection then needs a modifier key (usually `shift`).

<Warning>
  Shell commands and database assertions are disabled by default. Pass
  `--allow-shell` and/or `--allow-db` to enable them in studio, the same as with
  `hitspec run`.
</Warning>

## Read-only mode

`--read-only` protects the workspace and `hitspec.yaml`: saving, creating, renaming and deleting files and editing settings or cookies are refused. Running requests, stress, mock, record and contract verification still work, and read-only runs do not save cookies. Use it to browse or demo a workspace without risking changes:

```bash theme={null}
hitspec studio ./tests/ --read-only
```

## Next steps

<Columns>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Write and run your first test, then open it in studio.
  </Card>

  <Card title="Editor Setup" icon="code" href="/editor-setup">
    Syntax highlighting and completions in VS Code, Neovim, and more.
  </Card>

  <Card title="Stress Testing" icon="gauge-high" href="/features/stress-testing">
    Drive a load test from the stress screen.
  </Card>

  <Card title="API Client Manager" icon="layer-group" href="/guides/api-client-manager">
    How studio and `serve` share one in-process manager.
  </Card>
</Columns>