Mock server from .http files

The mock server is an experimental feature. The syntax and behavior may change in future releases.

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

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

A >>>mock block — if present, its content is returned verbatim as the response body.
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:

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

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

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:

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

{
  "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:

hitspec mock api.http --host 0.0.0.0

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.

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:

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:

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

hitspec mock api.http --port 3000

Then test against it:

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

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.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Mock server from .http files

Basic Usage

How It Works

Custom Mock Responses

Inferring the Response from Assertions

Flags

Network Access

Methods, HEAD and CORS

Adding Artificial Delay

Example