Keploy: Auto-Generate API Tests by Capturing Real Traffic

Keploy: Auto-Generate API Tests by Capturing Real Traffic

Writing API tests by hand is slow, error-prone, and almost always incomplete. Developers miss edge cases, test data drifts from production reality, and mocks diverge from real service behavior over time. Keploy takes a different approach: instead of writing tests, you capture real traffic and let the tool generate them for you.

Keploy is an open-source API testing platform that records HTTP calls and database interactions from your running application, then replays those interactions as self-contained test cases — complete with auto-generated mocks for downstream dependencies.

How Keploy Works

Keploy sits between your application and its dependencies using eBPF-based traffic interception (on Linux) or an SDK integration. When you run your application with Keploy in record mode, it:

  1. Intercepts incoming HTTP requests to your service
  2. Records the request payload and all outgoing calls (database queries, downstream HTTP, gRPC)
  3. Records the responses at every layer
  4. Stores everything as a self-contained test case with embedded mocks

When you run in test mode, Keploy replays those exact requests against your application and compares responses. Instead of hitting a real database or downstream service, Keploy serves the recorded responses — making tests fast, deterministic, and isolated.

Setting Up Keploy

The fastest way to try Keploy is with Docker:

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

For a Node.js/Express service, you can use the SDK integration:

npm install @keploy/sdk
const { Keploy } = require('@keploy/sdk');
const keploy = new Keploy();
app.use(keploy.middleware());

For Go services, Keploy's eBPF-based approach requires no code changes — you wrap the binary:

keploy record -c "./myapp --port 8080"

Traffic your application receives while running in record mode becomes test cases automatically.

Recording Test Cases

Once recording is active, exercise your application normally — run your manual smoke tests, click through the UI, hit the API with curl:

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"item": "widget", "qty": 3}'

Keploy captures this interaction and saves it:

# keploy/tests/test-1.yaml
version: api.keploy.io/v1beta1
kind: Http
name: test-1
spec:
  metadata: {}
  req:
    method: POST
    url: /api/orders
    body: '{"item":"widget","qty":3}'
  resp:
    status_code: 201
    body: '{"orderId":"abc123","status":"created"}'
  mocks:
    - db_insert_orders
    - http_inventory_service

The mocks directory contains the recorded responses from every downstream call your application made while handling that request.

Running Captured Tests

To replay your recorded tests:

keploy test -c "./myapp --port 8080" --delay 10

Keploy starts your application, waits for it to be ready (the --delay flag), then replays each recorded request. It compares the actual response to the recorded response and reports diffs.

The output looks like:

✅ test-1 passed (POST /api/orders → 201)
✅ test-2 passed (GET /api/orders/abc123 → 200)
❌ test-3 failed
  Expected: {"status":"shipped"}
  Got:      {"status":"pending"}

This tells you the exact response that changed — often catching regressions that no hand-written test covered because the test data matched real production behavior.

Noise Filters and Flaky Test Prevention

Real responses often contain fields that change on every call: timestamps, generated IDs, request latency values. Keploy would fail every test if it compared these literally. It handles this with noise filters.

You can define fields to ignore in keploy.yml:

globalNoise:
  body:
    - "$.createdAt"
    - "$.requestId"
    - "$.traceId"
  header:
    - "X-Request-Id"

You can also mark noise per test case. Keploy detects common patterns automatically after a few test runs — if a field differs between the first and second replay of the same test, it flags that field as a noise candidate.

CI Integration

Keploy integrates with standard CI pipelines. The simplest approach is to run record mode against a staging environment, commit the generated test YAML files to your repository, and run test mode in CI:

# .github/workflows/test.yml
- name: Run Keploy tests
  run: |
    keploy test -c "./myapp" --delay 10 --ci

The --ci flag sets a non-zero exit code on any test failure, blocking the pipeline. Because test cases are plain YAML files, diffs are reviewable in pull requests — a test change is visible as a file change.

What Keploy Catches That Unit Tests Miss

Unit tests mock everything. Integration tests often mock the database or downstream services. Keploy tests use recorded real behavior, which means they catch:

  • Schema drift — a downstream service changed its response format and your code now parses wrong fields
  • Query regressions — a refactor changed the SQL your ORM generates, producing different data
  • Serialization bugs — a JSON field that was a string is now a number, breaking downstream consumers
  • Missing error paths — real production traffic often hits error conditions that test authors never thought to exercise

Where Keploy Fits in Your Test Strategy

Keploy is not a replacement for unit tests or contract tests. Unit tests run fast, test logic in isolation, and give precise failure messages. Keploy tests are integration-level — they test your service's behavior end-to-end, including how it interacts with databases and downstream APIs.

The practical use case: run unit tests constantly during development, and run Keploy tests as a regression gate before merging. When you capture test cases from a production-like environment, you get a suite that represents real usage without writing a single test by hand.

For teams that struggle with test coverage not because they don't want to test, but because writing and maintaining tests is expensive — Keploy changes the economics. Capture once, replay forever.

Monitoring Your APIs in Production

Test coverage during CI is valuable, but production behavior can still drift. Tools like HelpMeTest complement capture-replay testing by running continuous API health checks against your live endpoints — so you catch issues that never appeared in your recorded test suite because they only happen under specific production conditions.

The combination of Keploy (regression gate at merge time) and continuous monitoring (runtime health verification) covers both the "did we break something" and "is it working right now" questions.

Read more

Start now free