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.

# Python
$ pip install httrace

# Node.js / TypeScript
$ npm install httrace

# Go
$ go get github.com/httrace-io/httrace-go

# Ruby
$ gem install httrace

# Python (FastAPI shown — see Frameworks section for Django, Flask, Express, Go, Rails)
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
)

$ 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

Installation

All SDKs are open-source (MIT) and require no broker, sidecar, or infrastructure changes.

Python (3.9+)

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

Minimal dependencies: httpx for async uploads, anyio for background threads. Supports FastAPI, Django, Flask, and Starlette.

Node.js / TypeScript

$ npm install httrace
# or:
$ yarn add httrace

Supports Express and any Node.js HTTP framework. Uses AsyncLocalStorage for per-request isolation.

Go (1.18+)

$ go get github.com/httrace-io/httrace-go

Works with net/http, Gin, Echo, and chi. Uses idiomatic context.Context propagation — no global state.

Ruby (2.7+)

$ gem install httrace
# or add to Gemfile:
gem 'httrace'

Works with Rails, Rack, and Sinatra. Uses Thread.current for per-request isolation — safe under Puma and other threaded servers.

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

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.

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)
  --format TEXT       pytest | jest | vitest | go | rspec  (default: pytest)
  --output PATH       Output directory (default: ./tests/integration)
  --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. Httrace automatically detects which endpoints require authentication and wires the auth_headers fixture accordingly — no manual token setup needed:

# Generated by Httrace — 8 interactions captured
# Service: my-api
# DO NOT EDIT — re-run `httrace generate` to update
import pytest
import httpx

@pytest.fixture
def payload_post_orders_201():
    return {"product_id": "prod_123", "quantity": 2}

def test_post_orders_201(client, auth_headers, payload_post_orders_201):
    response = client.post(
        "/orders",
        json=payload_post_orders_201,
        headers=auth_headers,  # ← injected from conftest.py
    )
    assert response.status_code == 201
    assert "order_id" in response.json()

The auth_headers fixture lives in the auto-generated conftest.py. See Auth fixture detection for details.

CLI Reference

httrace generate

Generate test files from captured traffic. Supports 5 output formats:

$ httrace generate [OPTIONS]

Options:
  --format    pytest | jest | vitest | go | rspec  (default: pytest)
  --output    Output directory  (default: ./tests/integration)
  --dry-run   Preview output without writing files

Examples:

# Generate pytest tests (default)
$ httrace generate

# Generate Jest tests
$ httrace generate --format jest --output tests/

# Generate Go tests
$ httrace generate --format go --output ./integration_tests/

# Preview without writing
$ httrace generate --format rspec --dry-run

httrace status

Check how much traffic has been captured and which endpoints have coverage:

$ 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

httrace diff

Detect API schema drift since the last time tests were generated. Use --fail-on-breaking in CI pipelines to block deployments when breaking changes are detected:

$ httrace diff [OPTIONS]

Options:
  --service          Service name (overrides config)
  --fail-on-breaking Exit code 1 if breaking changes detected
  --output           table | json  (default: table)

Example output:

$ httrace diff --service my-api

╭─────────────────────────────────────────────────────╮
│  API Drift — my-api                                 │
├──────────────────┬─────────────────┬───────────────┤
│ Endpoint         │ Change type     │ Detail        │
├──────────────────┼─────────────────┼───────────────┤
│ POST /orders     │ schema          │ +coupon_code  │
│ GET /products    │ new endpoint    │ No tests yet  │
╰──────────────────┴─────────────────┴──���────────────╯

2 changes detected

Use in CI with --fail-on-breaking to fail the pipeline on breaking schema changes:

$ httrace diff --fail-on-breaking
# Exits 0 if no changes, 1 if breaking changes or new untested endpoints

httrace replay

Replay captured traffic against a target URL and compare responses. Useful for validating staging environments or checking for regressions before deployment.

$ httrace replay [OPTIONS]

Options:
  --target   -t  Target base URL to replay against (required)
  --service  -s  Service name (overrides config)
  --limit    -n  Number of recent captures to replay (default: 50, max: 200)
  --timeout      Per-request timeout in seconds (default: 10.0)
  --fail-on-diff Exit code 1 if any differences detected
  --output   -o  table | json  (default: table)

Example:

$ httrace replay --target https://staging.myapp.com --service my-api

Replaying 50 captures against https://staging.myapp.com …

╭──────────────────┬──────────┬─────────────────────────────╮
│ Endpoint         │ Status   │ Notes                       │
├──────────────────┼──────────┼─────────────────────────────┤
│ GET /api/users   │ ✓ match │                             │
│ POST /orders     │ ✓ match │                             │
│ DELETE /items/42 │ ✗ diff  │ 200 → 404 (status mismatch) │
╰──────────────────┴──────────┴─────────────────────────────╯

49/50 passed  (1 difference, 3420ms total)

In CI, combine --fail-on-diff with the GitHub Actions workflow to block deployments when staging diverges from production behaviour:

$ httrace replay --target $STAGING_URL --fail-on-diff
# Exits 1 if any status code or response schema differs from production captures

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"),
])

Express (Node.js)

Works with Express 4/5 and any Node.js HTTP framework. Install via npm:

$ npm install httrace

const express = require('express');
const httrace = require('httrace');

const app = express();

app.use(httrace({
  apiKey:  process.env.HTTRACE_API_KEY,
  service: 'my-api',
  sampleRate: 0.1,
}));

To capture outgoing HTTP calls (for dependency mock generation):

app.use(httrace({
  apiKey:          process.env.HTTRACE_API_KEY,
  service:         'my-api',
  captureOutgoing: true,   // patches http.request / https.request
}));

Go (net/http · Gin · Echo)

Install the Go module:

$ go get github.com/httrace-io/httrace-go

net/http

import "github.com/httrace-io/httrace-go/httrace"

cfg := httrace.Config{
    APIKey:  os.Getenv("HTTRACE_API_KEY"),
    Service: "my-api",
    SampleRate: 0.1,
}

http.ListenAndServe(":8080", httrace.Middleware(cfg)(mux))

Gin

r := gin.Default()
r.Use(httrace.GinMiddleware(cfg))
r.Run(":8080")

For outgoing HTTP capture, retrieve the recording *http.Client from context:

client := httrace.ClientFromContext(r.Context())
resp, err := client.Get("https://api.stripe.com/...")

Rails / Rack (Ruby)

Install via Bundler:

gem 'httrace'  # Gemfile

Rails

Add to config/application.rb:

require 'httrace'

config.middleware.use Httrace::CaptureMiddleware,
  api_key:     ENV['HTTRACE_API_KEY'],
  service:     'my-api',
  sample_rate: 0.1

To capture ActiveRecord SQL queries alongside requests:

config.middleware.use Httrace::CaptureMiddleware,
  api_key:         ENV['HTTRACE_API_KEY'],
  service:         'my-api',
  capture_outgoing: true,
  capture_db:       true   # Rails only — instruments ActiveRecord

Sinatra / plain Rack

require 'httrace'

use Httrace::CaptureMiddleware,
  api_key: ENV['HTTRACE_API_KEY'],
  service: 'my-api'

Test Formats

Httrace can generate tests in 5 different frameworks. All formats are generated from the same captured traffic — just pick the one that matches your stack.

Example — Jest output for GET /api/users:

// Generated by Httrace — 12 interactions captured
// DO NOT EDIT — re-run `httrace generate` to update
const axios = require('axios');
const BASE_URL = process.env.BASE_URL || 'http://localhost:8000';

describe('GET /api/users', () => {
  test('GET /api/users returns 200', async () => {
    const response = await axios({ method: 'get', url: `${BASE_URL}/api/users`, validateStatus: () => true });
    expect(response.status).toBe(200);
    expect(response.data.total).toBe(1);
    expect(Array.isArray(response.data.users)).toBe(true);
  });
});

Auth Fixture Detection

When you generate tests for a service that has authenticated endpoints, Httrace automatically detects the login flow from your captured traffic and generates a working auth_headers fixture — no manual token setup required.

How it works

Httrace scans all captures for the service and looks for a POST (or PUT) request that:

• returns HTTP 200 or 201
• has a response body containing a token field (access_token, token, jwt, auth_token, etc.)
• does not itself require an Authorization header (i.e. it is the login endpoint, not an authenticated one)

Paths containing /login, /auth, /token, or /signin are ranked higher so the correct endpoint wins when multiple candidates exist.

Generated conftest.py

The conftest.py generated alongside your test files will contain a ready-to-run auth_headers fixture:

import os
import pytest
import httpx

BASE_URL = os.environ.get("TEST_BASE_URL", "http://localhost:8000")

@pytest.fixture(scope="session")
def client():
    with httpx.Client(base_url=BASE_URL, timeout=10.0) as c:
        yield c

# ← Httrace detected POST /auth/login as the login endpoint
@pytest.fixture(scope="session")
def auth_headers(client):
    response = client.post(
        "/auth/login",
        json={
            "email": os.environ.get("EMAIL_TEST", ""),    # set EMAIL_TEST
            "password": os.environ.get("PASSWORD_TEST", ""),  # set PASSWORD_TEST
        },
    )
    assert response.status_code in (200, 201)
    token = response.json()["access_token"]
    return {"Authorization": f"Bearer {token}"}

Tests for endpoints that had an Authorization header in the original capture automatically receive auth_headers as a fixture argument:

# test_get_profile.py — auth injected automatically
def test_get_profile_200(client, auth_headers):
    response = client.get("/profile", headers=auth_headers)
    assert response.status_code == 200

Configuring credentials

Credentials are read from environment variables so they work in CI without hardcoding. Set them before running your tests:

# .env.test (never commit this)
EMAIL_TEST=testuser@example.com
PASSWORD_TEST=supersecret

# Or pass them inline
$ EMAIL_TEST=testuser@example.com PASSWORD_TEST=supersecret pytest tests/

When no auth flow is detected

If Httrace cannot find a login endpoint in your captures (e.g. your service uses API keys instead of JWTs, or you haven't captured a login request yet), the fixture falls back to a stub with instructions:

@pytest.fixture(scope="session")
def auth_headers(client):
    # TODO: implement login and return auth headers
    # response = client.post("/auth/login", json={...})
    # return {"Authorization": f"Bearer {response.json()['access_token']}"}
    return {}

Once you've captured at least one successful login request, re-run httrace generate and the fixture will be auto-populated.

Dependency Mocking

When capture_outgoing=True is enabled on the middleware, Httrace intercepts every outgoing HTTP call and SQL query made during a request and stores them alongside the captured interaction. The test generator then produces mock fixtures automatically — so generated tests require no live database, no external APIs, and no Docker containers to run.

This is Httrace's most powerful feature for CI: generated tests become fully self-contained.

Python (FastAPI / Flask)

from httrace import HttraceCaptureMiddleware

app.add_middleware(
    HttraceCaptureMiddleware,
    api_key="ht_...",
    capture_outgoing=True,     # intercept httpx + requests
    db_engines=[engine],         # optional: SQLAlchemy engines
)

The interceptor patches httpx.AsyncClient, httpx.Client, and requests.Session globally once — with zero overhead when no request is being tracked. SQLAlchemy engines are instrumented via event.listen hooks; SQL parameter values are always redacted to ?.

Node.js (Express)

const httrace = require('httrace');
app.use(httrace({ apiKey: 'ht_...', captureOutgoing: true }));

Uses AsyncLocalStorage for per-request isolation. Patches http.request and https.request — compatible with axios, node-fetch, and the native fetch API.

Go

cfg := httrace.Config{APIKey: "ht_...", CaptureOutgoing: true}

// In your handlers, use the recording client:
client := httrace.ClientFromContext(r.Context())
resp, err := client.Get("https://api.stripe.com/...")

Go uses idiomatic context.Context propagation. Pass the recording client to any code that makes outgoing calls.

Ruby (Rack / Rails)

use Httrace::CaptureMiddleware,
    api_key: 'ht_...',
    capture_outgoing: true

Prepends NetHTTPInterceptor into Net::HTTP once at startup. Uses Thread.current for per-request isolation — safe under Puma and other threaded servers.

Generated mock fixtures

When a captured interaction contains outgoing calls, the generator automatically adds mock fixtures to the test file. No configuration needed.

pytest — uses pytest-respx for HTTP and pytest-mock for SQL:

# pip install pytest-respx pytest-mock

@pytest.fixture
def mock_outgoing_http(respx_mock):
    respx_mock.get("https://api.stripe.com/v1/charges/ch_123").mock(
        return_value=httpx.Response(200, json={"id": "ch_123", "amount": 2000}),
    )
    yield respx_mock

@pytest.fixture
def mock_db_queries(mocker):
    mock_conn = mocker.MagicMock()
    mock_conn.execute.return_value.fetchall.return_value = [{"id": "ord_1"}]
    # mocker.patch("app.database.get_db", return_value=mock_conn)
    yield mock_conn

def test_post_orders_201(client, mock_outgoing_http, mock_db_queries, payload):
    response = client.post("/orders", json=payload)
    assert response.status_code == 201

Jest — uses nock:

// npm install --save-dev nock
const nock = require('nock');
nock('https://api.stripe.com').get('/v1/charges/ch_123').reply(200, {"id": "ch_123"});

Vitest — uses MSW (Mock Service Worker):

// npm install --save-dev msw
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
const server = setupServer(
  http.get('https://api.stripe.com/v1/charges/ch_123', () =>
    HttpResponse.json({ id: 'ch_123', amount: 2000 })
  )
);

Go — uses jarcoal/httpmock:

httpmock.Activate()
defer httpmock.DeactivateAndReset()
httpmock.RegisterResponder("GET", "https://api.stripe.com/v1/charges/ch_123",
    httpmock.NewStringResponder(200, `{"id":"ch_123","amount":2000}`))

RSpec — uses WebMock:

stub_request(:get, "https://api.stripe.com/v1/charges/ch_123")
  .to_return(status: 200, body: '{"id":"ch_123"}',
             headers: { 'Content-Type' => 'application/json' })

What gets captured

GitHub Actions Integration

Httrace integrates with GitHub Actions to automatically check for API schema drift on every push or pull request. The httrace diff command exits with code 1 if breaking changes are detected, which fails the CI pipeline.

Download a ready-to-use workflow file from your dashboard, or generate it via the API:

$ curl "https://api.httrace.com/v1/github-actions?service=my-api" \
  -H "x-api-key: ht_..." \
  -o .github/workflows/httrace.yml

The generated workflow file:

name: Httrace API Drift Check

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  httrace-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install httrace
      - run: httrace diff --service my-api --fail-on-breaking
        env:
          HTTRACE_API_KEY: ${{ secrets.HTTRACE_API_KEY }}

OpenAPI Export

Httrace can infer an OpenAPI 3.0 specification from your captured traffic. The schema is built from real request/response shapes — not from decorators or annotations.

# Download as YAML
$ curl "https://api.httrace.com/v1/openapi.yaml?service=my-api" \
  -H "x-api-key: ht_..." -o openapi.yaml

# Or JSON
$ curl "https://api.httrace.com/v1/openapi.json?service=my-api" \
  -H "x-api-key: ht_..." -o openapi.json

The spec includes:

• All observed paths and HTTP methods
• Request body schemas inferred from real payloads
• Response schemas per status code
• Path parameters (auto-detected from numeric URL segments)
• Security scheme hints (Bearer token detected from headers)

Coverage & Changes API

These endpoints power the Coverage and API Drift sections in the dashboard, and are also usable directly.

GET /v1/coverage

Returns all observed endpoints and capture counts for a service.

$ curl "https://api.httrace.com/v1/coverage?service=my-api" \
  -H "x-api-key: ht_..."

{
  "service": "my-api",
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/users",
      "captures": 412,
      "statuses": [200, 401]
    }
  ],
  "total_captures": 8432
}

GET /v1/changes

Returns schema changes since the last time tests were generated. Useful for detecting breaking changes before deployment.

$ curl "https://api.httrace.com/v1/changes?service=my-api" \
  -H "x-api-key: ht_..."

{
  "changes": [
    {
      "endpoint": "POST /orders",
      "changes": [
        { "type": "schema", "detail": "new field: coupon_code" }
      ]
    }
  ],
  "untested_endpoints": ["GET /products"]
}

Anomaly Alerts

Httrace can notify you via Slack or email when unusual patterns are detected in your captured traffic — spikes in error rates, latency outliers, or newly observed endpoints.

Alert triggers

Configure via the dashboard

Go to your dashboard → Alerts tab → click + New alert. Select the service, trigger, channel (Slack or email), and destination.

Configure via the API

# Create a Slack alert for error spikes on my-api
$ curl -X POST "https://api.httrace.com/v1/alerts" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "service":     "my-api",
    "alert_on":    "error_spike",
    "threshold":   10,
    "channel":     "slack",
    "destination": "https://hooks.slack.com/services/T.../B.../..."
  }'

# Create an email alert for new endpoints
$ curl -X POST "https://api.httrace.com/v1/alerts" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "service":     "my-api",
    "alert_on":    "new_endpoint",
    "channel":     "email",
    "destination": "team@mycompany.com"
  }'

Alert endpoints

Replay Testing

Replay testing re-sends your captured production requests to any target URL — staging, a feature branch, a refactored service — and compares the responses to what production returned. It's a zero-effort regression suite derived from real traffic.

How it works

1. Httrace loads the N most recent captures for your service
2. Each captured request is replayed concurrently against the target URL
3. Status codes and response body structure are compared
4. Differences are reported endpoint-by-endpoint

Via the CLI

See httrace replay above for the full CLI reference.

Via the API

$ curl -X POST \
  "https://api.httrace.com/v1/replay?service=my-api&target_base_url=https://staging.myapp.com&limit=50" \
  -H "x-api-key: ht_..."

{
  "total":       50,
  "passed":      49,
  "failed":       1,
  "duration_ms": 3420,
  "differences": [
    {
      "method":          "DELETE",
      "path":            "/items/42",
      "original_status": 200,
      "replay_status":   404,
      "status_match":    false,
      "body_diff":       "missing key: item_id"
    }
  ]
}

Teams & Organizations

Organizations let multiple engineers share a set of API keys, services, and dashboard access under one account. Useful for teams where several people need to view coverage or manage alerts.

Create an organization

In your dashboard → Team tab → click + New organization, or via the API:

$ curl -X POST "https://api.httrace.com/v1/orgs" \
  -H "Authorization: Bearer <JWT>" \
  -d '{"name": "Acme Corp"}'

Invite members

$ curl -X POST "https://api.httrace.com/v1/orgs/acme-corp/invite" \
  -H "Authorization: Bearer <JWT>" \
  -d '{"email": "colleague@acme.com", "role": "member"}'

The invited user receives an email with a link to accept the invitation. Accepted members can view the org's dashboard, coverage, and alerts.

Roles

Org API keys

Org-level API keys can be created for CI/CD pipelines so that no individual's personal key needs to be shared:

$ curl -X POST "https://api.httrace.com/v1/orgs/acme-corp/api-keys" \
  -H "Authorization: Bearer <JWT>" \
  -d '{"name": "Production CI"}'

Organization endpoints

VS Code Extension

The Httrace VS Code extension brings coverage data and test generation directly into your editor — without switching to the dashboard or running CLI commands.

Installation

Download the httrace-vscode-0.2.0.vsix and install it manually, or use the command line:

$ code --install-extension httrace-vscode-0.2.0.vsix

Alternatively, once published to the marketplace:

$ code --install-extension httrace.httrace-vscode

Configuration

Open VS Code settings (⌘,) and search for httrace:

Commands

Access all commands via the Command Palette (⌘⇧P) → type Httrace:

Inline decorations

When httrace.showInlineDecorations is enabled, the extension scans route definition lines in the active file and annotates them with capture counts from the last refresh:

# FastAPI — annotations appear after the decorator
@app.get("/api/users")      ✓ 412 captures · tested
@app.post("/api/orders")    ✓ 38 captures
@app.delete("/api/items/{id}")   ○ no captures

Supported file types: Python (FastAPI / Flask), JavaScript/TypeScript (Express), Go (chi/mux), Ruby (Rails routes).

Coverage tree view

The Httrace activity bar panel shows all tracked endpoints grouped by HTTP method, with capture counts and test status. Click the beaker icon (🧪) in the activity bar to open it.

Status bar

The status bar item in the bottom-right shows the current endpoint + capture count and refreshes on the configured poll interval. Click it to open the Coverage QuickPick.