Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api/connection_string_provider.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The Connection String Provider API provides a standardized way to access and manage connection information for Testcontainers (modules). It allows developers to customize module-provided connection strings or add their own, and to access module-specific connection strings or endpoints (e.g., database connection strings, HTTP API base addresses) in a uniform way.

!!!note
!!! note

Testcontainers modules do not yet implement this feature. Developers can use the provider to define and manage their own connection strings or endpoints. Providers will be integrated by modules in future releases.

Expand Down
12 changes: 6 additions & 6 deletions docs/api/create_docker_container.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ _ = new ContainerBuilder()
.WithImage(new DockerImage("postgres:15.1", new Platform("linux/amd64")));
```

!!!tip
!!! tip

A specifier has the format `<os>|<arch>|<os>/<arch>[/<variant>]`. The user can provide either the operating system or the architecture or both. For more details, see [containerd/platforms](https://github.com/containerd/platforms).

Expand All @@ -42,7 +42,7 @@ _ = new ContainerBuilder("nginx:1.26.3-alpine3.20")

Apps or services running inside a container are usually configured either with environment variables or configuration files. `WithEnvironment(string, string)` sets an environment variable, while `WithResourceMapping(string, string)` copies a file into a container before it starts. This covers common use cases among many .NET applications.

!!!tip
!!! tip

The majority of builder methods are overloaded and have different parameters to set configurations.

Expand Down Expand Up @@ -177,7 +177,7 @@ var postgreSqlContainer = new PostgreSqlBuilder("postgres:15.1")

Using `OverwriteEnumerable<string>(Array.Empty<string>())` removes all default command configurations. This is useful when you want full control over the PostgreSQL startup or when the default configurations do not match your requirements.

!!!tip
!!! tip

You can create your own `ComposableEnumerable<T>` implementation to control exactly how configuration values are composed or modified.

Expand Down Expand Up @@ -232,7 +232,7 @@ var magicNumber = await magicNumberReader.ReadLineAsync()
Assert.Equal(MagicNumber, magicNumber);
```

!!!tip
!!! tip

To avoid port conflicts, do not bind a fix host port. Instead, assign a random host port by using `WithPortBinding(80, true)` and retrieve it from the container instance by using `GetMappedPublicPort(80)`.

Expand Down Expand Up @@ -269,10 +269,10 @@ Assert.Equal(MagicNumber, magicNumber);
| `WithStartupCallback` | Sets the startup callback to invoke after the container start. |
| `WithCreateParameterModifier` | Allows low level modifications of the Docker container create parameter. |

!!!tip
!!! tip

Testcontainers for .NET detects your Docker host configuration. You do **not** have to set the Docker daemon socket.

!!!tip
!!! tip

Testcontainers for .NET detects private Docker registry configurations and applies the credentials automatically to authenticate against registries.
6 changes: 3 additions & 3 deletions docs/api/create_docker_image.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ To build a Docker image with Testcontainers, it's important to understand the bu
2. **Dockerfile name**: The name of the Dockerfile to use
3. **Dockerfile directory**: Where the Dockerfile is located

!!!tip
!!! tip

The build context is optional. If you don't specify one, it defaults to the Dockerfile directory.

Expand Down Expand Up @@ -56,7 +56,7 @@ _ = new ImageFromDockerfileBuilder()

As the tarball's content is based on `/Users/testcontainers/WeatherForecast/`, all paths inside the Dockerfile must be relative to this path. For example, Docker's `COPY` instruction copies all files inside the `WeatherForecast/` directory to the image.

!!!tip
!!! tip

To improve the build time and to reduce the size of the image, it is recommended to include only necessary files. Exclude unnecessary files or directories such as `bin/`, `obj/` and `tests/` with the `.dockerignore` file.

Expand Down Expand Up @@ -119,7 +119,7 @@ _ = new ImageFromDockerfileBuilder()
| `WithBuildArgument` | Sets build-time variables e.g `--build-arg "MAGIC_NUMBER=42"`. |
| `WithCreateParameterModifier` | Allows low level modifications of the Docker image build parameter. |

!!!tip
!!! tip

Testcontainers for .NET detects your Docker host configuration. You do **not** have to set the Docker daemon socket.

Expand Down
4 changes: 2 additions & 2 deletions docs/api/resource_reaper.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Testcontainers automatically assigns a Resource Reaper session id to each Docker resource. After the tests are finished — whether they are successful or not — [Moby Ryuk](https://github.com/testcontainers/moby-ryuk) will take care of the remaining Docker resources and removes them. You can change the Resource Reaper session and group Docker resources together. Right now, only Linux containers are supported.

!!!tip
!!! tip

Whenever possible, do **not** disable the Resource Reaper. It keeps your machine and CI/CD environment clean. If at all, consider disabling the Resource Reaper only for environments that have a mechanism to cleanup Docker resources, e.g. ephemeral CI nodes.

Expand All @@ -23,6 +23,6 @@ await new ContainerBuilder("alpine:3.20.0")
.ConfigureAwait(false);
```

!!!warning
!!! warning

Testcontainers for .NET assigns a default session id. You do not have to override the Resource Reaper session id usually. -->
4 changes: 2 additions & 2 deletions docs/api/resource_reuse.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ _ = new ContainerBuilder("alpine:3.20.0")

The current implementation considers the following resource configurations and their corresponding builder APIs when calculating the hash value.

!!!note
!!! note

Version 3.8.0 did not include the container configuration's name in the hash value.

Expand All @@ -41,7 +41,7 @@ The current implementation considers the following resource configurations and t

By default, all module resource configurations are included. This works well for simple value and reference types that can be serialized and deserialized to JSON without custom converters. However, more complex resource configurations may require a custom converter to properly serialize and deserialize their values.

!!!warning
!!! warning

Reuse does not replace singleton implementations to improve test performance. Prefer proper shared instances according to your chosen test framework.

Expand Down
4 changes: 2 additions & 2 deletions docs/api/wait_strategies.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ _ = Wait.ForUnixContainer()
.UntilInternalTcpPortIsAvailable(8080);
```

!!!note
!!! note

Just because a service is listening on the internal TCP port does not necessarily mean it is fully ready to handle requests. Often, wait strategies such as checking for specific log messages or verifying a health endpoint provide more reliable confirmation that the service is operational.

Expand All @@ -87,7 +87,7 @@ _ = Wait.ForUnixContainer()
.UntilExternalTcpPortIsAvailable(8080);
```

!!!note
!!! note

External TCP port availability doesn't guarantee that the actual service inside the container is ready to handle requests. It only confirms that the port mapping is established and a connection can be made to the host-side proxy.

Expand Down
2 changes: 1 addition & 1 deletion docs/custom_configuration/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ In .NET logging usually goes through the test framework. Testcontainers is not a
[testcontainers.org 00:00:06.26] Start Docker container 027af397344d08d5fc174bf5b5d449f6b352a8a506306d3d96390aaa2bb0445d
[testcontainers.org 00:00:06.64] Delete Docker container 027af397344d08d5fc174bf5b5d449f6b352a8a506306d3d96390aaa2bb0445d

!!!tip
!!! tip

These log messages are from the Testcontainers library and contain information about the test resources. They do not include log messages from the containers. To get the container log messages, see: [Getting log messages](https://dotnet.testcontainers.org/api/create_docker_container/#getting-log-messages).

Expand Down
2 changes: 1 addition & 1 deletion docs/modules/_call_out_test_projects.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
!!!tip
!!! tip

For the complete source code of this example and additional information, please refer to our [test projects](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/tests).
26 changes: 26 additions & 0 deletions docs/modules/garnet.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Garnet

[Garnet](https://github.com/microsoft/garnet) is a high-performance, Redis-compatible in-memory data store.

The Testcontainers Redis module is compatible with the Garnet container image. You can use the existing [`Testcontainers.Redis`](/modules/redis/) package without requiring a separate Garnet module.

!!! note

If Garnet introduces features or configuration options that require dedicated support in the future, we can introduce a separate module at that time.

## Usage

Add the Redis module:

```shell title="NuGet"
dotnet add package Testcontainers.Redis
```

Start a Garnet container using the Redis builder:

```csharp
var garnetContainer = new RedisBuilder("ghcr.io/microsoft/garnet:1.0.99").Build();
await garnetContainer.StartAsync();
```

--8<-- "docs/modules/_call_out_test_projects.txt"
4 changes: 4 additions & 0 deletions docs/modules/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ await moduleNameContainer.StartAsync();
| K3s | `rancher/k3s:v1.26.2-k3s1` | [NuGet](https://www.nuget.org/packages/Testcontainers.K3s) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.K3s) |
| Kafka | `confluentinc/cp-kafka:6.1.9` | [NuGet](https://www.nuget.org/packages/Testcontainers.Kafka) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Kafka) |
| Keycloak | `quay.io/keycloak/keycloak:21.1` | [NuGet](https://www.nuget.org/packages/Testcontainers.Keycloak) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Keycloak) |
| KurrentDb | `kurrentplatform/kurrentdb:25.1` | [NuGet](https://www.nuget.org/packages/Testcontainers.KurrentDb) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.KurrentDb) |
| Kusto emulator | `mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest` | [NuGet](https://www.nuget.org/packages/Testcontainers.Kusto) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Kusto) |
| LocalStack | `localstack/localstack:2.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.LocalStack) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.LocalStack) |
| Lowkey Vault | `nagyesta/lowkey-vault:2.7.1-ubi9-minimal` | [NuGet](https://www.nuget.org/packages/Testcontainers.LowkeyVault) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.LowkeyVault) |
Expand All @@ -59,6 +60,7 @@ await moduleNameContainer.StartAsync();
| MySQL | `mysql:8.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.MySql) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.MySql) |
| NATS | `nats:2.9` | [NuGet](https://www.nuget.org/packages/Testcontainers.Nats) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Nats) |
| Neo4j | `neo4j:5.4` | [NuGet](https://www.nuget.org/packages/Testcontainers.Neo4j) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Neo4j) |
| Ollama | `ollama/ollama:0.6.6` | [NuGet](https://www.nuget.org/packages/Testcontainers.Ollama) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Ollama) |
| OpenSearch | `opensearchproject/opensearch:2.12.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.OpenSearch) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.OpenSearch) |
| Oracle | `gvenzl/oracle-xe:21.3.0-slim-faststart` | [NuGet](https://www.nuget.org/packages/Testcontainers.Oracle) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Oracle) |
| Papercut | `changemakerstudiosus/papercut-smtp:latest` | [NuGet](https://www.nuget.org/packages/Testcontainers.Papercut) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Papercut) |
Expand All @@ -71,8 +73,10 @@ await moduleNameContainer.StartAsync();
| RavenDB | `ravendb/ravendb:5.4-ubuntu-latest` | [NuGet](https://www.nuget.org/packages/Testcontainers.RavenDb) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.RavenDb) |
| Redis | `redis:7.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.Redis) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Redis) |
| Redpanda | `docker.redpanda.com/redpandadata/redpanda:v22.2.1` | [NuGet](https://www.nuget.org/packages/Testcontainers.Redpanda) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Redpanda) |
| Seq | `datalust/seq:2025.2` | [NuGet](https://www.nuget.org/packages/Testcontainers.Seq) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Seq) |
| Sftp | `atmoz/sftp:alpine` | [NuGet](https://www.nuget.org/packages/Testcontainers.Sftp) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Sftp) |
| SQL Server | `mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04` | [NuGet](https://www.nuget.org/packages/Testcontainers.MsSql) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.MsSql) |
| Temporal | `temporalio/temporal:1.5.1` | [NuGet](https://www.nuget.org/packages/Testcontainers.Temporal) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Temporal) |
| Toxiproxy | `ghcr.io/shopify/toxiproxy:2.12.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.Toxiproxy) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Toxiproxy) |
| Typesense | `typesense/typesense:28.0` | [NuGet](https://www.nuget.org/packages/Testcontainers.Typesense) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Typesense) |
| Weaviate | `semitechnologies/weaviate:1.26.14` | [NuGet](https://www.nuget.org/packages/Testcontainers.Weaviate) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Weaviate) |
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/qdrant.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,6 @@ The module creates a container that listens to requests over **HTTP**. The offic

1. Configuring the module to use TLS.
1. Configuring server certificate validation.
1. Reference [`System.Net.Http.WinHttpHandler`](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler) version `6.0.1` or later, and configure `WinHttpHandler` as the handler for `GrpcChannelOptions` in the Qdrant client.
1. Reference [`System.Net.Http.WinHttpHandler`](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler) version `6.0.1` or later, and configure `WinHttpHandler` as handler for `GrpcChannelOptions` in the Qdrant client.

Refer to the official [Qdrant .NET SDK](https://github.com/qdrant/qdrant-dotnet) for more information.
27 changes: 27 additions & 0 deletions docs/modules/redis.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Redis

[Redis](https://redis.io/) is an in-memory key–value database, used as a distributed cache and message broker, with optional durability.

Add the following dependency to your project file:

```shell title="NuGet"
dotnet add package Testcontainers.Redis
```

You can start a Redis container instance from any .NET application. This example uses xUnit.net's `IAsyncLifetime` interface to manage the lifecycle of the container. The container is started in the `InitializeAsync` method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the container is removed in the `DisposeAsync` method.

=== "Usage Example"
```csharp
--8<-- "tests/Testcontainers.Redis.Tests/RedisContainerTest.cs:UseRedisContainer"
```

The test example uses the following NuGet dependencies:

=== "Package References"
```xml
--8<-- "tests/Testcontainers.Redis.Tests/Testcontainers.Redis.Tests.csproj:PackageReferences"
```

To execute the tests, use the command `dotnet test` from a terminal.

--8<-- "docs/modules/_call_out_test_projects.txt"
26 changes: 26 additions & 0 deletions docs/modules/valkey.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Valkey

[Valkey](https://github.com/valkey-io/valkey) is an open-source, Redis-compatible in-memory data store.

The Testcontainers Redis module is compatible with the Valkey container image. You can use the existing [`Testcontainers.Redis`](/modules/redis/) package without requiring a separate Garnet module.

!!! note

If Valkey introduces features or configuration options that require dedicated support in the future, we can introduce a separate module at that time.

## Usage

Add the Redis module:

```shell title="NuGet"
dotnet add package Testcontainers.Redis
```

Start a Valkey container using the Redis builder:

```csharp
var valkeyContainer = new RedisBuilder("valkey/valkey:9.0-alpine").Build();
await valkeyContainer.StartAsync();
```

--8<-- "docs/modules/_call_out_test_projects.txt"
2 changes: 1 addition & 1 deletion docs/test_frameworks/xunit_net.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The example below demonstrates how to override the `Configure(TBuilderEntity)` m
--8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`1.cs:ConfigureRedisContainer"
```

!!!tip
!!! tip
Always pin the image version to avoid flakiness. This ensures consistency and prevents unexpected behavior, as the `latest` tag may pointing to a new version.

The base class also receives an instance of xUnit.net's [ITestOutputHelper](https://xunit.net/docs/capturing-output) to capture and forward log messages to the running test.
Expand Down
3 changes: 3 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ nav:
- modules/clickhouse.md
- modules/db2.md
- modules/elasticsearch.md
- modules/garnet.md
- modules/grafana.md
- modules/mongodb.md
- modules/mssql.md
Expand All @@ -66,6 +67,8 @@ nav:
- modules/postgres.md
- modules/qdrant.md
- modules/rabbitmq.md
- modules/redis.md
- modules/toxiproxy.md
- modules/valkey.md
- contributing.md
- contributing_docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ private static EventHubsServiceConfiguration GetServiceConfiguration()
public async Task SendEventDataBatchShouldNotThrowException()
{
// Given
var message = Guid.NewGuid().ToString();
var message = Guid.NewGuid().ToString("D");

var readOptions = new ReadEventOptions();
readOptions.MaximumWaitTime = TimeSpan.FromSeconds(5);
Expand Down
Loading
Loading