v0.1.1 Python 3.9+ Private Beta

Getting Started

Httrace captures real production HTTP traffic and automatically generates pytest integration tests — without you writing a single line.

Quickstart

You'll have your first auto-generated tests in under 5 minutes.

1Install the package

$ pip install httrace

2Add the middleware to your app

import os
from httrace import HttraceCaptureMiddleware

app.add_middleware(
    HttraceCaptureMiddleware,
    api_key=os.environ["HTTRACE_API_KEY"],
    service="my-api",
    sample_rate=0.1,   # capture 10% of requests
)

3Let real traffic flow in — then generate

$ httrace generate

  ✓ test_post_orders.py    (3 tests)
  ✓ test_get_products.py   (5 tests)
  ✓ test_post_auth_login.py (2 tests)

✓ 10 tests generated across 3 endpoints

Get your API key: Sign up for the waitlist at httrace.com. Beta users receive their key by email within 24 hours.

Installation

Httrace requires Python 3.9 or higher. It's published on PyPI:

$ pip install httrace
# or with uv:
$ uv add httrace

The SDK has minimal dependencies: httpx for async uploads and anyio for background threads. No additional broker or sidecar is required.

Add middleware

The capture middleware is a standard ASGI/WSGI middleware. It intercepts requests after they complete, reads the request and response, sanitizes PII, and queues the payload for upload — all off the critical path.

Middleware options

Parameter	Type	Default	Description
api_key	str	required	Your Httrace API key (`ht_...`). Use an environment variable — never hardcode.
service	str	required	A logical name for the service (e.g. `"orders-api"`). Used to group endpoints in the dashboard.
sample_rate	float	`0.1`	Fraction of requests to capture (0.0–1.0). Start low in production; raise after verifying overhead.
exclude_paths	list[str]	`[]`	Path prefixes to skip (e.g. `["/health", "/metrics"]`).
max_body_bytes	int	`65536`	Maximum request/response body size to capture (bytes). Larger bodies are truncated.
pii_fields	list[str]	built-in list	Additional field names to redact on top of the built-in blocklist.

PII sanitization

The SDK applies two layers of sanitization before any payload leaves your server:

Field-name blocklist — fields named password, token, secret, ssn, cvv, and 40+ others are replaced with "[REDACTED]".
Value-pattern regex — detects credit card numbers, IBANs, JWTs, email addresses, IPv4 addresses, and phone numbers in field values.

You can extend the blocklist via the pii_fields parameter:

app.add_middleware(
    HttraceCaptureMiddleware,
    api_key=...,
    service="my-api",
    pii_fields=["tax_id", "passport_number", "date_of_birth"],
)

Sampling

We recommend sample_rate=0.05 to 0.1 in production. Even 5% of traffic on a busy API generates hundreds of test scenarios per endpoint per day.

Heads up: Setting sample_rate=1.0 on a high-traffic service will significantly increase API usage and may hit your plan's monthly request limit quickly.

Generate tests

After traffic has been captured, run the CLI to generate test files:

$ httrace generate [OPTIONS]

Options:
  --service TEXT      Service name to generate for (default: all)
  --output PATH       Output directory (default: ./tests/)
  --framework TEXT    Test framework: pytest | jest | rspec (default: pytest)
  --min-requests INT  Min captured requests per endpoint to generate a test (default: 3)
  --dry-run           Preview output without writing files

Generated test files follow this structure:

# Generated by Httrace v0.1.1 — 2026-04-18
# Source: 412 captured requests on POST /orders
import pytest
from httpx import AsyncClient
from app.main import app

@pytest.mark.anyio
async def test_post_orders_authenticated():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/orders",
            json={"product_id": "prod_123", "quantity": 2},
            headers={"Authorization": "Bearer [TEST_TOKEN]"},
        )
    assert response.status_code == 201
    assert "order_id" in response.json()

CLI Reference

httrace status

Check how much traffic has been captured for each service:

$ httrace status

Service: my-api
  Captured requests (last 7d): 8,432
  Endpoints tracked: 12
  Tests already generated: 34
  Plan usage: 8,432 / 1,000,000 requests

FastAPI

from fastapi import FastAPI
from httrace import HttraceCaptureMiddleware
import os

app = FastAPI()
app.add_middleware(HttraceCaptureMiddleware,
    api_key=os.environ["HTTRACE_API_KEY"], service="my-api")

Django

Add to MIDDLEWARE in settings.py:

MIDDLEWARE = [
    "httrace.django.HttraceCaptureMiddleware",
    # ... your other middleware
]

HTTRACE = {
    "API_KEY": os.environ["HTTRACE_API_KEY"],
    "SERVICE": "my-api",
    "SAMPLE_RATE": 0.1,
}

Flask

from flask import Flask
from httrace.flask import HttraceFlask

app = Flask(__name__)
HttraceFlask(app, api_key=os.environ["HTTRACE_API_KEY"], service="my-api")

Starlette

from starlette.applications import Starlette
from starlette.middleware import Middleware
from httrace import HttraceCaptureMiddleware

app = Starlette(middleware=[
    Middleware(HttraceCaptureMiddleware,
        api_key=os.environ["HTTRACE_API_KEY"], service="my-api"),
])