Need help with dotnet-testcontainers?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

HofmeisterAn
323 Stars 45 Forks MIT License 231 Commits 6 Opened issues

Description

A library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.

Services available

!
?

Need anything else?

Contributors list

NuGet Build Status Quality Gate Status Coverage

.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
    .
  • WithMount
    mounts a volume into the container e. g.
    -v, --volume .:/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()
  .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()
  .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()
  .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

Thanks

Many thanks to JetBrains who provide an Open Source License for this project :heart:.

License

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.