Go quickstart: run go test without PostgreSQL or an HTTP API
In this quickstart, you build a small Go package whose tests read PostgreSQL
and call an exchange-rates API. You record those calls once, with both
dependencies up. Then you run the same go test with both of them switched
off, and the tests still pass.
You don't write any mock code, and the tests don't change.
Every output on this page comes from a real run of Keploy 3.9.3 on Linux. Long log lines are trimmed and timestamps are removed.
Before you begin
You need:
-
Linux. Keploy's agent runs as root, so Keploy may ask for your
sudopassword. -
Go 1.21 or newer.
-
Docker, to run PostgreSQL.
-
Keploy. To install it, run:
source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')"For other ways to install it, see Installation.
Step 1: Create the sample package
-
Create a folder, a git repository and a Go module:
mkdir orders && cd orders
git init
go mod init example.com/orders -
Save this as
orders.go.TotalInreads an order from PostgreSQL, asks the rates API for an exchange rate, and returns the converted total:// Package orders prices an order in another currency. The order comes from
// PostgreSQL and the exchange rate from a rates API.
package orders
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"net/http"
)
type Service struct {
DB *sql.DB
RatesURL string
}
// TotalIn returns the order's total, converted to currency.
func (s *Service) TotalIn(ctx context.Context, orderID int, currency string) (float64, error) {
var cents int
var from string
err := s.DB.QueryRowContext(ctx,
"SELECT amount_cents, currency FROM orders WHERE id = $1", orderID).Scan(¢s, &from)
if err != nil {
return 0, fmt.Errorf("order %d: %w", orderID, err)
}
url := fmt.Sprintf("%s/rates?from=%s&to=%s", s.RatesURL, from, currency)
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return 0, err
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return 0, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return 0, fmt.Errorf("rates API: %s", resp.Status)
}
var rate struct {
Rate float64 `json:"rate"`
}
if err := json.NewDecoder(resp.Body).Decode(&rate); err != nil {
return 0, err
}
return float64(cents) / 100 * rate.Rate, nil
} -
Save this as
orders_test.go. Each test creates the table and its rows, then checks one total:package orders
import (
"context"
"database/sql"
"testing"
_ "github.com/lib/pq"
)
func newService(t *testing.T) *Service {
db, err := sql.Open("postgres",
"postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { db.Close() })
_, err = db.Exec(`CREATE TABLE IF NOT EXISTS orders (
id int PRIMARY KEY, amount_cents int NOT NULL, currency text NOT NULL)`)
if err != nil {
t.Fatal(err)
}
_, err = db.Exec(`INSERT INTO orders VALUES (1, 4000, 'EUR'), (2, 1250, 'USD')
ON CONFLICT (id) DO NOTHING`)
if err != nil {
t.Fatal(err)
}
return &Service{DB: db, RatesURL: "http://localhost:8090"}
}
func TestTotalInUSD(t *testing.T) {
s := newService(t)
got, err := s.TotalIn(context.Background(), 1, "USD")
if err != nil {
t.Fatal(err)
}
if got != 50 {
t.Fatalf("total = %v, want 50", got)
}
}
func TestTotalInEUR(t *testing.T) {
s := newService(t)
got, err := s.TotalIn(context.Background(), 2, "EUR")
if err != nil {
t.Fatal(err)
}
if got != 10 {
t.Fatalf("total = %v, want 10", got)
}
} -
Save this as
cmd/rates/main.go. It stands in for a real exchange-rates API:// A stand-in for a real exchange-rates API.
package main
import (
"encoding/json"
"log"
"net/http"
)
var rates = map[string]float64{"EUR-USD": 1.25, "USD-EUR": 0.8, "EUR-GBP": 0.875}
func main() {
http.HandleFunc("/rates", func(w http.ResponseWriter, r *http.Request) {
pair := r.URL.Query().Get("from") + "-" + r.URL.Query().Get("to")
rate, ok := rates[pair]
if !ok {
http.Error(w, "unknown pair "+pair, http.StatusNotFound)
return
}
json.NewEncoder(w).Encode(map[string]float64{"rate": rate})
})
log.Println("rates API on :8090")
log.Fatal(http.ListenAndServe(":8090", nil))
} -
Add the PostgreSQL driver:
go get github.com/lib/pq@v1.10.9
go mod tidy
Step 2: Run the tests against the real dependencies
-
Start PostgreSQL:
docker run -d --name orders-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16Then wait until it accepts connections. The first start takes a few seconds:
until docker exec orders-db pg_isready -q -h 127.0.0.1 -U postgres; do sleep 1; done -
In a second terminal, in the
ordersfolder, start the rates API:go run ./cmd/rates -
Back in the first terminal, run the tests:
go test -count=1 ./...ok example.com/orders 0.031s
? example.com/orders/cmd/rates [no test files]
-count=1 turns off Go's test cache. Without it, go test can print a cached
result and skip the tests, and then there are no calls to record or replay.
Step 3: Record the calls
Run the same test command under keploy mock record:
keploy mock record --local -c "go test -count=1 ./..."
🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "default", "program": "go", "args": 3}
🐰 Keploy: INFO Starting Application : {"program": "go", "args": 3}
ok example.com/orders 0.035s
? example.com/orders/cmd/rates [no test files]
🐰 Keploy: INFO recorded mocks {"mocks": 10, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}
--local keeps the recording in your repository, so you don't need a Keploy
account for this quickstart. Without --local, Keploy asks you to sign in
first.
Keploy wrote four files:
keploy.yml, the project's Keploy settings. It holds the app name and the test command.keploy/default/mocks.yaml, the recording: 10 mocks, 8 for PostgreSQL (the connections and each statement) and 2 HTTP calls, each with its answer.keploy/default/last-record.yaml, the command Keploy recorded this set with.keploy mock statusreplays the recording with it.keploy/.gitignore, which keeps Keploy's temporary files out of git.
Here is one HTTP call from mocks.yaml, trimmed:
kind: Http
name: mock-4
spec:
metadata:
destAddr: "[::1]:8090"
operation: GET
type: HTTP_CLIENT
req:
method: GET
url: /rates?from=EUR&to=USD
header:
Host: localhost:8090
resp:
status_code: 200
body: |
{"rate":1.25}
Step 4: Replay with the dependencies off
-
Stop PostgreSQL:
docker rm -f orders-db -
Stop the rates API with Ctrl+C in the second terminal.
-
Run the tests on their own. They fail, because nothing answers:
go test -count=1 ./...orders_test.go:22: dial tcp [::1]:5432: connect: connection refused
FAIL
FAIL example.com/orders 0.005s -
Run them under
keploy mock replay:keploy mock replay --local -c "go test -count=1 ./..."🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "go", "args": 3, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "go", "args": 3}
ok example.com/orders 0.163s
? example.com/orders/cmd/rates [no test files]
🐰 Keploy: INFO mock replay summary {"loaded": 10, "consumed": 8, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 8}
The tests pass with no database and no rates API running. Keploy answered every call from the recording.
Step 5: Add a test, and see a call with no recording
-
Add this test at the end of
orders_test.go:func TestTotalInGBP(t *testing.T) {
s := newService(t)
got, err := s.TotalIn(context.Background(), 1, "GBP")
if err != nil {
t.Fatal(err)
}
if got != 35 {
t.Fatalf("total = %v, want 35", got)
}
} -
Replay again, with the dependencies still off:
keploy mock replay --local -c "go test -count=1 ./..."--- FAIL: TestTotalInGBP (0.02s)
orders_test.go:27: pq: keploy-pg-v3: no recorded invocation matched (hash=…e6592f0c76da currentTest= binds=6); …
FAIL
FAIL example.com/orders 0.228s
🐰 Keploy: INFO mock replay summary {"loaded": 10, "consumed": 8, "missed": 1}
Mock mismatch: [PostgreSQL] INSERT INTO orders VALUES ($1, $2, $3), ($4, $5, $6)
ON CONFLICT (id) DO NOTHING → [::1]:5432
Hint: The 2 recorded invocation(s) of this SQL available at this point of the run were all already served: the application ran it more times here than the recording holds. If the extra call is intended, re-record the mock set with 'keploy mock record'; otherwise find what makes the application repeat it.
🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1}The new test runs the
INSERTa third time, and the recording holds it twice. Keploy doesn't send the call to the real database. It fails the run, names the call, and says what to do. The exit code is the test command's, so CI fails too. -
Start the dependencies again, as in Step 2, and record again:
keploy mock record --local -c "go test -count=1 ./..."ok example.com/orders 0.088s
🐰 Keploy: INFO recorded mocks {"mocks": 15, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}A new record replaces the set, so the recording always matches the tests you have now.
-
Stop the dependencies, as in Step 4, and replay:
keploy mock replay --local -c "go test -count=1 ./..."ok example.com/orders 0.221s
🐰 Keploy: INFO mock replay summary {"loaded": 15, "consumed": 12, "missed": 0}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 12}
Step 6: Check each test on its own
So far, Keploy answers the calls of the whole run. With KEPLOY_PROVEN=1,
it also knows where each test starts and ends. It then gives each test only the
calls that test recorded, replays every test before it keeps the recording, and
reports a result per test.
-
Add Keploy's Go package:
go get github.com/keploy/go-sdk/v3@v3.1.3 -
In
orders_test.go, import it, and makedefer keploytest.T(t)()the first line of each test:import (
"context"
"database/sql"
"testing"
"github.com/keploy/go-sdk/v3/keploytest"
_ "github.com/lib/pq"
)func TestTotalInUSD(t *testing.T) {
defer keploytest.T(t)()
s := newService(t)
// ...the rest of the test is unchanged
}Do the same in
TestTotalInEURandTestTotalInGBP. Outside Keploy, the line does nothing, sogo testworks as before. -
In
keploy.yml, replace themock:block with this one. It adds the command Keploy runs the tests with:mock:
name: default
command: go test -p 1 -count=1 -json ./...
local: true-p 1runs one test binary at a time, which per-test checks need in this release.-jsonshows each test's result, and the reason for a skip. It also makesgo testprint a JSON line for each test event, so the outputs below leave those lines out and show Keploy's own.local: truekeeps the recording in the repository, as--localdid. -
Start the dependencies again, as in Step 2. Then delete the old recording, and record:
rm -rf keploy
export KEPLOY_PROVEN=1
keploy mock record🐰 Keploy: INFO wrote per-test mock mappings {"tests": 3, "mock-set": "default"}
🐰 Keploy: INFO recorded mocks {"mocks": 15, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}
keploy: judging round F (go test -p 1 -count=1 -json ./...): 3 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy; its output: …/round-F.log
keploy: judging round C (go test -p 1 -count=1 -json ./...): 3 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy; its output: …/round-C.log
keploy: committed keploy/default and its verdicts.yaml: 3 replayable, 0 quarantinedAfter the record, Keploy replayed the tests twice with the dependencies off (the judging rounds). All 3 replayed, so it kept all 3. A test that doesn't replay is set aside in
keploy/default/verdicts.yaml, with the reason and the fix. -
Ask Keploy what to do next:
keploy mock status=== KEPLOY NEXT ===
phase: recorded
summary: 1 recording(s); not yet proven to run with the dependencies off: default (never replayed on this machine).
ask: Prove it offline? I'll replay the tests with every dependency switched off; any call the recording does not have fails the run.
run: KEPLOY_PROVEN=1 keploy mock replay --local -c 'go test -p 1 -count=1 -json ./...' --on-miss failkeploy mock statusalways prints aNEXTblock like this one: where things stand, and the command to run next. Coding agents read it too. -
Stop the dependencies, and replay:
keploy mock replay🐰 Keploy: INFO mock replay summary {"loaded": 15, "consumed": 12, "missed": 0}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 12}
keploy: default: 3 test(s) ran: 3 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
MOCKED .::TestTotalInUSD: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record)
MOCKED .::TestTotalInUSD: [::1]:8090 (mocked: if this is your app, start it from the runner, then re-record)
MOCKED .::TestTotalInEUR: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record)
MOCKED .::TestTotalInGBP: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record)
VERDICT passedEach
MOCKEDline names a connection a test opened that Keploy answered. The EUR and GBP tests reuse the HTTP connection the USD test opened, so only the USD test lists port 8090. -
Make a test fail on purpose. In
TestTotalInUSD, change both50s to51, then replay:keploy mock replaykeploy: default: 3 test(s) ran: 2 passed, 1 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
FAILED .::TestTotalInUSD: the test failed
VERDICT failed: the test command exited 1Keploy names the test that failed, and exits with the test command's code. Change the
51s back to50.
Step 7: Commit the recording
Commit keploy.yml and the keploy/ folder with your code:
git status --short
?? cmd/
?? go.mod
?? go.sum
?? keploy.yml
?? keploy/
?? orders.go
?? orders_test.go
keploy/default/ holds the recording (mocks.yaml), which recorded calls
belong to each test (mappings.yaml), each test's result from the judging
rounds (verdicts.yaml), the record command (last-record.yaml) and a
README.md. Commit them all. The other files in keploy/default/, such as
last-replay.yaml, are run files from this machine's last record and replay:
keploy/.gitignore keeps them out of git.
Keploy also writes .keploy-run/, with the logs of each run. Its own
.gitignore keeps it out of git.
Now anyone can run KEPLOY_PROVEN=1 keploy mock replay on a clone, with no
PostgreSQL and no rates API, and CI can too.
Clean up
Step 6 stopped PostgreSQL and the rates API, so nothing is left running.
Delete the orders folder when you no longer need it.
Next steps
- Run the replay in CI, and share recordings with your team.
With a Keploy account, recordings live in Keploy Cloud, and the repository
keeps only
keploy.ymlandkeploy.lock. - Use the VS Code extension to record and replay from your editor.
- Learn every option of
keploy mock.