proxymock

Record, inspect, mock, replay, and generate API traffic using the proxymock CLI. Use when the user wants to capture HTTP/gRPC/database traffic, create mocks from real traffic or OpenAPI specs, replay traffic for testing, compare traffic snapshots, run mock servers, or manage proxymock RRPair files. Also use for load testing, regression testing, CI pipeline integration, or any task involving proxymock or Speedscale traffic replay.

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

text

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

bash

# 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

bash

# 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

bash

# 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)

bash

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

bash

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

bash

# Compare RRPair files for differences
proxymock files compare --in recorded/ --in replayed/

# Convert between formats
proxymock files convert --in proxymock --out-format json

# Update mock signatures after editing RRPairs
proxymock files update-mocks --in ./my-mocks

Cloud (Enterprise)

bash

proxymock cloud push snapshot    # Push to Speedscale cloud
proxymock cloud pull snapshot    # Pull from cloud

Import Traffic

bash

# Import traffic from a snapshot file
proxymock import snapshot.json
proxymock import --in ./snapshots snapshot.tar.gz

MCP Server

bash

# Start Model Context Protocol (MCP) server for AI tool integration
proxymock mcp

Other

bash

proxymock send-one path/to/test.md http://localhost:8080   # Send single request
proxymock init --api-key <key>                              # Initialize config
proxymock certs                                             # Manage TLS certs
proxymock version                                           # Version info
proxymock completion bash                                   # Generate shell completions (bash/zsh/fish/powershell)

RRPair Files

Traffic is stored as RRPair (request/response pair) markdown files under proxymock/ directory. Each file contains:

• ### REQUEST (TEST) ### or ### REQUEST (MOCK) ### — the captured request
• ### RESPONSE ### — the captured response
• ### SIGNATURE ### — mock matching criteria (for mocks)

Files are human and LLM readable. Edit them directly to modify test data or mock responses, then run proxymock files update-mocks if you changed request details that affect the signature.

Proxy Environment

When not using -- <command> child process mode, set proxy env vars manually:

bash

# HTTP/HTTPS/gRPC
export http_proxy=http://localhost:4140
export https_proxy=http://localhost:4140
export grpc_proxy=http://$(hostname):4140

# Database (SOCKS)
export all_proxy=socks5h://localhost:4140

See language reference for language-specific setup.

Reference

For signature matching, architecture details, and advanced usage: see references/cli-reference.md.