Skip to main content
View as Markdown

Contribution Guide​

Welcome to the world of Keploy development! This guide will help you set up Keploy locally.

1. Setting Up Your Platform:​

Keploy built from source intercepts with eBPF, so to record an app with your own build on macOS or Windows, you'll work inside a Linux VM. (To just use Keploy, you don't need one: it runs natively on macOS and Windows — see Installing Keploy below.)

  • For macOS, install Lima.
  • If you're on Windows, install WSL.

Note: Linux Users are good to go.

2. Pre-requisites:​

First things first, ensure you have Golang installed.

3. Clone Keploy Repository:​

Time to get your hands on Keploy!:

git clone https://github.com/keploy/keploy.git && cd keploy
go mod download

Once done, build the binary

go build -race -tags=viper_bind_struct -o keploy .
sudo mv keploy /usr/local/bin/
sudo chmod +x /usr/local/bin/keploy

Now we have successfully set up Keploy. Let’s test it with the sample app.

Keploy operates in two modes:​

  • record: Capture Keploy test cases from API calls.
  • test: Execute recorded test cases and validate assertions.

The Keploy CLI operates by capturing all network traffic between your application and its dependencies.

It meticulously records API calls, database queries, and any other interactions your application engages in.

Once the recording phase is complete, Keploy can effortlessly generate test cases and data mocks in YAML format.

If you don't have any samples app, you can use the gin-mongo URL Shortener sample application:

Let's clone sample app repo:​

git clone https://github.com/keploy/samples-go.git && cd samples-go/gin-mongo
go mod download   # Download dependencies:
go build -o gin-mongo-binary  # Generate binary of the application:

4. Now let's try running keploy:​

Capturing Test Cases:​

sudo keploy record -c "path/to/go/binary"

Running Test Cases:​

sudo keploy test -c "path/to/go/binary" --delay 10

Note: Use the --debug flag to run Keploy in debug mode for detailed logs.

Also you can Test Locally Built Docker Image:​

Build Docker Image:​

Note: Run the below command inside the keploy repository and make sure there is no directory by the name of keploy inside the main keploy repository.

sudo docker image build -t ghcr.io/keploy/keploy:v2-dev .

Remember setting up the Keploy binary. See Setup Keploy using Binary for details.​

Capture Test Cases:​

sudo keploy record -c "docker run -p -p <appPort>:<hostPort>  --name <containerName> --network keploy-network --rm <imageName>"

Running Test Cases:​

sudo keploy test -c "docker run -p -p <appPort>:<hostPort>  --name <containerName> --network keploy-network --rm <imageName>" --delay 10

There you have it! With this guide, you're all set to dive into Keploy development.

Happy testing! 🧪🔍💻

Note :- Run go run github.com/99designs/gqlgen generate --config pkg/graph/gqlgen.yml to generate the graphql server stubs which can be used when working with unit testing libraries like JUnit, PyTest, etc..

Hope this helps you out, if you still have any questions, reach out to us on Slack.

Installing Keploy​

To install the released Keploy binary alongside your local build:


info

Make sure your Linux kernel version is 5.10 or higher.

👉 Choose your preferred method:

1. Install Keploy​

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

2. Once done, you should see something like this:​

   ▓██▓▄
▓▓▓▓██▓█▓▄
 ████████▓▒
      ▀▓▓███▄      ▄▄   ▄               ▌
     ▄▌▌▓▓████▄    ██ ▓█▀  ▄▌▀▄  ▓▓▌▄   ▓█  ▄▌▓▓▌▄ ▌▌   ▓
   ▓█████████▌▓▓   ██▓█▄  ▓█▄▓▓ ▐█▌  ██ ▓█  █▌  ██  █▌ █▓
  ▓▓▓▓▀▀▀▀▓▓▓▓▓▓▌  ██  █▓  ▓▌▄▄ ▐█▓▄▓█▀ █▓█ ▀█▄▄█▀   █▓█
   ▓▌                           ▐█▌                   █▌
    ▓

Available Commands:
  example           Example to record and test via keploy
  config --generate generate the keploy configuration file
  record            record the keploy testcases from the API calls
  test              run the recorded testcases and execute assertions
  update            Update Keploy

Flags:
      --debug     Run in debug mode
  -h, --help      help for keploy
  -v, --version   version for keploy

Use "keploy [command] --help" for more information about a command.

🎉 You have successfully installed Keploy on Linux.

🎬 Start Capturing Test Cases


Record the test cases

keploy record -c "go run main.go"

Run the test cases

keploy test -c "go run main.go" --delay 10

📖 What’s Next?

Now, take it further by following the Quickstart Guide and see Keploy in action with your app.