Testcontainers for Rust

Testcontainers for Rust is the official Rust fork of the Testcontainers project. It provides a lightweight API for spinning up disposable Docker containers — databases, message brokers, or any Dockerized dependency — directly from your Rust integration tests, and tears them down automatically when the test finishes.

You describe the image you need, wait conditions, exposed ports, and environment, then start it with either an async (Tokio) or blocking runner. A collection of ready-to-use image modules and a generic image builder mean you can test against real services instead of mocks, with reproducible setup on every run.

What You Get

• A generic image builder plus ready-to-use image modules for common services
• Async (Tokio) and blocking runner APIs behind a shared container interface
• Configurable wait strategies (log messages, health checks, ports) before a container is considered ready
• Automatic container cleanup via a watchdog so no resources leak after tests finish
• Fine-grained control over exposed ports, environment variables, networks, and mounts

Common Use Cases

• Running integration tests against a real database (Postgres, Redis, MySQL) instead of mocks
• Testing code that talks to message brokers, object stores, or other Dockerized services
• Providing reproducible, isolated dependencies in CI without shared external infrastructure
• Spinning up docker-compose stacks for multi-service integration scenarios

Under The Hood

Architecture — The crate (in testcontainers/src/) centers on a core::Image trait describing how to build and wait on a container, runners/ implementing async (AsyncRunner) and blocking (SyncRunner) execution over a shared container abstraction, and a watchdog.rs background task that reaps containers even on panic. Docker interaction goes through the bollard client; compose/ adds docker-compose orchestration, images/ provides a GenericImage and module definitions, and buildables/ supports building images on the fly.

Tech Stack — Rust (edition 2021, rust-version 1.88), built on Tokio with bollard for the Docker API, reqwest/http for HTTP wait strategies, russh for SSH-based flows, serde/serde_json/serde_with for config, and thiserror for errors. Optional features gate compose support, blocking runners, and credential handling; distributed as a Cargo workspace with the single testcontainers member.

Code Quality — The code is idiomatic async Rust with clear module separation, typed errors via thiserror, and builder-style ergonomics. The project maintains a documented DESIGN_PRINCIPLES.md, CI workflows, and test images under testimages/, reflecting a mature, well-tested codebase with 30M+ total downloads.

API Design — The fluent ImageExt builder (.with_exposed_port, .with_wait_for, .with_env_var, .start()) makes container setup read almost declaratively, and the parallel async/blocking runner APIs let users pick the model matching their tests with minimal boilerplate — a container is often ready in a handful of chained calls.