Testcontainers for .NET 2.4.0

by: Andre Hofmeister

Testcontainers for .NET has recently released version 2.4.0 🥳, which includes a variety of improvements and new features. This release is an important milestone that allows more complex and advanced features in upcoming versions, making it easier than ever to write reliable tests.

One of the key improvements in this release is the cross-language experience. The API has been made more intuitive and aligns with other Testcontainers implementations, making it easier to switch between languages without losing the .NET idioms.

Another major feature of this release is the ability to override or subscribe to the lifecycle events of containers. This allows more advanced use cases that rely on running custom code before or after a container is created or started. This feature is particularly useful for developers working on complex projects that require precise control over the container’s lifecycle.

public sealed class KafkaContainer: DockerContainer
{
    ...

    public override Task StartAsync(CancellationToken ct = default)
    {
        return base.StartAsync(ct);
    }

    public override Task StopAsync(CancellationToken ct = default)
    {
        return base.StopAsync(ct);
    }

    protected override Task UnsafeCreateAsync(CancellationToken ct = default)
    {
        return base.UnsafeCreateAsync(ct);
    }

    protected override Task UnsafeDeleteAsync(CancellationToken ct = default)
    {
        return base.UnsafeDeleteAsync(ct);
    }
}

The snippet above overrides the container’s lifecycles.

var kafkaContainer = new KafkaBuilder().Build();
kafkaContainer.Creating += (_, _) => { };
kafkaContainer.Created += (_, _) => { };
kafkaContainer.Starting += (_, _) => { };
kafkaContainer.Started += (_, _) => { };
kafkaContainer.Stopping += (_, _) => { };
kafkaContainer.Stopped += (_, _) => { };

The snippet above subscribes to the container’s lifecycles.

Developers can also override the builder implementations and add custom configurations or input validations on top of it, allowing more advanced use cases. Additionally, developers can put the configurations into independent modules, making it easy to share configurations and best practices with other developers. This is a great way to preconfigure and share common use cases and patterns.

To further help our users take advantage of this feature, we will be publishing a follow-up blog post that provides a detailed explanation on how to implement a module. This post will include step-by-step instructions, code examples, and tips for getting the most out of this feature.

The following feature makes modules even more accessible. The .NET template allows developers to quickly scaffold Testcontainers for .NET modules. It includes the necessary classes, interfaces and explains with example code and comments how to implement the required parts. This feature makes it easy for developers to get started with Testcontainers modules, without needing to spend a lot of time setting them up.

dotnet new --install ./src/Templates
dotnet new tcm --name Kafka --output ./src

This release also includes a low-level modification API (for all resources such as containers, images, networks and volumes), which provides access to the underlying Docker API. This allows developers to set uncommon configurations, which are particularly necessary for complex projects and environments.

_ = new ContainerBuilder().WithCreateParameterModifier(modifier => modifier.HostConfig.Init = true);

WithCreateParameterModifier(Action) is available for all builders.

Furthermore, the release includes an HTTP wait strategy that indicates readiness of the container, application or service running inside the container as soon as a connection to the HTTP endpoint is established.

Finally, this release includes a GitHub Codespaces and Dev Container configuration, which allows developers to develop or test Testcontainers for .NET without needing to set up a local development environment.

Breaking Changes

We made a concerted effort to avoid breaking changes as much as possible. Our goal was to provide a smooth transition to the new version for our users. To achieve this, we have flagged all upcoming breaking changes as obsolete, which means that they will still work for now but will be removed in the next version.

However, there may be cases where we are unable to maintain backwards compatibility. In such instances, we will do our best to provide clear documentation and guidance on how to update your code to work with the new version. We apologize in advance for any inconvenience this may cause and we appreciate your understanding.

1. The interface member IWaitUntil.Until(ITestcontainersContainer, ILogger) has been changed to IWaitUntil.UntilAsync(IContainer). The container instance now holds the instance of ILogger.
2. The member ImageFromDockerfileBuilder.Build() does not return a Task<string> anymore. It returns an implementation of IFutureDockerImage. To finally build the image call CreateAsync(CancellationToken).
3. Use the ContainerBuilder instead of TestcontainersBuilder<TestcontainersContainer> or ContainerBuilder<DockerContainer> for generic (non module) configurations.
4. Following interfaces and classes has been renamed (the old interfaces and classes are still supported in 2.4.0):

Conclusion

Overall, the Testcontainers for .NET release 2.4.0 is a significant step forward for the Testcontainers community. With its new features and improvements, it makes it easier than ever for developers to write reliable tests.

On behalf of the Testcontainers team, I would like to extend a big thank you to our community for your continued support and engagement. The feedback and contributions from our users have been instrumental in helping us improve and evolve Testcontainers for .NET.

We are excited about the new features and improvements in the 2.4.0 release and we hope that you will find them as useful as we do. If you have any questions or feature requests, please don’t hesitate to reach out to us. We also encourage you to join our Slack workspace, where you can connect with other Testcontainers users, share knowledge and experience and stay up to date on the latest developments.