Docker Compose quickstart: run tests without the services in your compose file
In this quickstart, your tests need a PostgreSQL database and a Redis cache, and Docker Compose starts both. You record the tests' calls to them once, with the compose stack up. Then you stop the stack and run the same tests, and they still pass. Your CI job doesn't need to start the services any more.
You don't write any mock code, and the tests don't change. You don't need a Keploy account either: the recording stays in your repository.
Every output on this page comes from a real run of Keploy 3.9.4 on Linux. Some
of Keploy's log lines are left out, long lines are trimmed (…), and timestamps
are removed.
Before you begin
You need:
-
Linux. Keploy's agent runs as root, so Keploy may ask for your
sudopassword. -
Docker with the Compose plugin (
docker compose), which your user can run withoutsudo. -
Python 3.10 or newer, with its
venvmodule. On Debian and Ubuntu, install it withsudo apt install python3-venv. -
Ports 5432 and 6379 free. Stop a local PostgreSQL or Redis first.
-
Keploy. To install it, run:
source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')"For other ways to install it, see Installation. The install script installs Keploy Enterprise, which records and mocks Redis. The open-source build (installed with
--oss) passes Redis calls through to the real Redis instead, so with it, Redis must be up for the replay too.
Step 1: Create the sample app
-
Create a folder with a
dbfolder in it, and a git repository:mkdir -p shop/db && cd shop && git init -
Save this as
compose.yaml. It starts PostgreSQL and Redis, and publishes their ports on your machine:services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
volumes:
- ./db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
healthcheck:
test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "postgres"]
interval: 1s
retries: 30
cache:
image: redis:7
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 1s
retries: 30 -
Save this as
db/init.sql. PostgreSQL runs it when the database is first created:CREATE TABLE products (id int PRIMARY KEY, name text NOT NULL, price_cents int NOT NULL);
INSERT INTO products VALUES (1, 'Keyboard', 4999), (2, 'Mouse', 1999); -
Save this as
shop.py. It's your app: it reads products from PostgreSQL and keeps each user's cart in Redis:import psycopg
import redis
DB_URL = "postgresql://postgres:postgres@127.0.0.1:5432/postgres"
cache = redis.Redis(host="127.0.0.1", port=6379)
def product(product_id):
with psycopg.connect(DB_URL) as conn:
name, price_cents = conn.execute(
"SELECT name, price_cents FROM products WHERE id = %s", (product_id,)
).fetchone()
return {"name": name, "price_cents": price_cents}
def add_to_cart(user, product_id, quantity):
cache.hset(f"cart:{user}", str(product_id), quantity)
def clear_cart(user):
cache.delete(f"cart:{user}")
def cart_total(user):
items = cache.hgetall(f"cart:{user}")
return sum(
product(int(pid))["price_cents"] * int(quantity)
for pid, quantity in items.items()
) -
Save this as
test_shop.py. These are your tests:import shop
def test_product():
assert shop.product(1) == {"name": "Keyboard", "price_cents": 4999}
def test_cart_total():
shop.clear_cart("ada")
shop.add_to_cart("ada", 1, 2)
shop.add_to_cart("ada", 2, 1)
assert shop.cart_total("ada") == 11997 -
Create a virtual environment, keep it and Python's caches out of git, and install pytest and the PostgreSQL and Redis clients:
python3 -m venv .venv
printf '.venv/\n__pycache__/\n.pytest_cache/\n' > .gitignore
source .venv/bin/activate
pip install --quiet pytest "psycopg[binary]" redis
Step 2: Run the tests against the compose stack
-
Start PostgreSQL and Redis. The first time, Compose downloads their images.
--waitwaits until both services pass their health checks:docker compose up -d --wait -
Check that both services are up and healthy:
docker compose psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
shop-cache-1 redis:7 "docker-entrypoint.s…" cache 2 seconds ago Up 1 second (healthy) 0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp
shop-db-1 postgres:16 "docker-entrypoint.s…" db 2 seconds ago Up 1 second (healthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp -
Run the tests:
python3 -m pytest -q.. [100%]
2 passed in 0.12s
Step 3: Record the calls
Run the same test command under keploy mock record:
keploy mock record --local -c "python3 -m pytest -q"
🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "default", "program": "python3", "args": 3}
🐰 Keploy: INFO Starting Application : {"program": "python3", "args": 3}
.. [100%]
2 passed in 0.13s
🐰 Keploy: INFO recorded mocks {"mocks": 23, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"}
--local keeps the recording in your repository, so you don't need a Keploy
account for this quickstart. Without --local, Keploy asks you to sign in
first.
Keploy recorded the tests' calls to both services in
keploy/default/mocks.yaml. Count them by kind:
grep '^kind:' keploy/default/mocks.yaml | sort | uniq -c
15 kind: PostgresV3
8 kind: Redis
Here is one Redis call, trimmed:
kind: Redis
name: mock-10
spec:
metadata:
connID: "2"
destAddr: 127.0.0.1:6379
RequestBin:
- origin: client
message:
- type: string
data: "*4\r\n$4\r\nHSET\r\n$8\r\ncart:ada\r\n$1\r\n1\r\n$1\r\n2\r\n"
ResponseBin:
- origin: server
message:
- type: string
data: ":1\r\n"
The request is HSET cart:ada 1 2 in Redis's wire format, and the answer is
1. The PostgreSQL mocks hold the connection set-up, and each SELECT with
the rows it returned.
Step 4: Replay with the compose stack down
-
Stop the compose stack, and remove its containers and the database's data:
docker compose down -v -
Run the tests on their own. They fail, because nothing answers:
python3 -m pytest -q…
E redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused.
…
=========================== short test summary info ============================
FAILED test_shop.py::test_product - psycopg.OperationalError: connection fail...
FAILED test_shop.py::test_cart_total - redis.exceptions.ConnectionError: Erro...
2 failed in 2.66s -
Run them under
keploy mock replay:keploy mock replay --local -c "python3 -m pytest -q"🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "python3", "args": 3, "on-miss": "fail"}
🐰 Keploy: INFO Starting Application : {"program": "python3", "args": 3}
.. [100%]
2 passed in 0.10s
🐰 Keploy: INFO mock replay summary {"loaded": 23, "consumed": 11, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 11}
The tests pass with no PostgreSQL or Redis running. The summary shows no missed call: Keploy answered every call from the recording.
Step 5: Commit the recording
Commit keploy.yml and the keploy/ folder with your code:
git add . && git status --short
A .gitignore
A compose.yaml
A db/init.sql
A keploy.yml
A keploy/.gitignore
A keploy/default/last-record.yaml
A keploy/default/mocks.yaml
A shop.py
A test_shop.py
keploy/default/ holds the recording (mocks.yaml) and the record command
(last-record.yaml). The other files in keploy/default/, such as
last-replay.yaml, are run files from this machine's last replay:
keploy/.gitignore keeps them out of git, so git add . skips them.
Commit what git add staged:
git commit -m "Add shop tests and their Keploy recording"
Now anyone can clone the project, create its virtual environment and install
its packages (python3 -m venv .venv, source .venv/bin/activate and
pip install pytest "psycopg[binary]" redis), and run
keploy mock replay --local -c "python3 -m pytest -q" with the compose stack
down. CI can too.
Clean up
Step 4 stopped the compose stack. Delete the shop folder when you no longer
need it.
Next steps
- Python quickstart: the same loop with an HTTP API,
and
--on-miss recordto add a new call. - Go quickstart: a sample with PostgreSQL and an HTTP API, and a check of each test on its own.
- keploy.yml and keploy.lock: what to commit, and how the lock pins your recordings.
- Run the replay in CI, and share recordings with your team.