Keploy: recording real API traffic into replayable tests and mocks

The problem Keploy solves: integration tests that depend on live infrastructure

Most test suites split into two unhappy halves. Unit tests run fast but never touch a real database or a real HTTP boundary, so they miss the failures that reach production. Integration and E2E tests exercise the real path but need Postgres, MySQL, MongoDB, Kafka, RabbitMQ and a handful of third-party APIs to be up, seeded and reachable. That is why integration suites are slow and flaky in equal measure.

Keploy attacks the second half. The project describes itself as a developer-centric API and integration testing tool that auto-generates tests and data mocks, and the README states plainly that it records API calls, database queries and streaming events, then replays them as tests. The audience is the developer who owns a service and wants coverage of real request flows without maintaining a fixture factory or a docker-compose stack for every test run. QA engineers get a second lens: the same recordings feed API schema and business use-case coverage, which Keploy computes alongside statement and branch coverage.

How the eBPF capture and replay mechanism works

The mechanism is kernel-level, not library-level. The README states that Keploy uses eBPF to capture traffic at the network layer, which is why the project claims it is code-less and language-agnostic. The go.mod file is consistent with that claim: the dependency list includes github.com/cilium/ebpf, github.com/gopacket/gopacket and github.com/miekg/dns, alongside drivers for MySQL (go-sql-driver/mysql), Postgres (jackc/pgx/v5) and MongoDB (go.mongodb.org/mongo-driver/v2).

That dependency set tells you what the recorded artifacts are. Rather than only storing HTTP request and response pairs, Keploy records database queries and streaming events, so a replay can answer a Postgres query from a stored mock instead of a live server. The README frames this as complete infra-virtualization beyond HTTP mocks, and says the recordings replay deterministically. Determinism also depends on time: the project documents a time freezing feature that freezes system time during replay, which matters for code paths that branch on the current date or on token expiry.

The data flow is a loop. You run your application under keploy record, exercise it, and the agent writes test cases and mocks to disk. Later, keploy test starts the same command with the mocks in place and compares actual responses against recorded ones. The comparison is not naive string equality; go.mod includes github.com/keploy/jsonDiff and github.com/wI2L/jsondiff, and the README separately mentions AI-generated cases built from existing recordings and Swagger or OpenAPI schemas, targeting boundary values, missing or extra fields, wrong types and out-of-order sequences.

Installing the agent and recording your first test

The README gives a two-command install path. The installer is fetched and sourced, which means it runs in your current shell rather than a subshell:

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

After that, the keploy binary is on your PATH. The README does not document an uninstall step, so plan for the installer to modify your environment.

Recording starts your application under the agent. The command takes the command you would normally use to run the app:

keploy record -c "CMD_TO_RUN_APP"

The README's Python example substitutes a real start command:

keploy record -c "python main.py"

With the app running, send real traffic at it, through curl, a browser or your existing smoke tests. Keploy writes the captured calls and their dependencies to disk. When you are done, stop the app.

Replay is the second command. The README shows a delay flag, which gives the app time to boot before tests fire:

keploy test -c "CMD_TO_RUN_APP" --delay 10

What you should see is a report of passing and failing test cases, with the failing ones showing a diff between the recorded and actual response. Because the mocks stand in for Postgres, Kafka and external APIs, the app should not need those services running. The README does not document rollback of recorded artifacts, so treat the generated test and mock files as ordinary files you manage in version control.

Where Keploy is the wrong tool

The eBPF dependency is the sharpest constraint, and the README does not discuss it. Kernel-level interception requires a Linux host with the right kernel capabilities and, in practice, elevated privileges. If your CI runners are locked-down containers without CAP_BPF or equivalent, recording will not work there, and the README does not describe a fallback capture mode. The repository does ship a Dockerfile and a Dockerfile.runtime, and the Dockerfile comments note that libpg_query and pg_query_go require CGo, so the builder image must carry gcc. That is a build-time constraint for anyone compiling from source, separate from the runtime privilege question.

Language agnosticism has a boundary too. The README's claim rests on network-layer capture, which covers traffic that crosses the network stack. Code paths that call an in-process library directly, spawn a subprocess that never opens a socket, or read from a local file cache are not network traffic. If your service's riskiest logic is a pure function over local state, Keploy's recordings will not reach it, and a conventional unit test is the better instrument.

There is also a maturity question in the artifact contract. The README does not document how recordings are versioned, how they behave when a schema changes, or what happens to a mock set when a dependency is upgraded. The repository does list a Mock Registry for managing, reusing and versioning mocks across teams and environments, which suggests the project is aware of the problem, but the README points to external documentation rather than describing the behaviour.

Keploy compared with WireMock and Testcontainers

The nearest alternatives solve the same problem from opposite directions.

WireMock is a stub server. You declare the responses you want for given request patterns, by hand or from a mapping file, and your application talks to it instead of the real dependency. The difference is authorship: with WireMock a human decides what the stub returns, so the stub encodes what the team believes the dependency does. Keploy records what the dependency actually returned during a real session, so the mock encodes observed behaviour. WireMock gives you precise control and works anywhere a JVM or Docker runs; Keploy gives you less control and needs kernel access, but it produces the mock set without anyone writing mappings.

Testcontainers takes the third position: it starts real Postgres, Kafka or Redis in a container for the duration of the test. Nothing is mocked, so fidelity is high and there is no capture step. The cost is exactly what Keploy removes, which is the time and resources to boot and seed those containers on every run. If your suite is already fast enough with real containers, Testcontainers is the simpler answer and you should not add an interception layer on top of it.

The honest summary is that Keploy trades environmental requirements for authoring effort. You need Linux, kernel privileges and a record run against real dependencies. In exchange, nobody hand-writes the mock for each new database query.

Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-20, the same day as the v3.6.68 release. The three most recent releases, v3.6.68, v3.6.67 and v3.6.66, landed on 2026-09-20, 2026-09-20 and 2026-09-17 respectively. That cadence matters for upgrade cost: a project releasing several patch versions per week will move under you, and the README does not describe a stable long-term support line or a compatibility policy for recorded artifacts. Pin the version you validate against and re-run your recordings after each bump.

The code is Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It also requires that you preserve copyright and licence notices and state significant changes. That is the licence text, not advice about your situation; if you embed the agent in a distributed product, have counsel read the NOTICE and patent termination clauses rather than assuming permissive means unconditional. The README does not discuss the licensing of the hosted console at app.keploy.io, which is a separate service from the Apache-2.0 binary.

What the repository layout tells you about operating Keploy

Two Dockerfiles exist for different purposes, and the distinction is worth reading before you build. The Dockerfile comments state that CI does not use it; the release pipeline and pull request runs go through Dockerfile.runtime, which copies a prebuilt binary produced by an earlier GitHub Actions step on a native runner with gcc. The plain Dockerfile keeps an in-container go build path because external users need a single-command build from source. If you are building Keploy yourself, Dockerfile.runtime is the path the maintainers exercise.

The module targets Go 1.27.0 and module path go.keploy.io/server/v3. The presence of .golangci.yml, .pre-commit-config.yaml and a gitleaks dependency in go.mod indicates linting and secret scanning are part of the project's own workflow, not something you inherit by installing the agent. The tests/ directory and main_test.go, main_exitcode_test.go and main_exitcode_wiring_test.go at the repository root suggest the CLI's exit codes are covered by tests, which is relevant if you gate a pipeline on keploy test's exit status. The README does not document the exit code contract, so verify it in your own pipeline before wiring it to a required check.

Editorial conclusion

Adopt Keploy if your integration and E2E suites spend most of their time waiting on Postgres, Kafka or third-party APIs and you can run a privileged agent on the test host. Skip it if your environment forbids eBPF or kernel-level interception, or if you need Windows or macOS capture. Before committing, verify that a single keploy record followed by keploy test on one service produces the same pass or fail result twice, and that the mock set covers the external calls that actually break your builds.

Frequently asked questions

Official sources

1. keploy/keploy on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases