Simplifying REST API Testing with GoReplay

If you maintain REST APIs, the expensive bugs are the ones your Postman collection never sent. GoReplay captures live HTTP from production and replays it in staging so tests follow real clients, not the happy path you scripted. That is API testing by traffic replay, not by writing another synthetic case.

# Capture production HTTP
sudo gor --input-raw :8080 --output-file=api.gor
# Replay against staging
gor --input-file api.gor --output-http="http://staging.example.com"
# Shadow a canary in real time
sudo gor --input-raw :8080 --output-http="http://canary.example.com"

What this is (and is not)

• Is: record/replay of HTTP for shadow testing and load testing with production traffic.
• Is not: a Postman GUI, REST-assured runner, or contract-test framework. Keep those for schema and auth unit checks. Add Gor for the mix you actually serve.
• Is not: Wireshark. You want messages you can replay, not packets to stare at.

Filter to the API you care about (--http-allow-url "^/api/"), rewrite hosts, and run middleware to map prod tokens onto staging users (see examples/middleware/token_modifier.go in the GitHub repo). Mask bodies before anything is stored.

Install

wget https://github.com/buger/goreplay/releases/latest/download/gor_latest_x64.tar.gz
tar -xzf gor_latest_x64.tar.gz
sudo mv gor /usr/local/bin/
gor --version

Root/sudo is required for pcap on a privileged port. Capture behind the TLS terminator so you see HTTP. Local guide: installation. Full GitBook: https://docs.goreplay.org/untitled.

Before you capture

1. Permissions: sudo or CAP_NET_RAW.
2. Disk: peak RPS × average size × retention. PRO can spill to S3.
3. Port: the app port, not the public 443 if TLS is terminated at the LB.
4. Parity: staging schema and feature flags close enough that replayed POSTs mean something.
5. Safety: drop or rewrite Authorization, cookies, and PII in middleware before --output-file or --output-http.

Replay patterns for APIs

• Regression: replay a morning capture after every deploy; diff status codes (middleware or access logs).
• Load: --input-file "api.gor|200%" — same paths, higher rate.
• Contract drift: when staging returns 404 on a path that production still hits, you found a missing route without writing that test.
• Session-sensitive APIs: PRO keeps TCP/TLS sessions together so connection limits and sticky LB behavior show up. See accurate sessions.

Speed control, --output-http-workers, and --split-output are documented in the basics and middleware.

Related video

GoReplay OSS is LGPL; PRO is $3000/year for S3, WebSockets, TCP sessions, and a commercial license. Start with the binary, capture one endpoint, replay it once — then widen the filter.