Skip to main content

​
hitspec mock

Start an HTTP mock server that responds based on requests and assertions defined in your hitspec files. 
hitspec mock <file|directory> [flags]

​
Arguments

ArgumentDescription
<file>Single .http or .hitspec file to derive routes from
<directory>Directory containing test files (searched recursively)

​
Flags

FlagShortDescriptionDefault
--port-pPort to run the mock server on3000
--delay-dArtificial delay for all responses (e.g., 100ms, 1s)0
--verbose-vEnable verbose loggingfalse

​
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
  • Handles graceful shutdown on Ctrl+C (SIGINT/SIGTERM)

​
Examples

hitspec mock api.http

​
Sample Output

Loaded 12 routes from 3 files
Mock server started on http://localhost: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. 
hitspec record [flags]

​
Flags

FlagShortDescriptionDefault
--port-pPort to run the proxy on8080
--target-tTarget URL to proxy to (required)
--output-oOutput file pathstdout
--excludePaths to exclude from recording (comma-separated)
--verbose-vEnable verbose loggingfalse
--dedupeSkip duplicate requests (same method + path)false
--jsonExport as JSON instead of .http formatfalse

​
Behavior

The recording proxy:
  • Forwards all requests to the target server (reverse proxy mode)
  • Records both requests and responses
  • Sanitizes sensitive headers (Authorization, Cookie, etc.)
  • Exports to .http format on shutdown (Ctrl+C)
  • Supports deduplication of repeated requests

​
Examples

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

​
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

Proxy listening on http://localhost:8080
Forwarding 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.