> ## Documentation Index
> Fetch the complete documentation index at: https://hitspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mock server from .http files

> 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`  |
| `--delay` | Artificial response delay | `0`     |

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