httptest-cli 0.1.0
Local HTTP test server CLI - echo, static files, mock APIs
License: MIT
Requires Python: >=3.8
Keywords: http, server, testing, mock, api, development, cli

# httptest

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

## Installation

```bash
pip install httptest-cli
```

## Quick Start

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

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

Response format:
```json
{
  "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.

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

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

**Spec file format:**

```json
{
  "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.

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

### replay

Replay recorded requests against a target server.

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

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

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

```bash
# 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:

```bash
httptest static ./dist -p 8000
```

### Load Testing Prep

Record production traffic, then replay against staging:

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

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

## For AI Agents

See [SKILL.md](SKILL.md) for agent-optimized documentation.

## License

MIT