Getting Started
Get TestMesh running in minutes and execute your first integration test.
TestMesh is a platform for writing and running end-to-end integration tests across HTTP, databases, Kafka, gRPC, and more. Tests are defined in human-readable YAML files called flows.
Before You Start
Docker required
The demo microservices and infrastructure run in Docker. Install Docker Desktop if you haven't already.
Go 1.23+ required
The CLI is written in Go. Required if running from source or installing the CLI binary.
Quickest path: If you just want to evaluate TestMesh, jump to Your First Flow and run the demo services with one command.
Installation
Install the CLI and set up your environment.
Your First Flow
Write and run your first test in under five minutes.
Core Concepts
Understand flows, steps, actions, and the variable system.
Choose Your Setup
With Your Own Infrastructure
If you already have PostgreSQL, Redis, and optionally Kafka running, pull the image and connect:
docker run -d \
--name testmesh \
--network <your-network> \
-p 5016:5016 \
-p 3000:3000 \
-e DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db>?sslmode=disable \
-e REDIS_URL=redis://<host>:6379 \
-e KAFKA_ENABLED=true \
-e KAFKA_BROKERS=<host>:9092 \
ghcr.io/test-mesh/testmesh:latestWithout Existing Infrastructure
Use the bundled Docker Compose file to spin up everything at once:
Download the compose file:
curl -O https://raw.githubusercontent.com/test-mesh/testmesh/main/deploy/docker-compose/docker-compose.ymlStart all services:
docker compose up -dThis starts PostgreSQL, Redis, Kafka, the TestMesh API, and the dashboard.
Verify everything is healthy:
curl http://localhost:5016/healthA successful response looks like {"status":"ok"}. If you see a connection error, wait a few seconds for the containers to finish starting.
Open the dashboard at http://localhost:3000.
Running from source gives you hot-reload for API development and access to the demo microservices.
Clone the repository:
git clone https://github.com/test-mesh/testmesh.git
cd testmeshStart infrastructure (PostgreSQL on 5432, Redis on 6379, Kafka on 9092):
./infra.sh upStart the API server (port 5016) and dashboard (port 3000):
docker-compose -f docker-compose.dev.yml up --buildOptionally, start the demo microservices on ports 5001–5004:
docker-compose -f docker-compose.services.yml up --buildThese four services (user, product, order, notification) are used in the example flows.
Verify the API is healthy:
curl http://localhost:5016/healthExpected response: {"status":"ok"}
Run Your First Test
Once TestMesh is running, execute the bundled example flow from the CLI:
cd cli
go run main.go run ../examples/microservices/e2e-order-flow.yamlYou should see each step execute with a pass/fail result. If all steps pass, you're ready to write your own flows.
The demo microservices must be running for the example order flow to work. Start them with docker-compose -f docker-compose.services.yml up --build.