Skip to main content

Example URL Shortener App

A sample url shortener app to test Keploy integration capabilities in Go.

In this sample application we're using 2 dependencies - Gin, mongoDB.


1. Installation Methods​

There are two ways to quickly install and run the Keploy Server:

  • Helm Charts: Deploying the Server to Kubernetes is an easy way to improve collaboration amongst test QAs, SDEs, SDETs.
  • Docker: Using docker-compose is recommended for individual developers to record, maintain and test locally.

We do not recommend using any of these methods in a full (production) environment.

Helm Charts​

Keploy can also be installed to your Kubernetes cluster using the Helm chart. It automatically deploys a mongo instance using the Bitnami Mongo Helm chart


helm upgrade -i keploy .

Access via kube proxy​

export POD_NAME=$(kubectl get pods --namespace default -l "," -o jsonpath="{.items[0]}")
export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT

Then the keploy service should be accessible on

Access via ingress​

To access Keploy though ingress, please add information about ingress in the values.yaml file.



  1. Install Docker
  2. Install docker-compose

Start keploy server locally​

git clone && cd keploy

Now start the Keploy server.

docker-compose up

Voilà! 🧑🏻‍💻 We have the server running!

Now open the Keploy Console at http://localhost:8081

Once you have the Keploy Server running, open the Keploy Console at http://localhost:8081

Setup URL shortener​

git clone && cd samples-go/gin-mongo
go mod download

Run the application​

go run handler.go main.go

Generate testcases​

To generate testcases we just need to make some API calls. You can use Postman, Hoppscotch, or simply curl

1. Generate shortened url​

curl --request POST \
--url http://localhost:8080/url \
--header 'content-type: application/json' \
--data '{
"url": ""

this will return the shortened url. The ts would automatically be ignored during testing because it'll always be different.

"ts": 1645540022,
"url": "http://localhost:8080/Lhr4BWAi"

2. Redirect to original url from shortened url​

curl --request GET \
--url http://localhost:8080/Lhr4BWAi

or by querying through the browser http://localhost:8080/Lhr4BWAi

Now both these API calls were captured as a testcase and should be visible on the Keploy console. If you're using Keploy cloud, open this.

You should be seeing an app named sample-url-shortener with the test cases we just captured.


Now, let's see the magic! 🪄💫

Test mode​

There are 2 ways to test the application with Keploy.

  1. Unit Test File
  2. KEPLOY_MODE environment variable

Testing using Unit Test File​

Now that we have our testcase captured, run the unit test file (main_test.go) already present in the sample app repo.

If not present, you can add main_test.go in the root of your sample application.

  package main

import (

func TestKeploy(t *testing.T) {
go main()

To automatically download and run the captured test-cases. Let's run the test-file.

 go test -coverpkg=./... -covermode=atomic  ./...

output should look like -

ok      test-app-url-shortener  6.268s  coverage: 80.3% of statements in ./...

We got 80.3% without writing any testcases or mocks for mongo db. 🎉

Note : You didn't need to setup mongoDB locally or write mocks for your testing.

The application thought it's talking to mongoDB 😄

Go to the Keploy Console TestRuns Page to get deeper insights on what testcases ran, what failed.




Testing using KEPLOY_MODE Env Variable​

To test using KEPLOY_MODE env variable, set the same to test mode.

export KEPLOY_MODE="test"

Now simply run the application.

go run handler.go main.go

Keploy will run all the captures test-cases, compare and show the results on the console.

Note : With this method coverage will not be calculated.

Let's add a Bug in the App​

Now let's introduce a bug! Let's try changing something like renaming url to urls in handler.go ./handler.go on line 96

c.JSON(http.StatusOK, gin.H{
"urls": "http://localhost:8080/" + id,

Let's run the test-file to see if Keploy catches the regression introduced.

go test -coverpkg=./... -covermode=atomic ./...

You'll notice the failed test-case in the output.

{"msg":"result","testcase id":"05a576e1-c03a-4c25-a469-4bea0307cd08","passed":false}
{"msg":"result","testcase id":"cad6d926-b531-477c-935c-dd7314c4357a","passed":true}
{"msg":"test run completed","run id":"19d4cba1-b77c-4301-884a-5b3f08dc6248","passed overall":false}
--- FAIL: TestKeploy (5.72s)
keploy.go:42: Keploy test suite failed
coverage: 80.3% of statements in ./...
FAIL test-app-url-shortener 6.213s

To deep dive the problem go to test runs