Getting Started with Keploy: Testing Gin + Redis Application

In this guide, you'll learn how to use Keploy to automatically generate and run API tests for a Go Gin application backed by Redis.

What is Keploy?

Keploy is an open-source automated testing tool that records your API interactions and generates test cases automatically - without writing a single line of test code!

Why Use Keploy?

• Zero Test Code: No need to write manual tests
• Automatic Mocking: Database calls are mocked automatically
• Time-Saving: Record once, replay anytime
• Easy Integration: Works with existing applications

Prerequisites

Before we begin, make sure you have:

• Go (version 1.20 or higher)
• Docker (for running Redis)
• WSL (Windows Subsystem for Linux) - Keploy runs on Linux

Terminal Setup

For this tutorial, you'll work with 4 terminal windows:

1. Terminal 1 - Initial setup (installations)
2. Terminal 2 - Redis server (keeps running)
3. Terminal 3 - Keploy recording (keeps running)
4. Terminal 4 - Making API calls (testing)

Keep terminals 2 and 3 running throughout the tutorial. Only Terminal 4 will be used for active testing.

Let's get started.

Step 1: Install Required Tools

→ Terminal 1

Open your WSL Ubuntu terminal and install everything we need.

Install Go

# Download Go
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz

# Extract to /usr/local
sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz

# Add Go to your PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Verify installation
go version

Expected output:

go version go1.21.6 linux/amd64

Install Docker

Docker will run our Redis database in a container.

# Download and run Docker installation script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group (avoids needing sudo)
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version

Install Keploy

# Download and install Keploy
curl --silent --location "https://github.com/keploy/keploy/releases/latest/download/keploy_linux_amd64.tar.gz" | tar xz -C /tmp

# Move to system binaries
sudo mv /tmp/keploy /usr/local/bin

# Verify installation
keploy --version

Clone the Sample Project

We'll use Keploy's official Gin + Redis sample application.

# Clone the samples repository
git clone https://github.com/keploy/samples-go.git

# Navigate to the Gin-Redis project
cd samples-go/gin-redis

# Download Go dependencies
go mod download

# Build the application
go build -o gin-redis

Keep Terminal 1 open. You'll need it later to stop processes and view test results.

Step 2: Start Redis Database

→ Terminal 2 (New Window)

Open a new terminal window and navigate to the project directory.

cd ~/samples-go/gin-redis
docker compose up redis

What's happening? This command starts a Redis database in a Docker container. Redis will store the OTPs (One-Time Passwords) that our API generates.

Expected output:

✔ Container myredis Running
Attaching to myredis
myredis | Ready to accept connections tcp

Do not close Terminal 2. Redis must stay active for the application to work. Minimize this window and proceed to Terminal 3.

Step 3: Start Keploy Recording

→ Terminal 3 (New Window)

Open another new terminal window. This is where Keploy will record your API interactions.

cd ~/samples-go/gin-redis
sudo keploy record -c "./gin-redis"

Keploy wraps your application and intercepts all API calls and database interactions. It records:

• HTTP requests and responses
• Redis queries and responses
• Timing and metadata

Expected output:

 ▓██▓▓▓▓ ▓▓▓   ░░░   ▓▓▓
...
🟠 Keploy is running in record mode
...
🚀 Starting application on http://localhost:3000

Your application is now running on http://localhost:3000 with Keploy actively recording.

Do not close Terminal 3. Keploy needs to stay active to record your test cases. Minimize this window and open Terminal 4.

Step 4: Test the API

→ Terminal 4 (New Window)

Open your 4th terminal window. This is where you'll make API calls to test the application.

Test 1: Generate an OTP

Send a request to generate a one-time password for a user.

curl --location 'localhost:3000/api/getVerificationCode?email=test@example.com&username=johndoe'

Expected response:

{
  "status": "true",
  "message": "OTP Generated successfully",
  "otp": "5928"
}

What happens internally?

1. Your API received the request
2. It generated a random OTP (e.g., "5928")
3. It stored the OTP in Redis with the email as the key.
4. Keploy recorded everything - the HTTP request, the Redis write, and the response.

Test 2: Verify the OTP

Now verify the OTP by sending it back to the API. Replace 5928 with your actual OTP from the previous response.

curl --location 'localhost:3000/api/verifyCode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "otp": 5928,
    "email": "test@example.com"
}'

Expected response:

{
  "status": "true",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "johndoe",
  "message": "OTP authenticated successfully"
}

What just happened?

1. Your API received the OTP verification request
2. It queried Redis to check if the OTP matches
3. It generated a JWT token for the authenticated user
4. Keploy recorded this entire flow including the Redis read operation

Optional: Record More Test Cases

The more scenarios you test, the more comprehensive your test suite becomes. Try different combinations:

# Different user
curl --location 'localhost:3000/api/getVerificationCode?email=jane@test.com&username=janedoe'

# Another email
curl --location 'localhost:3000/api/getVerificationCode?email=admin@company.com&username=admin'

Each unique request creates a new test case in Keploy.

Step 5: View Recorded Tests

→ Terminal 3

Go back to Terminal 3 (where Keploy is running) and press Ctrl+C to stop recording.

You'll see output showing how many test cases were recorded:

🎉 Test cases recorded: 2
📁 Saved to: ./keploy/tests

→ Terminal 1

Check the generated test files:

ls -la keploy/tests/

You'll see YAML files containing your recorded test cases. Each file includes:

• The HTTP request details
• The expected HTTP response
• All database interactions (mocked)

Step 6: Run the Tests

Now comes the key advantage of Keploy - replaying your tests without Redis!

→ Terminal 2

Stop Redis by pressing Ctrl+C in Terminal 2.

→ Terminal 3

Run Keploy in test mode:

sudo keploy test -c "./gin-redis"

What actually happened?

Keploy replays the recorded HTTP requests but mocks all Redis calls using the recorded responses. Your tests run without needing the actual database.

Expected output:

🧪 Running tests...

Test 1: PASSED ✓
Test 2: PASSED ✓

📊 Test Summary
Total: 2 | Passed: 2 | Failed: 0

All tests should pass because the responses match what was recorded.

What You've Learned

Keploy's Workflow:

1. Record Mode - Captures real API interactions and database calls
2. Test Generation - Automatically creates test cases from recordings
3. Test Mode - Replays requests with mocked dependencies
4. Validation - Compares actual vs expected responses

Key Benefits:

• Zero test code written - Everything was auto-generated
• Database mocking - Tests run without Redis
• Real scenarios - Tests based on actual API usage
• Fast feedback - Run tests in seconds

Next Steps

Now that you understand the basics:

1. Explore test files - Check keploy/tests/ to see generated YAML
2. Modify tests - Edit YAML files to test edge cases
3. CI/CD Integration - Add keploy test to your pipeline
4. Try other samples - Explore Keploy's quickstarts for different frameworks

Troubleshooting

go: command not found

source ~/.bashrc

export PATH=$PATH:/usr/local/go/bin
go version

echo $PATH | grep go
# Should show: /usr/local/go/bin

# Find process using port 3000
sudo lsof -i :3000

# Kill the process (replace PID with actual number)
kill -9 PID

# Ensure docker group membership
sudo usermod -aG docker $USER
newgrp docker

# Run Keploy with sudo
sudo keploy record -c "./gin-redis"

Still Having Issues?

If none of these solutions work:

1. Check Keploy logs:

sudo keploy record -c "./gin-redis" --debug

This shows detailed logs that can help identify the issue.

2. Verify system requirements:

# Check Ubuntu version
lsb_release -a

# Check available disk space
df -h

# Check memory
free -h

3. Join the community:

• 💬 Keploy Discord
• 🐙 GitHub Issues
• 📧 Community Forum

4. Provide context when asking for help:

# Share these details:
- OS: Windows 11 + WSL Ubuntu 22.04
- Go version: 1.21.6
- Docker version: 24.0.7
- Keploy version: 2.x.x
- Error message: [paste full error]
- What you tried: [steps you took]

Keploy eliminates the manual effort of writing and maintaining API tests, letting you focus on building features.

Questions or issues? Join the Keploy community for support!