Demo apps for the proxymock quickstart — the same small app in seven languages. Each one calls a CNCF projects API as its downstream; proxymock records that call, then mocks it so the app runs and tests with no network.

One click — all seven runtimes and the proxymock CLI are preinstalled. Run proxymock init --api-key <key> once to activate it (free key at app.speedscale.com/signup).

Every app listens on :8080 (override PORT) and calls the downstream at DOWNSTREAM_URL (default https://demo-api.trafficreplay.com).

¹ requires Authorization: Bearer <access_token>.

First time on a machine, install proxymock and activate it once — proxymock init --api-key <key> (free key at app.speedscale.com/signup). In a Codespace the CLI is already installed, so you only need the init.

cd go                                          # pick any language dir (node/, python/, ...)
proxymock record -- go run .                   # 1. record the app calling the downstream
./lab/tests/run_tests.sh --recording           # 2. new terminal (repo root): drive every endpoint
proxymock web                                   # 3. browse the recorded traffic in your browser (:7788)
proxymock mock -- go run .                      # 4. mock the downstream — no network needed
proxymock replay --test-against http://localhost:8080   # 5. replay it back at the app

One script drives the whole demo — the 5 read endpoints plus the OAuth + order flow — pausing ~1s between calls so you can watch each one land in proxymock web (set DELAY=0 to skip the pause). Step 5 can also be run from the proxymock web UI instead of the proxymock replay command.

Go, Python, Ruby, Java, .NET, and C++ all work with proxymock record out of the box — proxymock injects the proxy and TLS settings each runtime understands (for Java, via JAVA_TOOL_OPTIONS). Node is the exception: its fetch ignores proxy env vars until Node 24 (backported to 22.21), so set NODE_USE_ENV_PROXY=1 and NODE_EXTRA_CA_CERTS first — see node/README.md.

Each app also exposes a small OAuth-style flow, built to show how proxymock handles values that change between record and replay. POST /oauth/token returns a fresh access_token; POST /api/orders (Bearer-protected, validates the project against the downstream) returns a fresh order_id; GET /api/orders/{order_id} (Bearer-protected) reads it back. Those two IDs are regenerated on every call, so on replay the recorded token/order_id are stale and the protected calls would 401/404 — until smart replace chains them.

A committed recording and smart-replace blueprint ship in lab/proxymock/, so you can mock + replay the whole demo (basic + auth endpoints) offline against any language, with no recording step:

cd go                                                          # any language dir
proxymock mock --in ../lab/proxymock/recording -- go run .     # downstream served from the recording
# in another terminal:
proxymock replay --in ../lab/proxymock/recording --test-against http://localhost:8080

Replay passes 0% failed — the blueprint (res_body → json_path → smart_replace_recorded on access_token and order_id) re-chains both IDs. To record your own and watch it happen, use the quickstart above (./lab/tests/run_tests.sh --recording drives the auth flow too).

Traffic replay is useful because it keeps the story honest: the app succeeds or fails against requests it already saw. In this lab, the story starts with the Go demo app calling the CNCF API and running the auth/order flow. proxymock records that traffic as RRPairs. Then the mock set gets stale — several downstream recordings are missing — and replay exposes the gap as MISS results. Tuning means restoring or adjusting the mock set until the same replay passes cleanly.

Use skills/proxymock-replay-tuning/ when a local HTTP/HTTPS mock has replay misses and you need a repeatable match-rate report:

./skills/proxymock-replay-tuning/scripts/tune-proxymock-replay.sh \
  --mock-in <candidate-mock-dir> \
  --replay-in <replay-dir>

To run the workflow from a fresh checkout:

git clone https://github.com/speedscale/mock-lab.git
cd mock-lab
mkdir -p replay-work

Take a local recording. This example uses the Go app, but the same pattern works from any language directory in this repo:

cd go
proxymock record --out ../replay-work/recording -- go run .

In another terminal from the repo root, drive the demo traffic:

./lab/tests/run_tests.sh --recording

Then start your AI agent from the repo root and ask it to use the tuning skill:

Use the proxymock-replay-tuning skill to tune this replay.
Mock input: lab/proxymock/recording
Replay input: replay-work/recording
Run the tuning script, summarize HIT/MISS/PASSTHROUGH, and recommend what transforms or recordings need to change.

Use Mock input for the mock or recording you want to tune. The agent should run the tuning script, read summary.json, inspect misses in mock-output/, and recommend concrete changes to recordings, signatures, filters, or transforms. Rerun the same skill after each tuning change until the match rate is acceptable.

To verify the tuning workflow itself, run:

./skills/proxymock-replay-tuning/scripts/prove-proxymock-replay-tuning.sh

The proof tells the whole replay story: record real app traffic, create a stale mock baseline, measure the misses, replay against the tuned mock set, and verify the hit rate improves.

The same recordings power three more agent skills in skills/. Each ships a script and a prove-*.sh, runs against the committed lab/proxymock/recording, and needs no Speedscale Cloud account.

# quick load test against the mocked app (run `cd go && proxymock mock --in ../lab/proxymock/recording -- go run .` first)
./skills/proxymock-load-test/scripts/proxymock-load-test.sh \
  --in lab/proxymock/recording/localhost --test-against http://localhost:8080 --vus 8 --for 20s

# deep comparison of two replay outputs
./skills/proxymock-compare-results/scripts/proxymock-compare-results.sh \
  --in ./after --baseline ./before --drift --fail-on-regression

# summarize what a recording contains
./skills/proxymock-summarize-recording/scripts/proxymock-summarize-recording.sh \
  --in lab/proxymock/recording --out recording-brief.md

The apps query a hosted CNCF projects API (default demo-api.trafficreplay.com). You don't run or manage it — its contract is in lab/openapi.yaml.

Everything the lab needs for itself (the mock backend, the traffic driver, and the API spec) lives in lab/. You can ignore it for the quickstart.