hitspec mock

hitspec mock <file|directory> [flags]

Arguments

Flags

Behavior

• 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

hitspec mock api.http

hitspec mock api.http --port 8080

hitspec mock api.http --port 3000 --delay 100ms

hitspec mock tests/ --verbose

hitspec mock api.http --host 0.0.0.0

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

hitspec record [flags]

Flags

Behavior

• 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

hitspec record --target https://api.example.com -o recorded.http

hitspec record --port 9090 --target https://api.example.com

hitspec record --target https://api.example.com --exclude "/health,/metrics" -o api.http

hitspec record --target https://api.example.com --dedupe -o api.http

hitspec record --target https://api.example.com --json -o recordings.json

Workflow

1. Start the recording proxy pointing at your real API:
   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.