Meziantou.Framework

Getting started

edit

Prerequisites

  • A container runtime on the machine: Docker, Podman, Apple's container (macOS) or wslc (Windows). Its daemon must be running; for instance, run container system start once for Apple's container. See Container runtimes.

Install the package

Add the Meziantou.Framework.TemporaryContainers package to your test project:

dotnet package add Meziantou.Framework.TemporaryContainers

The examples of this documentation omit using Meziantou.Framework.TemporaryContainers;.

Start a database

Start a PostgreSQL server and get its connection string:

await using var container = ContainerDefinition.CreatePostgreSql().CreateContainer();
await container.StartAsync(); // pulls the image if needed, then waits until PostgreSQL accepts connections

var connectionString = container.GetConnectionString();
// Host=127.0.0.1;Port=<random port>;Username=postgres;Password=<random password>;Database=postgres
  • CreatePostgreSql returns a definition that is already configured: the image, the port, a random password, and the checks that tell when PostgreSQL accepts connections.
  • CreateContainer creates the object that manages the container; nothing runs yet.
  • StartAsync pulls the image when it is not on the machine, creates and starts the container, and returns once the server is ready.
  • The port of the container is published on a random free port of 127.0.0.1, so tests that run at the same time do not collide. The connection string contains it.
  • Disposing the container (await using) removes it.

The other ready-made definitions are described in Databases.

Run your own image

Any image works. Describe the container with a ContainerDefinition, then create and start it:

var definition = new ContainerDefinition(ImageSource.FromRegistry("redis:8"));
definition.Environment.Add("ALLOW_EMPTY_PASSWORD", "yes");
definition.Ports.Add(new ContainerPort(6379));
definition.WaitStrategies.Add(Wait.ForPort(6379));

await using var container = definition.CreateContainer();
await container.StartAsync();

var host = container.GetHostAddress(6379); // 127.0.0.1, unless the daemon runs on another machine
var hostPort = container.GetMappedPort(6379);
// connect to host:hostPort
  • Ports.Add publishes a port of the container; GetMappedPort returns the host port it was given.
  • WaitStrategies.Add tells StartAsync what "ready" means. Without one, StartAsync returns as soon as the container is started, which is usually before the service inside it accepts connections. See Wait strategies.
  • CreateContainer copies the definition: changing definition afterward does not change the container.

Next steps