DEV Community

Cover image for What Is Keploy? Record-and-Replay API Testing
Hassann
Hassann

Posted on • Originally published at apidog.com

What Is Keploy? Record-and-Replay API Testing

If you want API tests without writing every case by hand, Keploy is worth evaluating. It records real traffic from your running application, turns that behavior into test cases, and replays those cases later as regression tests.

Try Apidog today

This guide shows what Keploy does, how its eBPF-based record-and-replay workflow works, how to install and run it, and where it fits in a practical API testing stack.

What is Keploy

Keploy is an open-source platform, licensed under Apache 2.0, for creating isolated API, integration, and end-to-end tests from real application behavior.

Instead of asking you to manually describe expected behavior in test code, Keploy observes your running service and converts the observed traffic into reproducible tests.

Keploy record and replay

Keploy supports two main workflows:

  1. Record and replay: capture real API interactions and dependencies, then replay them deterministically.
  2. AI test generation: generate validated API test suites from an OpenAPI spec, Postman collection, cURL command, or live endpoint.

Both workflows produce runnable tests and mocks, so your tests can run without hitting live dependencies.

The project is open source. You can inspect the code at github.com/keploy/keploy, and the official docs are available at keploy.io/docs.

How Keploy record works at the eBPF layer

The key feature of Keploy is that it records traffic without requiring an SDK, middleware, decorators, or application code changes.

When you run:

keploy record -c "CMD_TO_RUN_APP"
Enter fullscreen mode Exit fullscreen mode

Keploy starts your application and captures network activity using eBPF, a Linux kernel technology that allows programs to observe system-level events safely.

In practice, this means:

  • No code instrumentation: you do not need to modify handlers, services, or clients.
  • Language-agnostic capture: the same capture model can work across Go, Java, Node.js, Python, Rust, and other runtimes.
  • Dependency capture: Keploy records not only inbound API calls, but also outbound dependency calls such as database queries, downstream API requests, and messaging events.

For each observed request, Keploy captures:

  • the incoming API request
  • the API response
  • dependency calls made during request handling
  • mock responses for those dependencies

From that, it writes two kinds of artifacts:

  • a test case that defines the expected request and response
  • mocks and stubs for dependencies used during replay

During replay, Keploy sends the recorded request back to your application, serves dependency responses from mocks, and compares the new response with the recorded one. If the output changes, the test fails.

That makes Keploy useful for regression testing: record known-good behavior once, then replay it after every code change.

The two Keploy workflows

1. Record and replay

Use this workflow when you already have a working application and want fast regression coverage.

A typical flow looks like this:

# Start your app through Keploy
keploy record -c "node server.js"
Enter fullscreen mode Exit fullscreen mode

Then exercise your API using:

  • manual requests
  • an API client
  • an existing integration test suite
  • realistic traffic in a controlled environment

Keploy records those interactions as test cases and generates mocks for dependencies.

Later, run:

keploy test -c "node server.js" --delay 10
Enter fullscreen mode Exit fullscreen mode

Keploy replays the captured requests and flags response mismatches.

2. AI test generation

Use AI test generation when you want to generate coverage from an API contract or endpoint instead of only recording live behavior.

Keploy can generate API test suites from:

  • an OpenAPI specification
  • a Postman collection
  • a cURL command
  • a live endpoint

It also mocks dependencies and runs cleanup to reduce redundant cases.

The workflows are complementary:

  • Record and replay validates real observed behavior.
  • AI test generation helps create broader coverage from a spec or endpoint.

If you are comparing tools that generate tests from schemas, see this roundup of AI test case generators and this guide to generating test scripts from OpenAPI.

Installing Keploy

Keploy provides an install script. On a supported system, run:

curl --silent -O -L https://keploy.io/install.sh && source install.sh
Enter fullscreen mode Exit fullscreen mode

This installs the keploy command.

After installation, most usage centers around two commands:

keploy record
keploy test
Enter fullscreen mode Exit fullscreen mode

Recording API traffic

To record traffic, pass the command that starts your application with -c:

keploy record -c "CMD_TO_RUN_APP"
Enter fullscreen mode Exit fullscreen mode

For example, with a Node.js app:

keploy record -c "node server.js"
Enter fullscreen mode Exit fullscreen mode

Then call your API as you normally would.

For example:

curl http://localhost:3000/users
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'
Enter fullscreen mode Exit fullscreen mode

Keploy watches the application traffic and saves test cases and mocks from the observed behavior.

Replaying recorded tests

To replay captured tests, run:

keploy test -c "CMD_TO_RUN_APP" --delay 10
Enter fullscreen mode Exit fullscreen mode

Example:

keploy test -c "node server.js" --delay 10
Enter fullscreen mode Exit fullscreen mode

The --delay 10 flag tells Keploy to wait 10 seconds before sending recorded requests. This gives your application time to boot before replay begins.

Adjust the value based on startup time:

# For a slower service
keploy test -c "node server.js" --delay 30

# For a fast-starting service
keploy test -c "node server.js" --delay 3
Enter fullscreen mode Exit fullscreen mode

A practical first session looks like this:

# 1. Record while you exercise your API
keploy record -c "node server.js"

# 2. Replay the captured cases
keploy test -c "node server.js" --delay 10
Enter fullscreen mode Exit fullscreen mode

Once the recorded tests are stable, commit the generated test cases and mocks to your repository and run keploy test in CI.

Supported languages, protocols, and datastores

Because Keploy captures traffic at the network layer, it can support a broad set of runtimes and systems.

Category Supported
Languages Go, Java, Node.js, Python, Rust, C#, C/C++, TypeScript, and more
Protocols HTTP/REST, gRPC, GraphQL, Kafka, RabbitMQ
Datastores PostgreSQL, MySQL, MongoDB, Redis

The eBPF approach means Keploy does not need a separate plugin for every framework. If your service communicates over a supported protocol, Keploy can capture the interaction at the network level.

Running Keploy in CI

A simple CI setup usually follows this pattern:

  1. Record tests locally or in a controlled environment.
  2. Commit the generated test cases and mocks.
  3. Start the application in CI through keploy test.
  4. Fail the build if replayed responses differ from recorded expectations.

Example CI command:

keploy test -c "node server.js" --delay 10
Enter fullscreen mode Exit fullscreen mode

Because Keploy replays dependency calls from generated mocks, the CI job does not need live databases or downstream services for those captured interactions. That keeps replay runs more deterministic.

Limitations to consider

Keploy is useful, but it is not the right tool for every testing problem.

Key trade-offs:

  • Linux and permissions matter: eBPF is a Linux kernel feature, and network-level capture often requires elevated privileges.
  • Generated tests still need review: recorded or AI-generated tests are a starting point. You still need to remove noisy cases and decide which behaviors are real contracts.
  • It is focused on testing, not the full API lifecycle: Keploy captures, generates, mocks, and replays tests. It is not an API design, documentation, collaboration, or consumer-facing mock-server platform.

These limits are not flaws. They define the category Keploy belongs to. Use it when traffic-based regression testing is the problem you need to solve.

Where Apidog fits as the designed-testing alternative

If your workflow goes beyond recording runtime behavior, consider a full API lifecycle platform.

Apidog is an all-in-one API platform for API design, debugging, mocking, documentation, and testing.

Apidog API testing platform

The distinction is important:

  • Keploy records real runtime behavior and replays it with generated dependency mocks.
  • Apidog lets teams design, author, organize, and maintain API test scenarios as part of the broader API lifecycle.

With the Apidog CLI, you can run authored API collections from the terminal and CI. It supports data-driven testing with CSV or JSON, environment switching, and CLI, HTML, and JSON reports.

Apidog also supports AI test case generation from API schemas and endpoints.

The boundary is clear:

  • Apidog does not capture live traffic via eBPF.
  • Apidog does not auto-generate tests by recording production calls and dependency mocks.
  • Keploy does provide that record-from-traffic capability.

Choose based on the job:

  • Use Keploy when you want zero-code runtime capture and deterministic replay.
  • Use Apidog when you want designed, maintainable API tests inside a platform that also handles design, docs, mocking, debugging, and collaboration.

For a deeper comparison, see Apidog vs Keploy. If you are moving from Keploy to Apidog CLI, this migration walkthrough explains the process.

If maintainable authored API tests are your priority, you can download Apidog and start with this guide to testing an API with Apidog.

Frequently asked questions

Is Keploy free and open source?

Yes. Keploy is open source under the Apache 2.0 license, and the code is available on GitHub. You can self-host it.

Does Keploy require changing application code?

No. The record-and-replay workflow captures traffic at the eBPF network layer, so there is no SDK to add and no application code to change.

What does --delay do in keploy test?

It controls how long Keploy waits before sending recorded requests to your application. For example:

keploy test -c "node server.js" --delay 10
Enter fullscreen mode Exit fullscreen mode

This waits 10 seconds before replay begins.

Can Keploy mock a database during tests?

Yes. When Keploy records an interaction, it also captures dependency calls such as database queries and generates mocks for them. During replay, tests can run without a live database.

Is Keploy a replacement for an API design and documentation tool?

No. Keploy is focused on test generation, mocks, and replay. For API design, documentation, consumer-facing mocks, collaboration, and authored API testing, a full-lifecycle platform such as Apidog is a better fit.

The short version

Keploy turns real API behavior into regression tests. Its record-and-replay engine uses eBPF to capture requests, responses, and dependency calls at the network layer without code changes. It can then replay those interactions with generated mocks.

It is a strong fit when you want fast regression coverage from real traffic. Its main trade-offs are Linux/eBPF requirements, the need to curate generated tests, and a scope focused on testing rather than the full API lifecycle.

If you want authored, maintainable API test suites inside a complete API platform, compare it with Apidog.

Top comments (0)