Integrating Keploy with a Simple Node.js API

This blog documents my experience completing a DevRel assignment where the goal was to integrate Keploy with a project of my choice and understand how it captures traffic, generates test cases and mocks, and replays tests.

The focus here is on understanding Keploy’s workflow end-to-end in a local setup and explaining it in a beginner-friendly way.

Project Setup

For this assignment, I chose to work with a Node.js + Express application. I intentionally kept the project minimal so that the behavior of Keploy was easy to observe without additional complexity.

The application exposes two endpoints:

POST /users - create a user
GET /users/:id - fetch a user by ID

Users are stored in an in-memory array. No database is involved.

Environment Check

Before starting, I verified the environment:

node -v
npm -v
docker -v

Output:

v20.19.6
10.8.2
Docker version 29.1.3

Docker was available but not required for this setup.

Initial Application Setup

I started by creating a new Node.js project:

mkdir keploy-demo
cd keploy-demo
npm init -y

Then installed Express:

npm install express

After that, I created an index.js file with the two API endpoints.

To make sure the application worked independently, I ran it normally:

node index.js

Output:

Server running on port 3000

I stopped the server and confirmed the project structure:

index.js node_modules package.json package-lock.json

First Attempt at Running Keploy

I tried running Keploy in record mode:

keploy record -c "node index.js" --port 3000

This failed with:

keploy: command not found

At this point, Keploy was clearly not available in the system path.

Installing Keploy

I removed any partial installation and installed Keploy using the official script:

sudo rm -f /usr/local/bin/keploy
curl -sL https://keploy.io/install.sh | bash

The installation completed successfully and printed the Keploy version and usage instructions.

However, running Keploy still didn’t work immediately. The issue was that the Keploy binary was not available in the PATH.

To fix this, I exported the path manually:

export PATH=$PATH:$HOME/.keploy/bin

After this, the keploy command was accessible.

Running:

keploy version

returned an error saying the version command was unknown, which is expected behavior in the newer Keploy CLI. Instead, I verified the CLI using:

keploy --help

Running the Application with Keploy

Once Keploy was accessible, I ran the application in record mode:

keploy record -c "node index.js"

Keploy started successfully with the application. At this stage:

The app was running on port 3000
Keploy was attached to observe traffic
No tests were generated yet

Sending Traffic to the Application

In a second terminal, I started sending requests to the API.

Creating a user:

curl -X POST http://localhost:3000/users \
-H "Content-Type: application/json" \
-d '{"id":"1","name":"Shivani"}'

Response:

{"message":"User created","user":{"id":"1","name":"Shivani"}}

Fetching the user:

curl http://localhost:3000/users/1

Response:

{"id":"1","name":"Shivani"}

I sent multiple requests to ensure Keploy captured enough traffic.

Generated Keploy Artifacts

After stopping Keploy and checking the directory again, new files appeared:

index.js
keploy
keploy.yml
keploy_agent.log
node_modules
package.json
package-lock.json

This confirmed that Keploy had successfully:

Captured the API traffic
Generated test cases and mocks
Created a configuration file (keploy.yml)

The keploy/ directory contains the auto-generated test sets and mocks.

The repository includes the generated test cases and mocks under the keploy/ directory, along with the Keploy configuration file. Files generated only during local execution are excluded to keep the setup clean and reproducible.

Replaying Tests with Keploy

To validate the generated tests, I ran Keploy in test mode:

keploy test -c "node index.js"

When I ran Keploy in test mode, the application started again just like a normal run. This time, instead of waiting for new requests, Keploy replayed the requests that were recorded earlier during traffic capture.

Keploy compared the response for each request from the running application with the response that was recorded earlier.

Since the responses matched and the tests passed successfully. This confirmed that the replay worked as expected and that the application behavior remained consistent.

How Keploy Works

This is how I understood Keploy’s workflow, based on this setup.

Keploy runs alongside the application in record mode and observes real HTTP requests and responses. Test cases are not generated automatically at startup, they are created only when actual traffic hits the application.

Keploy generates mocks along with test cases, so that test replay does not depend on live state or external changes. This makes the replay deterministic.

Keploy replays the recorded during test mode, traffic against the application and validates the responses against the recorded behavior. This approach is different from writing manual tests and works well for API-heavy applications where writing and maintaining tests manually can be time-consuming.

What I Learned

A few key takeaways from this assignment:

Keploy depends entirely on real traffic to generate test cases. If no traffic hits the application, no tests are created.

Keeping the project minimal made it easier to understand how Keploy behaves and what each step is doing. Running the application normally before adding Keploy also helped simplify debugging and isolate issues early.

Conclusion

This assignment helped me understand how Keploy captures API traffic, generates test cases and mocks, and replays them to validate application behavior.
Here I used a minimal Node.js setup that made it easier to focus on Keploy’s workflow without unnecessary complexity.

Command Palette