Skip to main content
View as Markdown

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 sudo password.

  • 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​

  1. Create a folder, a git repository and a Go module:

    mkdir orders && cd orders
    git init
    go mod init example.com/orders
  2. Save this as orders.go. TotalIn reads 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(&cents, &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
    }
  3. 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)
    }
    }
  4. 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))
    }
  5. 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​

  1. Start PostgreSQL:

    docker run -d --name orders-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16

    Then 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
  2. In a second terminal, in the orders folder, start the rates API:

    go run ./cmd/rates
  3. 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 status replays 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​

  1. Stop PostgreSQL:

    docker rm -f orders-db
  2. Stop the rates API with Ctrl+C in the second terminal.

  3. 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
  4. 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​

  1. 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)
    }
    }
  2. 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 INSERT a 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.

  3. 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.

  4. 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.

  1. Add Keploy's Go package:

    go get github.com/keploy/go-sdk/v3@v3.1.3
  2. In orders_test.go, import it, and make defer 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 TestTotalInEUR and TestTotalInGBP. Outside Keploy, the line does nothing, so go test works as before.

  3. In keploy.yml, replace the mock: 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 1 runs one test binary at a time, which per-test checks need in this release. -json shows each test's result, and the reason for a skip. It also makes go test print a JSON line for each test event, so the outputs below leave those lines out and show Keploy's own. local: true keeps the recording in the repository, as --local did.

  4. 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 quarantined

    After 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.

  5. 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 fail

    keploy mock status always prints a NEXT block like this one: where things stand, and the command to run next. Coding agents read it too.

  6. 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 passed

    Each MOCKED line 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.

  7. Make a test fail on purpose. In TestTotalInUSD, change both 50s to 51, then replay:

    keploy mock replay
    keploy: 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 1

    Keploy names the test that failed, and exits with the test command's code. Change the 51s back to 50.

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​