httptest

Local HTTP test server CLI for development. Echo requests, serve static files, or mock APIs.

Installation

pip install httptest-cli

Quick Start

# Echo all requests back as JSON
httptest echo

# Serve static files
httptest static ./public

# Mock API from JSON spec
httptest mock api.json

# Record requests to file
httptest record -o requests.jsonl

# Replay recorded requests
httptest replay requests.jsonl -t http://localhost:3000

Commands

echo

Echo all incoming requests back as JSON. Useful for debugging webhooks or API clients.

httptest echo                    # Start on port 8080
httptest echo -p 3000            # Custom port
httptest echo -r requests.jsonl  # Record all requests

Response format:

{
  "timestamp": "2026-02-04T12:00:00.000Z",
  "method": "POST",
  "path": "/webhook",
  "query": {"foo": ["bar"]},
  "headers": {"Content-Type": "application/json", ...},
  "body": {"event": "user.created"},
  "client": {"address": "127.0.0.1", "port": 54321}
}

static

Serve static files from a directory with automatic index.html and directory listings.

httptest static ./public         # Serve ./public directory
httptest static . -p 3000        # Current dir on port 3000
httptest static dist --index main.html  # Custom index file

mock

Serve mock API responses from a JSON spec file.

httptest mock api.json
httptest mock spec.json -p 3000

Spec file format:

{
  "GET /users": {
    "body": [
      {"id": 1, "name": "Alice"},
      {"id": 2, "name": "Bob"}
    ]
  },
  "POST /users": {
    "status": 201,
    "body": {"id": 3, "message": "Created"}
  },
  "GET /slow": {
    "body": {"status": "ok"},
    "delay": 1000
  },
  "/health": {
    "body": {"status": "healthy"}
  },
  "GET /users/*": {
    "body": {"id": 1, "name": "User"}
  }
}

Route keys:

• "METHOD /path" - match specific HTTP method
• "/path" - match any method
• "/path/*" - wildcard matching

Response options:

• body or response - response body (objects become JSON)
• status - HTTP status code (default: 200)
• headers - custom response headers
• delay - response delay in milliseconds

record

Record all incoming requests to a JSONL file.

httptest record                  # Record to requests.jsonl
httptest record -o webhooks.jsonl

replay

Replay recorded requests against a target server.

httptest replay requests.jsonl -t http://localhost:3000
httptest replay webhooks.jsonl -t https://staging.api.com -d 100

Options:

• -t, --target - Target URL base (required)
• -d, --delay - Delay between requests in ms
• --json - Output results as JSON

fixed

Return a fixed response for all requests.

httptest fixed                   # Returns "ok" with 200
httptest fixed --status 503 --body "maintenance"
httptest fixed --body '{"status":"healthy"}' --content-type application/json

Common Options

All server commands support:

• -p, --port - Port to listen on (default: 8080)
• -H, --host - Host to bind to (default: 0.0.0.0)
• --no-cors - Disable CORS headers
• -q, --quiet - Suppress startup message

Use Cases

Webhook Development

Test webhooks locally by echoing requests:

httptest echo -p 9999 -r webhooks.jsonl
# Configure your service to send webhooks to http://localhost:9999

API Prototyping

Mock an API before it's built:

# api.json
{
  "GET /api/users": {"body": [{"id": 1, "name": "Test"}]},
  "POST /api/users": {"status": 201, "body": {"id": 2}},
  "GET /api/users/*": {"body": {"id": 1, "name": "User"}}
}

httptest mock api.json -p 3001

Frontend Development

Serve your frontend build:

httptest static ./dist -p 8000

Load Testing Prep

Record production traffic, then replay against staging:

# Record
httptest record -p 8080 -o traffic.jsonl

# Replay
httptest replay traffic.jsonl -t http://staging.example.com

For AI Agents

See SKILL.md for agent-optimized documentation.

License

MIT