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

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

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

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.