Testcontainers for Rust

https://rust.testcontainers.org/
Admin
Testcontainers for Rust is a library that simplifies creating and managing container-based...
Tokens:11,313
Snippets:139
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Serve Docs Locally

Source: https://rust.testcontainers.org/contributing_docs

Run this command from the `testcontainers-rs` root directory to install dependencies and start a local, auto-updating MkDocs server for previewing documentation changes.

```bash
pip3 install -r requirements.txt && ./tc-venv/bin/mkdocs serve
```

--------------------------------

### Synchronous API Example

Source: https://rust.testcontainers.org/features/building_images

Demonstrates building and starting a Docker image using the synchronous API. Requires the 'blocking' feature to be enabled.

```rust
use testcontainers::
    core::BuildImageOptions,
    runners::{SyncBuilder, SyncRunner},
    GenericBuildableImage,
};

#[test]
fn test_sync_build() -> Result<(), Box<dyn std::error::Error>> {
    let image = GenericBuildableImage::new("my-app", "latest")
        .with_dockerfile_string("FROM alpine:latest")
        .build_image()?;

    let container = image.start()?;
    Ok(())
}
```

```rust
use testcontainers::
    core::BuildImageOptions,
    runners::{SyncBuilder, SyncRunner},
    GenericBuildableImage,
};

#[test]
fn test_sync_build_with_options() -> Result<(), Box<dyn std::error::Error>> {
    let image = GenericBuildableImage::new("my-app", "latest")
        .with_dockerfile_string("FROM alpine:latest\nARG VERSION")
        .build_image_with(
            BuildImageOptions::new()
                .with_skip_if_exists(true)
                .with_build_arg("VERSION", "1.0.0")
        )?;

    let container = image.start()?;
    Ok(())
}
```

--------------------------------

### Create and start a generic container

Source: https://rust.testcontainers.org/features/creating_container

Demonstrates building a container request using GenericImage and starting it asynchronously.

```rust
use testcontainers::{
    core::{IntoContainerPort, WaitFor},
    runners::AsyncRunner,
    GenericImage, ImageExt,
};

let _container = GenericImage::new("redis", "7.2.4")
    .with_exposed_port(6379.tcp())
    .with_env_var("DEBUG", "1")
    .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
    .start()
    .await
    .unwrap();
```

--------------------------------

### Enable and start Podman socket

Source: https://rust.testcontainers.org/features/configuration

Commands to enable and start the Podman socket, followed by setting the DOCKER_HOST environment variable for compatibility.

```bash
systemctl --user enable podman.socket
systemctl --user start podman.socket
systemctl --user status podman.socket

export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
```

--------------------------------

### Use Postgres Module with SyncRunner

Source: https://rust.testcontainers.org/quickstart/community_modules

Example of starting a PostgreSQL container using the `postgres` module and `SyncRunner`. Ensure `blocking` and `postgres` features are enabled for `testcontainers-modules`.

```rust
use testcontainers_modules::{postgres, testcontainers::runners::SyncRunner};

#[test]
fn test_with_postgres() {
    let container = postgres::Postgres::default().start().unwrap();
    let host_port = container.get_host_port_ipv4(5432).unwrap();
    let connection_string = &format!(
        "postgres://postgres:postgres@127.0.0.1:{host_port}/postgres",
    );
}
```

--------------------------------

### Building from a Complex Dockerfile

Source: https://rust.testcontainers.org/features/building_images

Example of building a Docker image from a multi-stage Dockerfile, copying local files into the build context.

```rust
let dockerfile = r#" 
FROM rust:1.75 as builder
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/myapp /usr/local/bin/
CMD ["/usr/local/bin/myapp"]
"#;

let image = GenericBuildableImage::new("my-rust-app", "latest")
    .with_dockerfile_string(dockerfile)
    .with_file("./Cargo.toml", "./Cargo.toml")
    .with_file("./Cargo.lock", "./Cargo.lock")
    .with_file("./src", "./src")
    .build_image()
    .await?;
```

--------------------------------

### Sample Docker Compose File for Testing

Source: https://rust.testcontainers.org/features/docker_compose

An example `docker-compose.yml` file demonstrating service definitions for a database (Postgres), cache (Redis), and a web application, including environment variable usage and port mappings.

```yaml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: test
    ports:
      - "5432"

  redis:
    image: redis:7-alpine
    command: redis-server --maxmemory ${REDIS_MAXMEMORY:-128mb}
    ports:
      - "6379"

  web:
    image: my-web-app:latest
    environment:
      DATABASE_URL: postgres://postgres:${POSTGRES_PASSWORD}@db:5432/test
      REDIS_URL: redis://redis:6379
    ports:
      - "8080"
    depends_on:
      - db
      - redis

```

--------------------------------

### Minimal Redis Test with Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

A minimal example demonstrating how to spin up a Redis service using a Docker Compose file and interact with it.

```rust
use testcontainers::compose::DockerCompose;

#[tokio::test]
async fn test_redis() -> Result<(), Box<dyn std::error::Error>> {
    let mut compose = DockerCompose::with_local_client(&["tests/docker-compose.yml"]);
    compose.up().await?;

    let redis = compose.service("redis").expect("redis service");
    let port = redis.get_host_port_ipv4(6379).await?;

    // Use redis at localhost:{port}
    let client = redis::Client::open(format!("redis://localhost:{}", port))?;
    let mut con = client.get_connection()?;
    redis::cmd("PING").query::<String>(&mut con)?;

    Ok(())
}

```

--------------------------------

### Basic Docker Compose Usage

Source: https://rust.testcontainers.org/features/docker_compose

Starts services defined in a compose file and accesses a web service by name.

```rust
use testcontainers::compose::DockerCompose;

#[tokio::test]
async fn test_with_compose() -> Result<(), Box<dyn std::error::Error>> {
    let mut compose = DockerCompose::with_local_client(&["tests/docker-compose.yml"]);

    compose.up().await?;

    // Access service by name
    let web = compose.service("web").expect("web service");
    let port = web.get_host_port_ipv4(8080).await?;

    let response = reqwest::get(format!("http://localhost:{}", port)).await?;
    assert!(response.status().is_success());

    Ok(())
    // Automatic cleanup on drop
}

```

--------------------------------

### Complete Integration Test with Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

An end-to-end example demonstrating setting up a multi-service environment (Postgres, Redis, Web App) using Docker Compose, interacting with services, and performing assertions. Includes automatic cleanup.

```rust
use testcontainers::
    compose::DockerCompose,
    core::IntoContainerPort,
;

#[tokio::test]
async fn integration_test_with_compose() -> Result<(), Box<dyn std::error::Error>> {
    let mut compose = DockerCompose::with_local_client(&[
        "tests/docker-compose.yml",
    ])
    .with_env("POSTGRES_PASSWORD", "test-password")
    .with_env("REDIS_MAXMEMORY", "256mb");

    compose.up().await?;

    // List all running services
    println!("Running services: {:?}", compose.services());

    // Access database
    let db_port = compose.get_host_port_ipv4("db", 5432).await?;
    let db_url = format!("postgres://postgres:test-password@localhost:{}/test", db_port);
    let db_pool = sqlx::PgPool::connect(&db_url).await?;

    // Run migrations or setup
    sqlx::query("CREATE TABLE IF NOT EXISTS users (id INT PRIMARY KEY)")
        .execute(&db_pool)
        .await?;

    // Access Redis
    let redis_port = compose.get_host_port_ipv4("redis", 6379).await?;
    let redis_client = redis::Client::open(format!("redis://localhost:{}", redis_port))?;
    let mut con = redis_client.get_connection()?;
    redis::cmd("SET").arg("test-key").arg("test-value").query::<()>(&mut con)?;

    // Access web service
    let web_port = compose.get_host_port_ipv4("web", 8080).await?;
    let response = reqwest::get(format!("http://localhost:{}/health", web_port))
        .await?;
        .text()
        .await?;

    assert_eq!(response, "OK");

    Ok(())
    // Automatic cleanup: containers, networks, and volumes are removed
}

```

--------------------------------

### Local Client Mode for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Initializes Docker Compose using the locally installed Docker CLI. Requires Docker CLI with Compose plugin installed and compose files on the filesystem.

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

```

--------------------------------

### Build Docker Image with Build Arguments

Source: https://rust.testcontainers.org/features/building_images

Pass build-time variables to the Dockerfile using `with_build_arg` for `ARG` instructions. This example sets `VERSION` and `BUILD_DATE`.

```rust
let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile_string(r#"
        FROM alpine:latest
        ARG VERSION
        ARG BUILD_DATE
        RUN echo "Building version ${VERSION} on ${BUILD_DATE}"
    "#)
    .build_image_with(
        BuildImageOptions::new()
            .with_build_arg("VERSION", "1.0.0")
            .with_build_arg("BUILD_DATE", "2024-10-25")
    )
    .await?;
```

--------------------------------

### Listing All Services in Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Iterates through all services defined in the Docker Compose setup and prints their names.

```rust
compose.up().await?;

for service_name in compose.services() {
    println!("Service: {}", service_name);
}

```

--------------------------------

### Docker Info Command

Source: https://rust.testcontainers.org/features/building_images

A command-line utility to display information about the Docker installation, useful for troubleshooting.

```bash
docker info
```

--------------------------------

### Build a Simple Docker Image from a Dockerfile String

Source: https://rust.testcontainers.org/features/building_images

Use `GenericBuildableImage` to define an image built from a Dockerfile string. This example demonstrates creating a custom image with an entrypoint script and copying it into the image.

```rust
use testcontainers::
    core::WaitFor,
    runners::AsyncRunner,
    GenericBuildableImage;

#[tokio::test]
async fn test_custom_image() -> Result<(), Box<dyn std::error::Error>> {
    let image = GenericBuildableImage::new("my-test-app", "latest")
        .with_dockerfile_string(r#"
            FROM alpine:latest
            COPY --chmod=0755 app.sh /usr/local/bin/app
            ENTRYPOINT ["/usr/local/bin/app"]
        "#)
        .with_data(
            r#"#!/bin/sh
echo "Hello from custom image!"
"#,
            "./app.sh",
        )
        .build_image()
        .await?;

    let container = image
        .with_wait_for(WaitFor::message_on_stdout("Hello from custom image!"))
        .start()
        .await?;

    Ok(())

}
```

--------------------------------

### Install Testcontainers dependencies

Source: https://rust.testcontainers.org/quickstart/testcontainers

Add the necessary crate to your project based on whether you are using async or blocking test environments.

```shell
cargo add testcontainers
```

```shell
cargo add testcontainers --features blocking
```

--------------------------------

### Accessing Ports, Logs, and Executing Commands

Source: https://rust.testcontainers.org/features/docker_compose

Shows how to get mapped ports (IPv4 and IPv6), stream logs (stdout and stderr), and execute commands within a service container.

```rust
compose.up().await?;

let redis = compose.service("redis").expect("redis service");

// Get mapped ports
let port = redis.get_host_port_ipv4(6379).await?;
let ipv6_port = redis.get_host_port_ipv6(6379).await?;

// Stream logs
let stdout = redis.stdout(true);
let stderr = redis.stderr(false);

// Execute commands
let result = redis.exec(ExecCommand::new(["redis-cli", "PING"])).await?;

// Get container info
let container_id = redis.id();
let host = redis.get_host().await?;

```

--------------------------------

### Spin up a Redis container

Source: https://rust.testcontainers.org/quickstart/testcontainers

Use GenericImage to define and start a Redis container with specific port exposure and readiness checks.

```rust
use testcontainers::{
    core::{IntoContainerPort, WaitFor},
    runners::AsyncRunner,
    GenericImage,
};

#[tokio::test]
async fn test_redis() {
    let _container = GenericImage::new("redis", "7.2.4")
        .with_exposed_port(6379.tcp())
        .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
        .start()
        .await
        .unwrap();
}
```

--------------------------------

### Execute Command and Get Results

Source: https://rust.testcontainers.org/features/exec_commands

Execute a command on a container using `container.exec(command).await?`. Retrieve the exit code, stdout, and stderr from the `ExecResult`.

```rust
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?;
```

--------------------------------

### Configure Build and Pull Options for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Specify whether to build images defined in the compose file or pull the latest images before starting the stack. Both `with_build` and `with_pull` are boolean flags.

```rust
let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
    .with_build(true)   // Build images defined in compose file
    .with_pull(true);   // Pull latest images before starting

compose.up().await?;
```

--------------------------------

### Containerised Client Mode for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Runs Docker Compose inside a container, eliminating the need for a local Docker CLI installation. This ensures consistent compose versions across environments and is useful for CI/CD.

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

```

--------------------------------

### Using Build Arguments for Flexibility

Source: https://rust.testcontainers.org/features/building_images

Demonstrates how to make test images configurable by using build arguments in the Dockerfile.

```rust
fn build_test_image(version: &str) -> GenericBuildableImage {
    GenericBuildableImage::new("my-app", version)
        .with_dockerfile_string("FROM alpine:latest\nARG APP_VERSION\nENV VERSION=$APP_VERSION")
        .build_image_with(
            BuildImageOptions::new()
                .with_build_arg("APP_VERSION", version)
        )
}
```

--------------------------------

### Mounting host directories

Source: https://rust.testcontainers.org/features/files

Use Mount helpers to bind host directories or create tmpfs mounts for efficient read/write access.

```rust
// Example: mounting a host directory for read/write access
use std::path::Path;
use testcontainers::core::{mounts::Mount, AccessMode, MountType};

let host_data = Path::new("/var/tmp/integration-data");
let mount = Mount::bind(host_data, "/workspace")
    .with_mode(AccessMode::ReadWrite)
    .with_type(MountType::Bind);

let image = GenericImage::new("python", "3.13")
    .with_mount(mount)
    .with_cmd(["python", "/workspace/run.py"]);
```

--------------------------------

### Copying files into containers before startup

Source: https://rust.testcontainers.org/features/files

Use with_copy_to to stage files or directories from raw bytes or host paths into the container filesystem.

```rust
// Example: copying inline bytes and directories into a container
use testcontainers::{GenericImage, WaitFor};

let project_assets = std::path::Path::new("tests/fixtures/assets");
let image = GenericImage::new("alpine", "latest")
    .with_wait_for(WaitFor::seconds(1))
    .with_copy_to("/opt/app/config.yaml", br#"mode = "test""#.to_vec())
    .with_copy_to("/opt/app/assets", project_assets);
```

--------------------------------

### Building Multiple Variants

Source: https://rust.testcontainers.org/features/building_images

Shows how to build multiple Docker image variants with different configurations, such as ports, using build arguments.

```rust
async fn build_variant(variant: &str, port: u16) -> Result<GenericImage, Box<dyn std::error::Error>> {
    GenericBuildableImage::new("my-app", variant)
        .with_dockerfile_string(format!(r#" 
            FROM alpine:latest
            ARG PORT
            ENV APP_PORT=$PORT
            CMD ["sh", "-c", "echo 'Running on port $APP_PORT' && sleep infinity"]
        "#))
        .build_image_with(
            BuildImageOptions::new()
                .with_build_arg("PORT", port.to_string())
                .with_skip_if_exists(true)
        )
        .await
}

#[tokio::test]
async fn test_multiple_variants() -> Result<(), Box<dyn std::error::Error>> {
    let image1 = build_variant("dev", 8080).await?;
    let image2 = build_variant("staging", 8081).await?;

    // Use images in tests...
    Ok(())
}
```

--------------------------------

### Create ExecCommand with Conditions

Source: https://rust.testcontainers.org/features/exec_commands

Use `ExecCommand::new` to define the command and arguments. Chain `with_container_ready_conditions` and `with_cmd_ready_condition` to specify when the command should be considered ready.

```rust
let command = ExecCommand::new(vec!["echo", "Hello, World!"])
    .with_container_ready_conditions(vec![/* conditions */])
    .with_cmd_ready_condition(CmdWaitFor::message_on_stdout("Hello, World!"));
```

--------------------------------

### Update startup timeout for containers

Source: https://rust.testcontainers.org/features/wait_strategies

If the default 60-second startup timeout is insufficient, use `ImageExt::with_startup_timeout` to specify a custom duration. This is useful for containers that take longer to initialize.

```rust
let image = GenericImage::new("my_image:latest")
    .with_startup_timeout(Duration::from_secs(120));
```

--------------------------------

### Dockerfile ARG Instruction Placement

Source: https://rust.testcontainers.org/features/building_images

Illustrates the correct placement of `ARG` instructions in a Dockerfile, which must appear before they are used.

```dockerfile
# Correct
ARG VERSION
ENV APP_VERSION=$VERSION

# Incorrect - ARG comes after usage
ENV APP_VERSION=$VERSION
ARG VERSION
```

--------------------------------

### Build Docker Image with Build Arguments from HashMap

Source: https://rust.testcontainers.org/features/building_images

Provide multiple build arguments to the Dockerfile by passing a `HashMap` to `with_build_args` within `BuildImageOptions`.

```rust
use std::collections::HashMap;

let mut args = HashMap::new();
args.insert("VERSION".to_string(), "1.0.0".to_string());
args.insert("ENVIRONMENT".to_string(), "test".to_string());

let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile_string("FROM alpine:latest\nARG VERSION\nARG ENVIRONMENT")
    .build_image_with(
        BuildImageOptions::new()
            .with_build_args(args)
    )
    .await?;
```

--------------------------------

### Add Files to Docker Build Context from Filesystem

Source: https://rust.testcontainers.org/features/building_images

Specify a Dockerfile from the filesystem and include additional files from your local system into the build context using `with_file`.

```rust
let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile("./path/to/Dockerfile")
    .with_file("./target/release/myapp", "./myapp")
    .build_image()
    .await?;
```

--------------------------------

### Build Docker Image with Skip if Exists Option

Source: https://rust.testcontainers.org/features/building_images

Use `BuildImageOptions` to configure the build process. `with_skip_if_exists(true)` prevents rebuilding the image if an image with the same descriptor already exists. This is thread-safe.

```rust
use testcontainers::core::BuildImageOptions;

let image = GenericBuildableImage::new("my-app", "v1.0")
    .with_dockerfile_string("FROM alpine:latest")
    .build_image_with(
        BuildImageOptions::new()
            .with_skip_if_exists(true)
    )
    .await?;
```

--------------------------------

### Combine Docker Build Options

Source: https://rust.testcontainers.org/features/building_images

Chain multiple build options together within `BuildImageOptions` for comprehensive control over the Docker image build process.

```rust
let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile_string("FROM alpine:latest\nARG VERSION")
    .build_image_with(
        BuildImageOptions::new()
            .with_skip_if_exists(true)
            .with_no_cache(false)
            .with_build_arg("VERSION", "1.0.0")
    )
    .await?;
```

--------------------------------

### Accessing Service Container API

Source: https://rust.testcontainers.org/features/docker_compose

Demonstrates accessing a service container after calling up() to use its full API, including ports, logs, and executing commands.

```rust
compose.up().await?;

let redis = compose.service("redis").expect("redis service exists");

// Full container API available
let port = redis.get_host_port_ipv4(6379).await?;
let logs = redis.stdout(true);
redis.exec(ExecCommand::new(["redis-cli", "PING"])).await?;

```

--------------------------------

### Configure Docker Compose Cleanup Options

Source: https://rust.testcontainers.org/features/docker_compose

Configure whether volumes and images should be removed during cleanup. `with_remove_volumes` defaults to `true`, while `with_remove_images` defaults to `false`.

```rust
let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);

// Remove volumes on cleanup (default: true)
compose.with_remove_volumes(true);

// Remove images on cleanup (default: false)
compose.with_remove_images(false);

compose.up().await?;
```

--------------------------------

### Configure Resource Cleanup

Source: https://rust.testcontainers.org/features/docker_compose

Adjust volume and image removal behavior during container cleanup.

```rust
// Keep volumes for debugging or to reuse data across test runs
compose.with_remove_volumes(false);

// Remove images to save disk space
compose.with_remove_images(true);
```

--------------------------------

### Connect to a containerized Redis instance

Source: https://rust.testcontainers.org/quickstart/testcontainers

Retrieve the dynamic host and port mapping from a running container to configure a client connection.

```rust
use redis::Client;
use testcontainers::{core::{IntoContainerPort, WaitFor}, runners::AsyncRunner, GenericImage};

#[tokio::test]
async fn test_redis() -> Result<(), Box<dyn std::error::Error + 'static>> {
    let container = GenericImage::new("redis", "7.2.4")
        .with_exposed_port(6379.tcp())
        .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
        .start()?
        .await;
    let host = container.get_host()?;
    let host_port = container.get_host_port_ipv4(REDIS_PORT)?;

    let url = format!("redis://{host}:{host_port}");
    let client = redis::Client::open(url.as_ref())?;
    // do something with the client
}
```

--------------------------------

### Docker Compose File for Redis

Source: https://rust.testcontainers.org/features/docker_compose

A sample Docker Compose file defining a Redis service.

```yaml
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379"

```

--------------------------------

### Auto Client Mode for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Initializes Docker Compose by first attempting to use the local Docker CLI and falling back to the containerised client if the local CLI is unavailable.

```rust
use testcontainers::compose::{AutoComposeOptions, DockerCompose};

let options = AutoComposeOptions::new(&["docker-compose.yml"]);

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

```

--------------------------------

### Containerised Client with Project Directory Option

Source: https://rust.testcontainers.org/features/docker_compose

Configures the containerised Docker Compose client, specifying a project directory to ensure correct resolution of relative paths in bind mounts.

```rust
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?;

```

--------------------------------

### Use Multiple Docker Compose Files

Source: https://rust.testcontainers.org/features/docker_compose

Combine multiple compose files, such as a base file and an override file, by passing an array of file paths to `DockerCompose::with_local_client`.

```rust
let mut compose = DockerCompose::with_local_client(&[
    "docker-compose.yml",
    "docker-compose.test.yml",
]);

compose.up().await?;
```

--------------------------------

### Leveraging skip_if_exists for Faster Tests

Source: https://rust.testcontainers.org/features/building_images

Shows how to use the `skip_if_exists` option to avoid rebuilding images that haven't changed, speeding up test execution.

```rust
let image = GenericBuildableImage::new("my-stable-app", "v1.0")
    .with_dockerfile_string("FROM alpine:latest\nRUN apk add curl")
    .build_image_with(
        BuildImageOptions::new()
            .with_skip_if_exists(true)
    )
    .await?;
```

--------------------------------

### Add Files to Docker Build Context with Inline Data

Source: https://rust.testcontainers.org/features/building_images

Provide inline data as a string and specify its destination path within the Docker build context using `with_data`.

```rust
let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile_string("FROM alpine:latest\nCOPY config.json /config.json")
    .with_data(r#"{"port": 8080}"#, "./config.json")
    .build_image()
    .await?;
```

--------------------------------

### Copying files from a running container

Source: https://rust.testcontainers.org/features/files

Use copy_file_from to retrieve files generated inside a container to the host filesystem.

```rust
// Example: copying a file from a running container to the host
use tempfile::tempdir;
use testcontainers::{GenericImage, WaitFor};

#[tokio::test]
async fn copy_example() -> anyhow::Result<()> {
    let container = GenericImage::new("alpine", "latest")
        .with_cmd(["sh", "-c", "echo '42' > /tmp/result.txt && sleep 10"])
        .with_wait_for(WaitFor::seconds(1))
        .start()
        .await?;

    let destination = tempdir()?.path().join("result.txt");
    container
        .copy_file_from("/tmp/result.txt", destination.as_path())
        .await?;
    assert_eq!(tokio::fs::read_to_string(&destination).await?, "42\n");
    Ok()
}
```

```rust
let mut bytes = Vec::new();
container.copy_file_from("/tmp/result.txt", &mut bytes).await?;
```

--------------------------------

### Descriptive Image Tags

Source: https://rust.testcontainers.org/features/building_images

Illustrates the use of descriptive image names and tags for better organization and to avoid conflicts.

```rust
// Good: specific and descriptive
GenericBuildableImage::new("test-user-service", "integration-v1")
```

```rust
// Avoid: generic names that might conflict
GenericBuildableImage::new("test", "latest")
```

--------------------------------

### Verifying Image Name and Tag

Source: https://rust.testcontainers.org/features/building_images

Emphasizes the importance of matching the image name and tag exactly when referencing a built image.

```rust
let image = GenericBuildableImage::new("my-app", "v1.0")  // Name and tag must match
    .with_dockerfile_string("FROM alpine:latest")
    .build_image()
    .await?;

// The image is now available as "my-app:v1.0"
```

--------------------------------

### Enable Host Port Exposure Feature

Source: https://rust.testcontainers.org/features/networking

Adds the required feature flag to the project dependencies for enabling host-to-container communication.

```bash
cargo add testcontainers --features host-port-exposure
```

--------------------------------

### Define a custom strongly-typed image

Source: https://rust.testcontainers.org/features/creating_container

Shows how to implement the Image trait to create reusable, strongly-typed container definitions.

```rust
use testcontainers::{
    core::{ContainerPort, WaitFor},
    runners::AsyncRunner,
    Image,
};

#[derive(Debug, Clone)]
struct RedisImage {
    ports: [ContainerPort; 1],
}

impl Default for RedisImage {
    fn default() -> Self {
        Self {
            ports: [ContainerPort::Tcp(6379)],
        }
    }
}

impl Image for RedisImage {
    fn name(&self) -> &str {
        "redis"
    }

    fn tag(&self) -> &str {
        "7.2.4"
    }

    fn ready_conditions(&self) -> Vec<WaitFor> {
        vec![WaitFor::message_on_stdout("Ready to accept connections")]
    }

    fn expose_ports(&self) -> &[ContainerPort] {
        &self.ports
    }
}

let _container = RedisImage::default().start().await.unwrap();
```

--------------------------------

### Expose Container Ports to Host

Source: https://rust.testcontainers.org/features/networking

Uses with_exposed_port to publish a container port to a random free host port, which is then retrieved via get_host_port_ipv4.

```rust
use testcontainers::{
    core::{IntoContainerPort, WaitFor},
    runners::AsyncRunner,
    GenericImage,
};

#[tokio::test]
async fn talks_to_web_service() -> Result<(), Box<dyn std::error::Error>> {
    let container = GenericImage::new("ghcr.io/testcontainers/examples", "web")
        .with_exposed_port(8080.tcp())
        .with_wait_for(WaitFor::message_on_stdout("listening on 0.0.0.0:8080"))
        .start()
        .await?;

    let host = container.get_host()?;
    let port = container.get_host_port_ipv4(8080.tcp())?;

    let body = reqwest::get(format!("http://{host}:{port}/health"))
        .await?
        .text()
        .await?;
    assert_eq!(body, "OK");

    Ok(())
}
```

--------------------------------

### Build Docker Image with No Cache Option

Source: https://rust.testcontainers.org/features/building_images

Force a fresh Docker image build without utilizing Docker's layer cache by setting `with_no_cache(true)` in `BuildImageOptions`.

```rust
let image = GenericBuildableImage::new("my-app", "latest")
    .with_dockerfile_string("FROM alpine:latest\nRUN apk update")
    .build_image_with(
        BuildImageOptions::new()
            .with_no_cache(true)
    )
    .await?;
```

--------------------------------

### Configure wait strategy for GenericImage

Source: https://rust.testcontainers.org/features/wait_strategies

Use the `with_wait_for` method on `GenericImage` to specify a desired wait strategy. This ensures your tests wait for the container to reach a specific state.

```rust
let image = GenericImage::new("my_image:latest")
    .with_wait_for(WaitFor::StdOutMessage(regex::Regex::new("ready").unwrap()));
```

--------------------------------

### Configure Docker Compose Healthcheck

Source: https://rust.testcontainers.org/features/docker_compose

Define a healthcheck in the compose file to enable the --wait functionality in the up() method.

```yaml
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 5s
      timeout: 3s
      retries: 3
    ports:
      - "80"
```

--------------------------------

### Set Environment Variables for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Pass environment variables to your Docker Compose stack using individual `with_env` calls. Ensure the variable names and values are correctly formatted strings.

```rust
use std::collections::HashMap;

let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
    .with_env("DATABASE_URL", "postgres://test:test@db:5432/test")
    .with_env("REDIS_PORT", "6380");

compose.up().await?;
```

```rust
let mut env_vars = HashMap::new();
env_vars.insert("API_KEY".to_string(), "test-key-123".to_string());
env_vars.insert("DEBUG".to_string(), "true".to_string());

let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
    .with_env_vars(env_vars);

compose.up().await?;
```

--------------------------------

### Add Docker Compose Feature Dependency

Source: https://rust.testcontainers.org/features/docker_compose

Include the 'docker-compose' feature in your dev-dependencies to enable Docker Compose support.

```toml
[dev-dependencies]
testcontainers = { version = "x.y.z", features = ["docker-compose"] }

```

--------------------------------

### Overriding file metadata with CopyTargetOptions

Source: https://rust.testcontainers.org/features/files

Use CopyTargetOptions to specify custom file permissions when copying files into a container.

```rust
use testcontainers::{CopyTargetOptions, GenericImage, ImageExt};

let image = GenericImage::new("alpine", "latest")
    .with_copy_to(
        CopyTargetOptions::new("/opt/app/secret.yaml").with_mode(0o600),
        "./fixtures/secret.yaml",
    )
    .with_copy_to(
        CopyTargetOptions::new("/opt/app/blob.bin").with_mode(0o640),
        br"raw bytes".to_vec(),
    );
```

--------------------------------

### Override Redis Module Defaults

Source: https://rust.testcontainers.org/quickstart/community_modules

Customizes a Redis container by specifying a tag and an environment variable for the password using `ImageExt`. This function returns a `ContainerRequest` for a Redis module.

```rust
use testcontainers_modules::{
    redis::Redis,
    testcontainers::{ContainerRequest, ImageExt},
};


/// Create a Redis module with `6.2-alpine` tag and custom password
fn create_redis() -> ContainerRequest<Redis> {
    Redis::default()
        .with_tag("6.2-alpine")
        .with_env_var(("REDIS_PASSWORD", "my_secret_password"))
}
```

--------------------------------

### Disabling Build Cache

Source: https://rust.testcontainers.org/features/building_images

Provides an option to disable the Docker build cache by setting `with_no_cache(true)` in `BuildImageOptions` to resolve 'no active session' errors.

```rust
BuildImageOptions::new().with_no_cache(true)
```

--------------------------------

### Manage Docker Compose Stack Lifecycle

Source: https://rust.testcontainers.org/features/docker_compose

Control the lifecycle of your Docker Compose stack. By default, the stack is automatically cleaned up when the `DockerCompose` object goes out of scope. Explicit teardown using `down()` is also possible.

```rust
// Option 1: Automatic cleanup (default behavior)
{
    let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
    compose.up().await?;
    // Use services...
} // Automatically cleaned up here

// Option 2: Explicit teardown
let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
compose.up().await?;
// Use services...
compose.down().await?; // Explicit cleanup, consumes compose
```

--------------------------------

### Expose Host Ports to Container

Source: https://rust.testcontainers.org/features/networking

Uses with_exposed_host_port to allow a container to reach a service running on the host via the host.testcontainers.internal alias.

```rust
use std::io::Write;
use std::net::TcpListener;
use std::thread;

use testcontainers::{
    core::{ExecCommand, IntoContainerPort},
    runners::AsyncRunner,
    GenericImage,
};

const HOST_ALIAS: &str = "host.testcontainers.internal";

#[tokio::test]
async fn container_reaches_host_service() -> Result<(), Box<dyn std::error::Error>> {
    // Start a temporary HTTP server on the host.
    let listener = TcpListener::bind("127.0.0.1:0")?;
    let host_port = listener.local_addr()?.port();
    thread::spawn(move || {
        if let Ok((mut stream, _)) = listener.accept() {
            let _ = stream.write_all(
                b"HTTP/1.1 200 OK\r\nContent-Length: 15\r\n\r\nhello-from-host",
            );
        }
    });

    let container = GenericImage::new("alpine", "3.19")
        .with_entrypoint("/bin/sh")
        .with_cmd(["-c", "sleep 30"])
        .with_exposed_host_port(host_port)
        .start()
        .await?;

    // Verify that the container can reach the host.
    let mut exec = container
        .exec(ExecCommand::new(vec![
            "wget".into(),
            "-qO-".into(),
            format!("http://{HOST_ALIAS}:{host_port}"),
        ]))
        .await?;
    let output = String::from_utf8(exec.stdout_to_vec().await?)?;
    assert_eq!(output, "hello-from-host");

    Ok(())
}
```

--------------------------------

### Set a Stable Project Name for Docker Compose

Source: https://rust.testcontainers.org/features/docker_compose

Override the default unique project name generation with a stable name using `with_project_name`. This is useful for reusing volumes across test runs.

```rust
let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
    .with_project_name("my-test-stack");


```

--------------------------------

### Apply advanced host configuration modifiers

Source: https://rust.testcontainers.org/features/creating_container

Uses with_host_config_modifier to adjust low-level Docker HostConfig fields not exposed by the standard API.

```rust
use testcontainers::{GenericImage, ImageExt};

let image = GenericImage::new("testcontainers/helloworld", "1.3.0")
    .with_host_config_modifier(|host_config| {
        host_config.cpu_period = Some(100_000);
        host_config.cpu_quota = Some(200_000);
    });
```

--------------------------------

### Re-export of testcontainers

Source: https://rust.testcontainers.org/quickstart/community_modules

Demonstrates that `testcontainers` is a re-exported dependency of `testcontainers-modules`, allowing direct use of its traits.

```rust
use testcontainers_modules::testcontainers::ImageExt;
```
Tokens:
Raw