3.2.0

What's Changed

🚀 Features

• feat: Add TC host strategy (#885) @HofmeisterAn
• feat: Add Keycloak module (#880) @VMelnalksnis
• feat: Add Docker image build policy (#882) @HofmeisterAn

🐛 Bug Fixes

• fix: Do not create a Port Forwarding Container instance if auto-discovery does not detect Docker host (#900) @HofmeisterAn
• fix: Replace CLI command to detect open ports in Linux containers (#883) @HofmeisterAn
• fix: Remove trailing slash from rootless Docker socket path (#881) @HofmeisterAn

📖 Documentation

• docs: Add information about running Testcontainers in specific CI environments (#895) @HofmeisterAn
• fix: Typo in Selenium (#893) @dotkarl
• docs: Link to Wikipedia to explain the .properties file format (#889) @HofmeisterAn
• docs: Add Docker remote host configuration (#888) @HofmeisterAn

🧹 Housekeeping

• chore: Favor custom environment variable configurations over properties file (#899) @HofmeisterAn
• chore: Update Docker.DotNet from version 3.125.13 to 3.125.15 (#898) @HofmeisterAn
• chore: Update Ryuk image from version 0.4.0 to 0.5.1 (#896) @HofmeisterAn
• chore: Build image with ITestcontainersClient implementation (#884) @HofmeisterAn

3.1.0

What's Changed

⚠️ Breaking Changes

• As mentioned in the two previous releases, we replaced the legacy extension method modules with a dedicated API. We recommend moving forward to the new API. In this release, all classes and interfaces related to the legacy extension method approach have been removed.

🚀 Features

• feat: Add default session-id label to Docker resources (#878) @HofmeisterAn
• feat: Expose host ports (#873) @HofmeisterAn
• feat: Automatically detect Docker Desktop for Linux rootless socket (#872) @HofmeisterAn
• feat: Replace Azurite module (#871) @HofmeisterAn
• feat: Add .NET Source Link to modules (#870) @HofmeisterAn
• feat: Detect rootless Docker endpoint configurations (#868) @HofmeisterAn
• feat: Always use Docker's assigned random host port (Ryuk) (#852) @HofmeisterAn
• feat: Add container builder member to depend on other Docker resources (#832) @HofmeisterAn
• feat: Add K3s module (#835) @adar2
• feat: Replace CosmosDb module (#833) @AButler
• feat: Add WebDriver module (#780) @ShaharM7

🐛 Bug Fixes

• fix: KafkaException (timeout) while creating a topic (#849) @HofmeisterAn
• fix: Log Docker image build progress messages (#839) @HofmeisterAn

📖 Documentation

• docs: Explain how to delete multi-stage intermediate layers (#867) @HofmeisterAn
• docs: Explain the Docker build context (building a Docker image) (#861) @HofmeisterAn
• docs: Update ASP.NET Core Blazor out-off-process example (#838) @HofmeisterAn
• docs: Update the documentation and WeatherForecast example (#823) @HofmeisterAn

🧹 Housekeeping

• chore: Update Ryuk image from version 0.3.4 to 0.4.0 (#854) @HofmeisterAn
• chore: Update LocalStack image from version 1.4 to 2.0 (#864) @HofmeisterAn
• chore: Update Redpanda image (#840) @eddumelendez
• feat: Prepare next release cycle (3.1.0) (#822) @HofmeisterAn

3.0.0

What's Changed

We have added and replaced the modules mentioned below. Each module contains its own builder and configuration type, making it much easier to support various test cases. Currently, the modules are designed to quickly spin up common configurations of real dependencies to establish a connection to the application or service running inside it.

We are interested in your opinions and requirements in regards of the module's capabilities. Creating great modules is a community effort, so please consider sharing your thoughts with us and other Testcontainers users in this discussion or in our Slack workspace.

We will continuously add module features and documentation. Currently, information on how to configure and run modules can be found in the tests. If you are already familiar with Testcontainers, you should have no trouble understanding it as the experience is very similar as before. Here is a quick example using xUnit.net:

public sealed class ModuleSupport : IAsyncLifetime
{
    private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build();

    public Task InitializeAsync()
    {
        return _msSqlContainer.StartAsync();
    }

    public Task DisposeAsync()
    {
        return _msSqlContainer.DisposeAsync().AsTask();
    }

    [Fact]
    public void ConnectionStateReturnsOpen()
    {
        // Given
        using DbConnection connection = new SqlConnection(_msSqlContainer.GetConnectionString());

        // When
        connection.Open();

        // Then
        Assert.Equal(ConnectionState.Open, connection.State);
    }
}

⚠️ Breaking Changes

• chore!: Remove legacy WithCreateContainerParametersModifier(Action) (#809) @HofmeisterAn
• chore!: Remove legacy IDockerImage (#808) @HofmeisterAn
• chore!: Remove legacy TestcontainersVolumeBuilder, IDockerVolume (#805) @HofmeisterAn
• chore!: Remove legacy TestcontainersNetworkBuilder, IDockerNetwork (#804) @HofmeisterAn

Old name	New name
ITestcontainersContainer, IDockerContainer, IRunningDockerContainer	IContainer
IDockerImage	IImage
IDockerNetwork	INetwork
IDockerVolume	IVolume
TestcontainersBuilder	ContainerBuilder
TestcontainersContainer	DockerContainer
TestcontainersNetworkBuilder	NetworkBuilder
TestcontainersVolumeBuilder	VolumeBuilder
WithCreateContainerParametersModifier	WithCreateParameterModifier

🚀 Features

• feat: Sign assemblies with a strong name (#815) @HofmeisterAn
• feat: Add SQL Edge module (#812) @HofmeisterAn
• feat: Replace Kafka module (#802) @HofmeisterAn
• feat: Replace Couchbase module (#798) @HofmeisterAn
• feat: Add Redpanda module (#796) @eddumelendez
• fix: Wait until container ports are mapped, removed generated credentials (#791) @HofmeisterAn
• feat: Replace output consumer with IContainer.GetLogsAsync(DateTime, DateTime, bool, CancellationToken) (#793) @HofmeisterAn
• feat: Add EventStoreDb module (#778) @meysamhadeli
• feat: Replace Elasticsearch module (#790) @HofmeisterAn
• feat: Replace RabbitMq module (#788) @HofmeisterAn
• feat: Replace Neo4j module (#785) @HofmeisterAn
• feat: Replace CouchDb module (#779) @HofmeisterAn
• feat: Replace MongoDB module (#776) @HofmeisterAn
• feat: Add DynamoDB module (#768) @dominikus1993
• feat: Replace PostgreSQL module (#772) @HofmeisterAn
• feat: Replace Oracle module (#770) @HofmeisterAn
• feat: Add RavenDB module (#769) @HofmeisterAn
• feat: Add MinIO module (#760) @dominikus1993
• feat: Replace Redis module (#764) @HofmeisterAn
• feat: Replace MariaDB module (#763) @HofmeisterAn
• feat: Replace MySQL module (#761) @HofmeisterAn
• feat: Replace Microsoft SQL Server module (#757) @HofmeisterAn

🐛 Bug Fixes

• fix: InvalidOperationException when adding future volume (#817) @HofmeisterAn
• fix: Wait until container ports are mapped, removed generated credentials (#791) @HofmeisterAn
• fix(#783): Dispose container while Resource Reaper is disabled (#789) @HofmeisterAn

📖 Documentation

• docs: Add best practices (#816) @HofmeisterAn
• docs: Add community links (#807) @HofmeisterAn
• docs: Update Testcontainers for Node docs link (#806) @cristianrgreco
• docs: Add section 'Implement a module' (#771) @HofmeisterAn
• docs: Replace obsolete builders (#756) @HofmeisterAn

🧹 Housekeeping

• fix: Coverlet 'Unable to read beyond end of stream' IOException (#800) @HofmeisterAn
• chore: Clean up EventStoreDb module (#792) @HofmeisterAn
• chore: Clean up LocalStack module (#781) @HofmeisterAn
• chore: Clean up DynamoDB module (#774) @HofmeisterAn
• chore: Clean up MinIO module (#766) @HofmeisterAn
• fix: Use TCP to connect to the MySQL module (#765) @HofmeisterAn
• fix: Use sqlcmd utility to detect readiness of the container (#759) @HofmeisterAn
• fix: Move MsSqlContainerTest class to namespace (#758) @HofmeisterAn
• chore: Update the WeatherForecast example to 2.4.0 (#754) @HofmeisterAn
• chore: Remove obsolete property IDockerNetwork.Id (#753) @HofmeisterAn
• feat: Prepare next release cycle (2.5.0) (#752) @HofmeisterAn

2.4.0

What's Changed

⚠️ 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. If you rely on the module builder, please be aware of #750 (comment) for now.

4. Following interfaces and classes has been renamed (the old interfaces and classes are still supported in 2.4.0):

   Old name	New name
   ITestcontainersContainer, IDockerContainer, IRunningDockerContainer	IContainer
   IDockerImage	IImage
   IDockerNetwork	INetwork
   IDockerVolume	IVolume
   TestcontainersBuilder	ContainerBuilder
   TestcontainersNetworkBuilder	NetworkBuilder
   TestcontainersVolumeBuilder	VolumeBuilder
   TestcontainersContainer	DockerContainer

• feat(#493): Add container lifecycle events (#743) @HofmeisterAn
• refactor(#493): Replace module extension methods with module API (#729) @HofmeisterAn

🚀 Features

• feat: Invoke create parameter modifier for image, network, volume build or create (#746) @HofmeisterAn
• feat(#493): Add .NET module template (#742) @HofmeisterAn
• feat(#493): Add container lifecycle events (#743) @HofmeisterAn
• feat(#493): Add low level modifications API for all resources (#741) @HofmeisterAn
• refactor(#493): Replace module extension methods with module API (#729) @HofmeisterAn
• feat: Add GitHub Codespaces configuration (Dev Container) (#735) @HofmeisterAn
• feat(#725): Do not return JSON auth config for partial Docker registry matches (#726) @HofmeisterAn
• chore: Replace SharpZipLib TarArchive helper class with TarOutputStream (#724) @HofmeisterAn
• feat: Include file path in TarException: Entry closed at [...] (Docker build) (#720) @HofmeisterAn
• feat(#715): Add HttpWaitStrategy (#717) @HofmeisterAn

🐛 Bug Fixes

• fix: Wait until LocalStack writes ready message (#738) @HofmeisterAn

📖 Documentation

• chore: Add link Open in GitHub Codespaces (#739) @eddumelendez
• docs: Add Docker Desktop Compose example (#731) @HofmeisterAn

🧹 Housekeeping

• chore: Rename release branch to main (#748) @HofmeisterAn
• feat(#493): Prepare module NuGet support, sign NuGet (#744) @HofmeisterAn
• chore: Replace host port 0 with an empty string (#727) @HofmeisterAn
• fix: Remove Sonar finding csharpsquid:S6444 (#721) @HofmeisterAn
• chore: Increase HttpWaitStrategy test coverage (#719) @HofmeisterAn
• fix: Remove Sonar finding csharpsquid:S1006 (#718) @HofmeisterAn
• chore: Reduce concurrent builds (#714) @HofmeisterAn
• feat: Prepare next release cycle (2.4.0) (#711) @HofmeisterAn

Release 2.3.0

As part of this release we had 9 issues closed.

Added

• #531 Add Docker health status wait strategy (@kfrajtak)
• #640 Add ITestcontainersBuilder<TDockerContainer>.WithResourceMapping to copy files or any binary contents into the created container before it is started
• #654 Add ITestcontainersNetworkBuilder.WithOption (@vlaskal)
• #678 Add support of custom configuration TESTCONTAINERS_HOST_OVERRIDE and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE
• #694 Add Resource Reaper (Ryuk) privileged mode support (TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED)

Changed

• #642 Expose container port bindings automatically
• #603 Add default logger that forwards messages to the console (does not support every test environment)
• #683 Return the gateway address (IDockerContainer.Hostname) of a network if one is assigned
• #703 ResourceReaper.GetAndStartDefaultAsync no longer support optional arguments, it is necessary to set the Resource Reaper configuration immediately

Fixed

• #610 Trim traling slashes in Dockerfile directory path (otherwise, it cuts the first character of the relative path), Normalize paths to forward slashes
• #648 Always include .dockerignore and Dockerfile files in tarball (docker build)
• #650 Update SharpZipLib to version 1.4.1 to prevent a deadlock in the Docker container image build
• #666 DockerImageNotFoundException when logged in with Docker Desktop instead of the CLI

Thanks for your contributions 🙏

Release 2.2.0

As part of this release we had 24 issues closed.

Added

• #370 Add protected Docker daemon socket support (@vlaskal)
• #421 Add Azurite module (@vlaskal)
• #421 Add Cosmos DB Linux Emulator (@Yeseh, @ktjn)
• #504 Add Elasticsearch module (@chertby)
• #516 Add ITestcontainersBuilder<TDockerContainer>.WithTmpfsMount (@chrisbbe)
• #520 Add MariaDB module (@renemadsen)
• #528 Do not require the Docker host configuration (DockerEndpointAuthConfig) on TestcontainersSettings initialization
• #538 Support optional username and password in MongoDB connection string (@the-avid-engineer)
• #540 Add Docker registry authentication provider for DOCKER_AUTH_CONFIG environment variable (@vova-lantsov-dev)
• #541 Allow MsSqlTestcontainerConfiguration custom database names (@enginexon)
• #558 Support relative base directories other than the working directory with WithDockerfileDirectory
• #565 Add ExecScriptAsync (MongoDB Shell) to MongoDB module
• #579 Add Neo4j module (@kaiserbergin)
• #583 Add XML documentation to NuGet
• #592 Add LocalStack module (@bgener)
• #594 Add IDockerContainer.GetLogs
• #601 Add ITestcontainersBuilder<TDockerContainer>.WithImagePullPolicy (@BenasB)
• #616 Add ITestcontainersBuilder<TDockerContainer>.WithMacAddress (@seb1992)
• #618 Match .dockerignore entry * to all files and directories
• #626 Support MySQL root password configuration (@DanielHabenicht)

Changed

• #571 Update wnameless/oracle-xe-11g-r2 to gvenzl/oracle-xe:21-slim

Fixed

• #525 Read ServerURL, Username and Secret field from CredsStore response to pull private Docker images
• #595 Implement TestcontainersContainer.DisposeAsync thread safe (rename TestcontainersState to TestcontainersStates)
• #604 Do not deny all files in the Docker image tarball when a .dockerignore entry ends with /
• #610 Do not deny all files in the Docker image tarball when a .dockerignore entry ends with /*
• #632 Execute local database scripts (inside the container) against localhost
• #634 JsonReaderException in Docker.DotNet with Docker Desktop 4.13.0 (dotnet/Docker.DotNet#595)

Thanks for your contributions 🙏

Release 2.1.0

As part of this release we had 11 issues closed.

Added

• #481 Add builder access to the CreateContainerParameters instance (@Xitric)
• #483 Support custom resource reaper image via TestcontainersSettings.ResourceReaperImage (@vlaskal)
• #495 Add CHANGELOG.md
• #496 Support ~/.testcontainers.properties custom configuration
• #500 Add trace output while building or pulling a Docker image (@michal-korniak)
• #501 Throw an exception when Docker image has not been built (@michal-korniak)
• #509 Check if the authentication provider can establish a Docker endpoint connection
• #510 Add IImageFromDockerfileBuilder.WithBuildArgument (@michal-korniak)
• #511 Remove temp Dockerfile archive after Docker build (@michal-korniak)
• #512 Throw ArgumentException if Docker image name contains uppercase characters (@michal-korniak)

Removed

• #497 Remove ResourceReaperDiagnostics

Fixed

• #431 Fix System.InvalidOperationException : cannot hijack chunked or content length stream (update Docker.DotNet dependency)
• #449 Fix wrong mapped public host port
• #484 Fix unit tests that fail on Windows hosts (@vlaskal)
• #507 Fix ITestcontainersConfiguration duplication, such as DockerApiException : [...] Duplicate mount point [...] (@alesandrino)

Thanks for your contributions 🙏

Release 2.0.1

As part of this patch release we had 2 issues closed.

• #449 Fixes ResourceReaperException, Testcontainers couldn't establish a connection to the resource reaper (public host port wasn't set)
• #485 Fixes ArgumentNullException while mapping the network configurations in TestcontainersConfigurationConverter (@pellared)

Release 2.0.0

With this release, we transferred the repository to the official Testcontainers organization. As part of this release we had 3 issues closed.

• #455 Add WithNetworkAliases (@vlaskal).
• #461 Add Docker credentials helpers (@harrhp).
• #470 Fixes HubImageNamePrefix in combination with private Docker registry credentials (@bohlenc).

Release 1.6.0

As part of this release we had 10 issues closed.

⚠️ This version has breaking changes. It contains a lot of new features, including performance and stability improvements.

• #242, #464 Add Resource Reaper (@PSanetra, @s-rech).
• #393 Pass container instance to wait strategy.
• #398 Add MongoDB module (@RMariowski).
• #403 Add managed volume.
• #430 Get file from a running container (@s-rech).
• #444 Add Docker credentials store (credentials helpers not included).
• #463 Use DOCKER_HOST as Docker endpoint (supports custom client configurations).
• #466 Add Docker Hub substitution (@bohlenc).
• #428 Fixes NullReferenceException when Docker image is not set (@jlevier-ae).
• #390 Get the ExecResult instead of the exit code from IDockerContainerOperations.ExecAsync (@fabiogouw).
• #399 Add IDatabaseScript.IDatabaseScript for TestcontainerDatabase (@fabiogouw).

📝 If your Docker host can't access the domain socket (or IPC socket) /var/run/docker.sock, disable the Resource Reaper (TestcontainersSettings.ResourceReaperEnabled = false).