Crate testcontainers

A library for integration testing against docker containers from within Rust.

This crate is the official Rust language fork of Testcontainers.

Tests should be self-contained and isolated. While this is usually easy for unit-tests, integration-tests typically require a more complex environment. The testcontainers ecosystem facilitates self-contained and isolated integration tests. It allows to easily spin up Docker containers from within your tests and removes them afterwards.

A very typical usecase for testcontainers are integration-tests of persistence layers. These require an actual database to be present. Using testcontainers, your tests can spin up database containers themselves, without the need for any other setup.

Main benefits

• Run integration tests in parallel (because each test sets up its own environment)
• Run integration tests the same way you run unit tests (cargo test and you are fine)

Usage

Unsurprisingly, working with testcontainers is very similar to working with Docker itself.

First you choose a Client. Given a client instance, you can run Images. This gives you back a Container. Containers implement Drop. As soon as they go out of scope, the underlying docker container is removed.

Usage in production code

Although nothing inherently prevents testcontainers from being used in production code, the library itself was not designed with that in mind. For example, many methods will panic if something goes wrong but because the usage is intended to be within tests, this is deemed acceptable.

Ecosystem

The testcontainers ecosystem is split into multiple crates, however, the testcontainers crate itself is a meta-crate, re-exporting the others. Usually, depending on testcontainers should be sufficient for most users needs.

Modules

clients	All available Docker clients.
images	All available Docker images.

Structs

Container	Represents a running docker container.
Logs	Log streams of running container (stdout & stderr).
Ports	The exposed ports of a running container.

Enums

WaitError

Defines error cases when waiting for a message in a stream.

Traits

Docker	Defines the minimum API required for interacting with the Docker daemon.
Image	Represents a docker image.
WaitForMessage	Extension trait for io::Read to wait for a message to appear in the given stream.