A simple, opinionated way to run containers for tests in your Rust project.

Overview

Build status Crates.io Documentation

rustainers

rustainers is a simple, opinionated way to run containers for tests.

TLDR

More information about this crate can be found in the crate documentation.

Or just see example directory.

Differences with testcontainers

This crate is an alternative to the testcontainers-rs crate.

The key differences are

For now, the implementation is based on the CLI command. We may add more runner based on Rust api later.

Run a simple container

You need a Runner to launch an image. You can use the Runner::auto function to detect an available runner, or use the Runner::docker, Runner::podman, Runner::nerdctl functions to choose a specific runner.

Then you need to create a runnable image, see module images to use an existing image, or create your own image.

And you just need to start your image. The running container can provide some methods to help you to use this container, e.g. a connection URL to access your container.

use rustainers::runner::{Runner, RunOption};
use rustainers::images::Postgres;

async fn pg() -> anyhow::Result<()> {
    let runner = Runner::auto()?;
    let image = Postgres::default().with_tag("15.2");
    let container = runner.start(image).await?;

    let url = container.url().await?;
    do_something_with_postgres(url).await?;
    Ok(())
}

async fn do_something_with_postgres(url: String) -> anyhow::Result<()> { 
    Ok(())
}

Livecycle of a container

When you start a runnable image, the runner first check the state of the container. It may already exists, or we may need to create it.

Then, the runner wait until all wait strategies to be reached, for example it can check the health of the container.

And it's returning a container. This container have a reference on the runnable image, this image can provide helper functions to retrieve for example the database URL.

When the container is dropped, by default, it stop the container.

You can opt-in to detach the container to avoid stopping in during the drop.

Using compose

To run containers defined with a docker-compose file, you also need a runner.

Then you can start your containers with compose_start.

use rdkafka::producer::{FutureProducer, FutureRecord};
use rdkafka::ClientConfig;
use tracing::{info, Level};

use rustainers::compose::images::KafkaSchemaRegistry;
use rustainers::runner::Runner;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let runner = Runner::auto()?;
    let image = KafkaSchemaRegistry::build_single_kraft().await?;
    let containers = runner.compose_start(image).await?;
    info!("Now I can use {containers}");
    do_something_with_kafka(&containers).await?;

   Ok(())
}

async fn do_something_with_kafka(image: &KafkaSchemaRegistry) -> anyhow::Result<()> {
    let topic = "plop";
    let broker_address = image.broker_address().await?;
    info!("Using kafka broker: {broker_address}");

    let schema_registry_url = image.schema_registry_endpoint().await?;
    info!("Using schema registry: {schema_registry_url}");

    // ...
    Ok(())
}

Create a custom image

See images module documentation.

Create a custom compose images

See compose::images module documentation.

You might also like...
A very opinionated, zero-configuration shell prompt
A very opinionated, zero-configuration shell prompt

A very opinionated, zero-configuration shell prompt

A lightweight, opinionated CQRS and event sourcing framework targeting serverless architectures.

cqrs A lightweight, opinionated CQRS and event sourcing framework targeting serverless architectures. Command Query Responsibility Segregation (CQRS)

MinMon - an opinionated minimal monitoring and alarming tool

MinMon - an opinionated minimal monitoring and alarming tool (for Linux) This tool is just a single binary and a config file. No database, no GUI, no

A opinionated and fast static analyzer for PHP.
A opinionated and fast static analyzer for PHP.

TLDR; A static analyzer for PHP. It helps you catch common mistakes in your PHP code. These are the current checks implemented. Extending undefined cl

Beautiful, minimal, opinionated CLI prompts inspired by the Clack NPM package
Beautiful, minimal, opinionated CLI prompts inspired by the Clack NPM package

Effortlessly build beautiful command-line apps with Rust 🦀 ✨ Beautiful, minimal, opinionated CLI prompts inspired by the @clack/prompts npm package.

Opinionated, zero-config linter for JavaScript monorepos
Opinionated, zero-config linter for JavaScript monorepos

Sherif: Opinionated, zero-config linter for JavaScript monorepos About Sherif is an opinionated, zero-config linter for JavaScript monorepos. It runs

An ascii webcam in your console, written as a way of learning rust.

asciicam An ascii webcam in your console, written as a way of learning rust. asciicam picture of me holding a basketball usage only linux is supported

The-way - A code snippets manager for your terminal.
The-way - A code snippets manager for your terminal.

The Way A code snippets manager for your terminal. Record and retrieve snippets you use every day, or once in a blue moon, without having to spin up a

Simple, safe way to store and distribute tensors

Safetensors Ruby 🙂 Simple, safe way to store and distribute tensors Supports Torch.rb and Numo Installation Add this line to your application’s Gemfi

Comments
  • Allow creation of Kafka topic

    Allow creation of Kafka topic

    We should be able to create a Kafka topic with the number of partitions and the replication factor.

    Should be added to the ComposeContainers<KafkaSchemaRegistry> and maybe in the ComposeContainers<Redpanda>.

    Must be done without adding a dependency. Try with an exec in the containers or something based on an env. var.

    enhancement good first issue C-compose-images 
    opened by IgorLaborieWefox 0
Owner
wefox
wefox opensource projects
wefox
Black-box integration tests for your REST API using the Rust and its test framework

restest Black-box integration test for REST APIs in Rust. This crate provides the [assert_api] macro that allows to declaratively test, given a certai

IOmentum 10 Nov 23, 2022
The dead easy way to use config files in your rust project

Configr The dead easy way to use config files in your project This will load a config.toml file if it exists, otherwise it will create the needed fold

Carsten Kragelund Jørgensen 4 Jul 1, 2022
Assure that your tests are there, and well written.

cargo-is-tested [ ???? ] El libro contiene instrucciones e información detallada en Español. cargo-is-tested is a way to check which of your items are

Alex ✨ Cosmic Princess ✨ 15 Jan 8, 2023
A simple tui to view & control docker containers

oxker A simple tui to view & control docker containers Built in Rust, making heavy use of tui-rs & Bollard Download & install See releases download &

Jack Wills 119 Dec 28, 2022
Run the right version of python, in the right environment, for your project

rpy Do you deal with lots of virtual python environments? rpy is for you! Before rpy: ~/dev/prj$ env PYTHONPATH=src/py path/to/my/interpreter src/py/m

Aquatic Capital Management 2 Dec 8, 2022
Cedar-agent is the easiest way to deploy and run Cedar

Cedar Agent What is Cedar-Agent? Cedar-Agent is an HTTP server designed to efficiently manage a policy store and a data store. It provides a seamless

Permit.io 30 May 26, 2023
A simple, modern fuzzy finder tool to run examples in a Cargo project.

cargo-rx cargo-rx is a simple, modern Runner for Examples in a Cargo project. This crate provides a single executable: rx. Basically anywhere you woul

Ritvik Nag 14 Dec 2, 2022
Snapshot testing for a herd of CLI tests

trycmd Snapshot testing for a herd of CLI tests trycmd aims to simplify the process for running a large collection of end-to-end CLI test cases, takin

null 57 Jan 3, 2023
A template with cookie cutter CLI, Program and Integration tests for Solana blockchain

About solana-cli-program template is a sample app demonstrating the creation of a minimal CLI application written in Rust to interact with Solana and

null 46 Nov 3, 2022
Opinionated set of extensions for use with rust-script

rust-script-ext Opinionated set of extensions for use with rust-script. Using rust-script to run Rust like a shell script is great! This crate provide

Kurt Lawrence 13 Sep 3, 2023