proxymock

proxymock captures real API and database traffic via a transparent proxy, then uses it to create mocks and tests — no code changes required.

Core Workflow

record → inspect → mock / replay

1. Record traffic with proxymock record -- <app-command>
2. Inspect captured RRPairs with proxymock inspect
3. Mock dependencies with proxymock mock -- <app-command>
4. Replay recorded tests with proxymock replay --test-against <url>

Key Commands

Record Traffic

# Record while running app as child process (recommended)
proxymock record -- go run .
proxymock record -- npm start

# Custom output dir
proxymock record --out my-recording -- python app.py

# Record database traffic via reverse proxy
proxymock record --map 65432=postgres://localhost:5432 -- ./my-app

# Record with custom app port
proxymock record --app-port 3000 -- ./my-app

Architecture: inbound proxy on :4143 → app on --app-port (default 8080), outbound proxy on :4140 captures egress.

Mock Server

# Start mock server, launch app as child
proxymock mock -- go run .

# Source mocks from specific dir
proxymock mock --in ./my-recordings -- npm start

# Fast mode (no simulated latency)
proxymock mock --fast -- ./my-app

# Don't write observed traffic to disk
proxymock mock --no-out -- ./my-app

# Database mock via reverse proxy
proxymock mock --map 65432=localhost:5432 -- ./my-app

When mocking, app connects to external services through proxy on :4140. Matched requests return recorded responses; unmatched requests pass through to real backends.

Replay / Load Test

# Replay recorded tests against app
proxymock replay --test-against http://localhost:8080

# Load test: 10 virtual users for 5 minutes
proxymock replay --test-against http://localhost:8080 --vus 10 --for 5m

# Run tests 3 times
proxymock replay --test-against http://localhost:8080 --times 3

# Fail on conditions (CI-friendly)
proxymock replay --test-against http://localhost:8080 \
  --fail-if "requests.failed!=0" \
  --fail-if "latency.p99>100"

# Multi-service routing
proxymock replay \
  --test-against auth=auth.example.com \
  --test-against frontend=http://localhost:8080 \
  --test-against http://localhost:9000

Validation metrics: latency.{avg,p50,p90,p95,p99,max,min}, requests.{total,succeeded,failed,per-second,per-minute,response-pct,result-match-pct}.

Inspect (TUI)

proxymock inspect                    # Current directory
proxymock inspect --in ./my-recording
proxymock inspect --demo             # Demo data

Note: inspect launches a terminal UI — run with pty=true in exec.

Generate Mocks from OpenAPI

proxymock generate api-spec.yaml
proxymock generate --out ./mocks --host api.staging.com api-spec.yaml
proxymock generate --tag-filter "users,orders" api-spec.yaml
proxymock generate --include-optional --examples-only api-spec.yaml

File Utilities