testcontainers-rs

Decide how to handle files based on your testing requirements:

Mixing these approaches allows you to keep tests hermetic while still being able to inspect outputs locally.

Testcontainers for Rust uses wait strategy to ensure a container has reached a specific state (e.g., a service is listening on a port or a specific log message appears) before your tests proceed.

Strategies are defined using the WaitFor enum. You can apply a strategy to a GenericImage using the with_wait_for method.

// Example of applying a wait strategy to a GenericImage
let image = GenericImage::from_image("postgres:latest")
    .with_wait_for(WaitFor::Http { 
        // ... configuration for HttpWaitStrategy
    });

If you are implementing your own Image trait, you can define commands that run automatically during the container lifecycle using two methods:

1. exec_before_ready: Executes commands after the container has started, but before the Image::ready_conditions are awaited.
2. exec_after_start: Executes commands only after the container is started and ready.

If you need to specify a non-default Docker host, testcontainers-rs resolves the host in this specific order:

1. The tc.host property defined in the ~/.testcontainers.properties file.
2. The DOCKER_HOST environment variable.
3. The docker.host property defined in the ~/.testcontainers.properties file.
4. The default Docker socket (fallback).

Testcontainers for Rust allows you to run multi-container applications defined in Docker Compose files. This is useful for testing interconnected services.

Note: Docker Compose support is currently only available for async runtimes.

Key lifecycle concepts:

• Startup: Use DockerCompose::up().await? to start the stack. This method uses Docker Compose's --wait flag, meaning it will wait for services to pass their healthchecks before returning.
• Cleanup: By default, the stack is automatically cleaned up when the DockerCompose instance is dropped. You can also call compose.down().await? for explicit teardown.
• Isolation: Each test gets a unique project name (UUID) automatically to prevent conflicts during parallel execution. You can override this with .with_project_name("name").

The Containerised Client runs docker compose inside a container. This is ideal for CI/CD environments where a local Docker CLI might not be available, ensuring a consistent Compose version.

// Basic usage
let mut compose = DockerCompose::with_containerised_client(&["docker-compose.yml"]).await;
compose.up().await?;

// Using options to set a project directory (required if using relative paths for bind mounts)
use testcontainers::compose::{ContainerisedComposeOptions, DockerCompose};

let options = ContainerisedComposeOptions::new(&["/home/me/app/docker-compose.yml"])
    .with_project_directory("/home/me/app");

let mut compose = DockerCompose::with_containerised_client(options).await?;
compose.up().await?;

The Local Client is the default mode. It uses the docker compose CLI installed on your local machine.

Requirements:

• Docker CLI with the Compose plugin must be installed locally.
• Compose files must exist on the local filesystem.

use testcontainers::compose::DockerCompose;

let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
compose.up().await?;

The most common way to run commands within an already running container is to use the .exec() method available on ContainerAsync or Container. This method requires an ExecCommand struct and returns an ExecResult (for async) or SyncExecResult (for the blocking feature).

let result = container.exec(command).await?;
let exit_code = result.exit_code().await?;
let stdout = result.stdout_to_vec().await?;
let stderr = result.stderr_to_vec().await?;