repository·develop·Indexed 26 days ago
https://github.com/testcontainers/testcontainers-dotnetA library for .NET that provides programmatic control over Docker containers to facilitate integration testing. It enables developers to spin up, manage, and tear down isolated, disposable container instances. The library supports all compatible .NET Standard versions and includes features for custom connection string providers, resource mapping, and integration with tools like Flyway and Respawn.
A Testcontainers module typically consists of three core classes:
PostgreSqlBuilder): Extends the Testcontainers builder. It manages the lifecycle, sets default configurations, validates inputs, and provides the API for developers to interact with the module. The result of the builder is an instance of the container class.PostgreSqlConfiguration): An immutable class that stores optional members used to configure the module (e.g., Username, Password).PostgreSqlContainer): The object returned by the builder. It provides module-specific methods to interact with the running container (e.g., retrieving connection strings).IAsyncLifetime interface to manage the container lifecycle. Start the container in InitializeAsync to ensure the environment is ready before tests run, and dispose of it in DisposeAsync to ensure the container is removed after tests complete.Resource reuse requires stable configurations. By default, NetworkBuilder and VolumeBuilder assign random names to resources, which causes the reuse hash to change every time. To enable reuse for these resources, you must override the default random name with a fixed value using .WithName().
_ = new NetworkBuilder()
.WithReuse(true)
.WithName("WeatherForecast");IAsyncLifetime interface: start the container in InitializeAsync to ensure the environment is ready before tests run, and remove it in DisposeAsync after tests complete.localhost or 127.0.0.1 to connect to a container from your test host. Use the Hostname property of the container instance to ensure reliable connectivity.WithNetworkAliases(string) to assign an alias. Other containers on the same network can then access the service via this alias using its internal container port.ElasticsearchClientSettings instance and set the ServerCertificateValidationCallback delegate to CertificateValidations.AllowAll.To simulate network conditions between a service and a test host using Toxiproxy, follow these steps:
Listen address is where Toxiproxy accepts incoming connections from your test host, and the Upstream address is the target service's address.8666 for this purpose.Toxicity property (a value between 0.0 and 1.0) to control the probability of the toxic being applied to a connection.To maintain multi-architecture support and preserve digests when moving the Ryuk image to a private registry, use the following commands. The pinned digest for Testcontainers for .NET is testcontainers/ryuk:0.14.0@sha256:7c1a8a9a47c780ed0f983770a662f80deb115d95cce3e2daa3d12115b8cd28f0.
### Linux/macOS
```shell
skopeo \
copy \
--all \
--preserve-digests \
docker://docker.io/testcontainers/ryuk@sha256:7c1a8a9a47c780ed0f983770a662f80deb115d95cce3e2daa3d12115b8cd28f0 \
docker://registry.mycompany.com/testcontainers/ryuk:0.14.0# There's no Skopeo package for Windows. Use the Skopeo Docker image:
docker run `
--rm `
quay.io/skopeo/stable:v1.22.0 `
copy `
--all `
--preserve-digests `
docker://docker.io/testcontainers/ryuk@sha256:7c1a8a9a47c780ed0f983770a662f80deb115d95cce3e2daa3d12115b8cd28f0 `
docker://registry.mycompany.com/testcontainers/ryuk:0.14.0You can start a PostgreSQL container instance by using the PostgreSqlBuilder. Specify the desired image tag (e.g., postgres:15.1) in the constructor, call .Build(), and then await .StartAsync() to launch the container.
var postgreSqlContainer = new PostgreSqlBuilder("postgres:15.1").Build();
await postgreSqlContainer.StartAsync();To run tests via Docker Compose where the test runner itself is a container, you must mount the raw Docker socket and potentially configure the host override.
Note for Docker Desktop users: You must uncomment and include the environment section with TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal. This is not required when using standard Docker Engine.
version: "3"
services:
docker_compose_test:
build:
dockerfile: Dockerfile
context: .
entrypoint: dotnet
command: test
# Uncomment the lines below in the case of Docker Desktop (see note above).
# TESTCONTAINERS_HOST_OVERRIDE is not needed in the case of Docker Engine.
# environment:
# - TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal
volumes:
- /var/run/docker.sock.raw:/var/run/docker.sock