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:
bodyorresponse- response body (objects become JSON)status- HTTP status code (default: 200)headers- custom response headersdelay- 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
Metadata
Release files for httptest-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| httptest_cli-0.1.0.tar.gz | 10.3 kB | Without provenance | Details for httptest_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| httptest_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for httptest_cli-0.1.0-py3-none-any.whl |
Total release size: 20.1 kB
Release files / httptest_cli-0.1.0.tar.gz
| Download URL | httptest_cli-0.1.0.tar.gz |
|---|---|
| Size | 10.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
33f7b8e350824de84100b8262071aaadce23ec767cc4b5b0cdbac660eaa8f63b
|
|
BLAKE2b-256 checksum How to use checksums |
9bca5d76edc24327efdfd6dc5c23d2c4cb0b037bbc69094def12a4619473489e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / httptest_cli-0.1.0-py3-none-any.whl
| Download URL | httptest_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9f9c005abdac1c78aa64b937c9f4d28e714a1adc6ee325e7cdcf445f521b697
|
|
BLAKE2b-256 checksum How to use checksums |
0dc3d669bc8858dfcfacd4f8f764efc60dc5cea5a60e8212447e1bdfc39a0547
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for httptest-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.