.NET Testcontainers

.NET Testcontainers is a library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions. The library is built on top of the .NET Docker remote API and provides a lightweight implementation to support your test environment in all circumstances.

Choose from existing pre-configured configurations and start containers within a second, to support and run your tests. Or create your own containers with Dockerfiles and run your tests immediately afterward.

Supported operating systems

.NET Testcontainers supports Windows, Linux, and macOS as host systems. Linux Docker containers are supported on all three operating systems.

Native Windows Docker containers are only supported on Windows. Windows requires the host operating system version to match the container operating system version. You'll find further information about Windows container version compatibility here.

Keep in mind to enable the correct Docker engine on Windows host systems to match the container operating system. With Docker CE you can switch the engine with: $env:ProgramFiles\Docker\Docker\DockerCli.exe -SwitchDaemon or -SwitchLinuxEngine, -SwitchWindowsEngine.

Supported commands

WithImage specifies an IMAGE[:TAG] to derive the container from.
WithWorkingDirectory specifies and overrides the WORKDIR for the instruction sets.
WithEntrypoint specifies and overrides the ENTRYPOINT that will run as an executable.
WithCommand specifies and overrides the COMMAND instruction provided from the Dockerfile.
WithName sets the container name e. g. --name nginx.
WithHostname sets the container hostname e. g. --hostname my-nginx.
WithEnvironment sets an environment variable in the container e. g. -e, --env "test=containers".
WithLabel applies metadata to a container e. g. -l, --label dotnet.testcontainers=awesome.
WithExposedPort exposes a port inside the container e. g. --expose=80.
WithPortBinding publishes a container port to the host e. g. -p, --publish 80:80.
WithBindMount binds a path of a file or directory into the container e. g. -v, --volume .:/tmp.
WithVolumeMount mounts a managed volume into the container e. g. --mount type=volume,source=.,destination=/tmp.
WithNetwork assigns a network to a container e. g. --network="bridge".
WithCleanUp removes a stopped container automatically.
WithDockerEndpoint sets the Docker API endpoint e. g. -H tcp://0.0.0.0:2376.
WithRegistryAuthentication basic authentication against a private Docker registry.
WithOutputConsumer redirects stdout and stderr to capture the Testcontainer output.
WithWaitStrategy sets the wait strategy to complete the Testcontainer start and indicates when it is ready.
WithStartupCallback sets the startup callback to invoke after the Testcontainer start.
WithDockerfileDirectory builds a Docker image based on a Dockerfile (ImageFromDockerfileBuilder).
WithDeleteIfExists removes the Docker image before it is rebuilt (ImageFromDockerfileBuilder).

Pre-configured containers

The pre-configured Testcontainers below are supported. Further examples can be found in TestcontainersContainerTest as well as in database or message broker tests.

Apache CouchDB (couchdb:2.3.1)
Couchbase (couchbase:6.5.1)
Microsoft SQL Server (mcr.microsoft.com/mssql/server:2017-CU14-ubuntu)
MongoDB (mongo:5.0.2)
MySQL (mysql:8.0.18)
Oracle Database (wnameless/oracle-xe-11g-r2)
PostgreSQL (postgres:11.5)
Redis (redis:5.0.6)
Apache Kafka (confluentinc/cp-kafka:6.0.1)
RabbitMQ (rabbitmq:3.7.21)

Examples

Pulls nginx, creates a new container with port binding 80:80 and hits the default site.

var testcontainersBuilder = new TestcontainersBuilder<TestcontainersContainer>()
  .WithImage("nginx")
  .WithName("nginx")
  .WithPortBinding(80)
  .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(80));

await using (var testcontainer = testcontainersBuilder.Build())
{
  await testcontainer.StartAsync();
  var request = WebRequest.Create("http://localhost:80");
}

Mounts the current directory as volume into the container and runs hostname > /tmp/hostname on startup.

var testcontainersBuilder = new TestcontainersBuilder<TestcontainersContainer>()
  .WithImage("nginx")
  .WithName("nginx")
  .WithMount(".", "/tmp")
  .WithCommand("/bin/bash", "-c", "hostname > /tmp/hostname")
  .WithWaitStrategy(Wait.ForUnixContainer().UntilFileExists("/tmp/hostname"));

await using (var testcontainer = testcontainersBuilder.Build())
{
  await testcontainer.StartAsync();
}

Here is an example of a pre-configured Testcontainer. In the example, Testcontainers starts a PostgreSQL database and executes a SQL query.

var testcontainersBuilder = new TestcontainersBuilder<PostgreSqlTestcontainer>()
  .WithDatabase(new PostgreSqlTestcontainerConfiguration
  {
    Database = "db",
    Username = "postgres",
    Password = "postgres",
  });

await using (var testcontainer = testcontainersBuilder.Build())
{
  await testcontainer.StartAsync();

  using (var connection = new NpgsqlConnection(testcontainer.ConnectionString))
  {
    connection.Open();

    using (var cmd = new NpgsqlCommand())
    {
      cmd.Connection = connection;
      cmd.CommandText = "SELECT 1";
      cmd.ExecuteReader();
    }
  }
}

The implementation of the pre-configured wait strategies can be chained together to support individual requirements for Testcontainers with different container platform operating systems.

Wait.ForUnixContainer()
  .UntilPortIsAvailable(80)
  .UntilFileExists("/tmp/foo")
  .UntilFileExists("/tmp/bar")
  .UntilOperationIsSucceeded(() => true, 1);

Logging

To enable and configure logging, set the static TestcontainersSettings.Logger property before test execution.

Note

Please keep in mind this is not the official repository. Unfortunately, my requirements are not supported by the official implementation yet. Although we try to add new features and refactor the current version of testcontainers/testcontainers-dotnet, the progress is slow. As long as the official implementation does not cover all my requirements, I will work on both projects.

Contributing

See CONTRIBUTING.md

Authors

Andre Hofmeister - Initial work - HofmeisterAn

Thanks

Many thanks to JetBrains who provide an Open Source License for this project ❤️.

License

This project is licensed under the MIT License - see the LICENSE file for details.

karelkral/dotnet-testcontainers