Running Keploy on a Go App

Recording real traffic from a Go service and replaying it as tests — on Windows, through WSL.

Why Keploy

Integration tests for a Go service usually mean keeping a database alive, writing mocks by hand, and updating those mocks every time a schema changes. It's a lot of upkeep for tests that mostly verify things you already know work.

Keploy takes a different approach: it records real traffic once and replays it forever.

When you start a recording, Keploy moves your app to another port and takes the original one for itself, so every request passes through it. At the same time, it attaches an eBPF probe at the kernel level to watch the syscalls your app makes to the database.

your curl  →  Keploy (port 8082)  →  app (port 35555)  →  Postgres
                    ↑                                        ↑
              records request                      eBPF records this
              and response                         query and its result

So one recording run captures two things: the HTTP exchange becomes a test case, and the database exchange becomes a mock.

On the test run, the app starts again — but this time Keploy answers the database calls from those mocks. Postgres never gets touched. No live database, no hand-written mocks, no drift when the schema changes.

Because the probe sits at the kernel level rather than inside your code, you don't import a library or change a line of your app. That's also why Keploy needs sudo, and why it only runs on Linux — hence WSL on Windows.

Prerequisites

For Windows users, Keploy runs three ways: natively, through WSL, or in Docker. This tutorial uses WSL.

You'll need WSL2 with Ubuntu, Docker Desktop, and Go.

This tutorial was written against 3.8.2.

Step 1 — Install Keploy

If WSL isn't enabled yet, run this in PowerShell as Administrator:

wsl --install -d Ubuntu-22.04

Then open your WSL terminal and move to your Linux home directory:

cd ~

Install the CLI:

curl --silent -O -L https://keploy.io/install.sh && source install.sh

It will ask for your password. Nothing appears as you type — that's normal.

Verify:

keploy --version

If yours isn't 3.8.2, some flags below may have changed.

Step 2 — Log in

sudo keploy login

Without sudo, it fails on a log file it can't write — and the message gives no hint that sudo is the fix:

Failed to start the logger for the CLI failed to set the log file permission to 777: chmod keploy-logs.txt: operation not permitted

The browser won't open inside WSL. Keploy prints a URL instead:

Opening browser for authentication...

If the browser does not open automatically, please visit:
https://app.keploy.io/signin/integration/auth?method=code&code=...

Paste it into a Windows browser and it works — but you have sixty seconds. Miss that window and you get:

authentication timed out after 1 minute; last polling error:
unexpected status 401: {"error":"invalid or expired code"}

The timeout message points you at manual login, which skips the browser entirely. Go to Account → API Keys in the dashboard, generate a token, and paste it when the CLI prompts you. Keploy's installation docs cover this flow in full.

One difference: they show the command as keploy login --manual-login, but on WSL it needs sudo for the same log-file reason as above.

sudo keploy login --manual-login

Step 3 — Get the sample app

git clone https://github.com/keploy/samples-go.git && cd samples-go/echo-sql
go mod download

go mod download fetches the libraries this project needs, as listed in go.mod.

Step 4 — Start Postgres

Keploy offers two routes here: run everything in Docker, or run the database in Docker and the app natively. This tutorial takes the second route — the app runs directly on WSL, and only Postgres is containerised.

Worth knowing up front, because the two paths differ in several places and mixing them produces confusing failures. The next step is the first of those differences.

docker-compose up -d postgres

The project ships a docker-compose.yml that defines both the app and the database. Naming postgres at the end starts just that one service, and -d runs it in the background so you get your terminal back.

Confirm it's running:

docker ps

That lists every running container. You should see one for Postgres, with port 5432 mapped. If nothing appears, the database didn't start and the next steps will fail.

Step 5 — Point the app at localhost

This is the first place the two routes diverge.

The sample ships configured for Docker, where the app and database share a Docker network and the app finds Postgres by name. On the native route the app runs outside Docker, so that name means nothing to it — it has to reach Postgres through the published port on localhost.

Open main.go and find the Postgres host configuration:.

grep -n "postgresDb" main.go

cat -n main.go | head -50

Edit it with nano main.go, then confirm the change:

git diff main.go

Step 6 — Build the binary

go build -cover

This compiles main.go, handler.go, and every library they import into a single executable.

Step 7 — Record

sudo PATH="$PATH" keploy record -c "./echo-psql-url-shortener"

Keploy starts your app, takes over port 8082, and moves the app to another port. From here on, every request you make passes through Keploy on its way in, while the eBPF probe watches the app's database calls on the way out.

keploy --version          # works
sudo keploy --version     # command not found

echo $PATH
sudo printenv PATH
which keploy

Make some API calls

With recording running, open a second terminal and hit the API. This tutorial uses curl; Postman or Hoppscotch work just as well.

curl --request POST \
  --url http://localhost:8082/url \
  --header 'content-type: application/json' \
  --data '{"url": "https://github.com"}'

You'll get back a shortened URL:

{"ts":1788079291093424896,"url":"http://localhost:8082/4KepjkTT"}

Paste that into a browser and it redirects to the original — a second request, captured as a second test case.

Stop recording with Ctrl+C, then look at what Keploy wrote:

ls -R keploy/

keploy/test-set-1:
mocks.yaml  tests

keploy/test-set-1/tests:
get-4kepjktt-1.yaml  post-url-1.yaml

Each API call became a test case — the request you sent and the response you got. The Postgres exchanges behind them went into mocks.yaml. That pairing is the whole idea: the test cases are what gets replayed, and the mocks are what answers the database calls when it does.

Step 8 — Run the tests

sudo PATH="$PATH" keploy test -c "./echo-psql-url-shortener" --delay 10 --test-sets test-set-1

--delay 10 gives the app ten seconds to start before Keploy begins replaying.

Step 9 — Read the output

 <=========================================>
  COMPLETE TESTRUN SUMMARY.
        Total tests: 2
        Total test passed: 2
        Total test failed: 0
        Total time taken: "10.09 s"
 <=========================================>

Both requests replayed and matched. The line worth noticing is further up:

IT metrics successfully sent  {"testsRan": 2, "mocksConsumed": 4}

Four mocks consumed. The app pinged the database, created its table, and ran both queries — and Postgres answered none of it. Every one of those calls was served from the recording. That's the entire value proposition visible in a single line: no live database, no hand-written mocks, and the app never knew the difference.

ERROR  failed to read the test-set report {"reportName": "test-set-0-report", ...}

Where this fits

For me, Keploy is most useful when you already have a working service and want regression coverage without maintaining a large set of database mocks by hand. The recorded traffic gives you a practical starting point, but it doesn't replace deliberately testing paths you haven't exercised — if you never send a request through a particular part of the application, Keploy can't record a test for it.