macOS Installation

View as Markdown

There are two ways to install Keploy on macOS:

1. Recommended: One-click install.
2. Install with Homebrew.

Natively on macOS, Keploy understands HTTP/HTTPS, MySQL and MongoDB calls; calls to other services — PostgreSQL, Redis, Kafka, gRPC and the like — are captured only as raw bytes and usually don't replay. If your app runs in containers or depends on one of those other services, a manual setup with Docker Desktop or Colima is also available.

Apple Silicon only

Both routes install the native Keploy CLI, which is built for Apple Silicon (arm64) only — the installer stops with a message on an Intel Mac, and the Homebrew formula refuses to install there. The manual Docker Desktop / Colima setup below is driven by that same CLI: it starts your app and Keploy's eBPF agent in containers inside the Linux VM, but the CLI itself runs on your Mac, so that route is Apple Silicon only too. On an Intel Mac, run Keploy with Lima instead.

One-click install Keploy

Run the following command in your terminal:

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

Install with Homebrew

If you prefer Homebrew, install Keploy from the official Keploy tap:

brew install keploy/tap/keploy

Verify the install:

keploy --version

Manual Setup

To record an app that runs in containers, or one whose dependencies Keploy does not understand natively on macOS, run Keploy through either Docker Desktop or Colima.

Using Docker Desktop

Note: To run Keploy on macOS through Docker the version must be 4.25.2 or above.

Creating Docker Volume & Network

We need to create debug volume to run Keploy using Docker-Desktop:

docker volume create --driver local --opt type=debugfs --opt device=debugfs debugfs

We need to create a custom network for Keploy since we are using the Docker, therefore application container would require docker network to act as the bridge between them.

If you're using a docker-compose network, replace keploy-network with your app's docker_compose_network_name below.

docker network create keploy-network

Using Colima

Install Colima

You need to have the latest version of brew installed on your system and then run this command from a terminal:

brew install colima

Start Colima with defaults

colima start

Creating Alias

We need to create a custom network for Keploy since we are using the Docker, therefore application container would require docker network to act as the bridge between them.

If you're using a docker-compose network, replace keploy-network with your app's docker_compose_network_name below.

docker network create keploy-network

Recording Testcases and Data Mocks

Here are few points to consider before recording!

• If you're running via docker compose, ensure to include the <CONTAINER_NAME> under your application service in the docker-compose.yaml file like this .

• Change the network name (--network flag) from keploy-network to your custom network if you changed it above.

• Docker_CMD_to_run_user_container refers to the Docker command for launching the application.

Utilize keploy to capture testcases. Execute the following command within your application's root directory.

keploy record -c "docker run -p <appPort>:<hostPort> --name <containerName> --network keploy-network --rm <applicationImage>" --containerName "<containerName>" --delay 10

Make API Calls using Postman, or cURL commands.

Keploy will capture the API calls you've conducted, generating test suites comprising testcases (KTests) and data mocks (KMocks) in YAML format.

Running Testcases

Now, execute the testcases. Follow these steps in the root directory of your application.

When using docker-compose to start the application, it's important to ensure that the --containerName parameter matches the container name in your docker-compose.yaml file.

keploy test -c "docker run -p <appPort>:<hostPort> --name <containerName> --network keploy-network --rm <applicationImage>" --containerName "<containerName>" --delay 20

Voilà! 🧑🏻‍💻 We have the tests with data mocks running! 🐰🎉

You'll be able to see the test-cases that ran with the results report on the console as well locally in the testReport directory.

1. delay is required while using Test Mode.
2. containerName is optional if you are using Docker run command, as the Container name would be present within the command itself.