feat: Add a wait strategy that waits until the ADO.NET database is available (#1401)

Co-authored-by: Andre Hofmeister <[email protected]>

Author: 0xced

docs/modules/cassandra.md

@@ -8,7 +8,15 @@ Add the following dependency to your project file:
 dotnet add package Testcontainers.Cassandra
 ```
 
-You can start an Apache Cassandra 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.
+You can start an Apache Cassandra container instance from any .NET application. To create and start a container instance with the default configuration, use the module-specific builder as shown below:
+
+=== "Start a Cassandra container"
+    ```csharp
+    var cassandraContainer = new CassandraBuilder().Build();
+    await cassandraContainer.StartAsync();
+    ```
+
+The following example utilizes the [xUnit.net](/test_frameworks/xunit_net/) module to reduce overhead by automatically managing the lifecycle of the dependent container instance. It creates and starts the container using the module-specific builder and injects it as a shared class fixture into the test class.
 
 === "Usage Example"
     ```csharp

docs/modules/db2.md

@@ -12,7 +12,15 @@ dotnet add package Testcontainers.Db2
 
     The Linux client dependency, [Net.IBM.Data.Db2-lnx](https://www.nuget.org/packages/Net.IBM.Data.Db2-lnx), requires additional configurations. We use the [Testcontainers.Db2.Tests.targets](https://github.com/testcontainers/testcontainers-dotnet/blob/develop/tests/Testcontainers.Db2.Tests/Testcontainers.Db2.Tests.targets) file to configure the environment variables: `LD_LIBRARY_PATH`, `PATH`, `DB2_CLI_DRIVER_INSTALL_PATH`, at runtime.
 
-You can start an Db2 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.
+You can start a Db2 container instance from any .NET application. To create and start a container instance with the default configuration, use the module-specific builder as shown below:
+
+=== "Start a Db2 container"
+    ```csharp
+    var db2Container = new Db2Builder().Build();
+    await db2Container.StartAsync();
+    ```
+
+The following example utilizes the [xUnit.net](/test_frameworks/xunit_net/) module to reduce overhead by automatically managing the lifecycle of the dependent container instance. It creates and starts the container using the module-specific builder and injects it as a shared class fixture into the test class.
 
 === "Usage Example"
     ```csharp

docs/modules/mssql.md

@@ -8,14 +8,15 @@ Add the following dependency to your project file:
 dotnet add package Testcontainers.MsSql
 ```
 
-You can start a MSSQL container instance from any .NET application. Here, we create different container instances and pass them to the base test class. This allows us to test different configurations.
+You can start a MSSQL container instance from any .NET application. To create and start a container instance with the default configuration, use the module-specific builder as shown below:
 
-=== "Create Container Instance"
+=== "Start a MSSQL container"
     ```csharp
-    --8<-- "tests/Testcontainers.MsSql.Tests/MsSqlContainerTest.cs:CreateMsSqlContainer"
+    var msSqlContainer = new MsSqlBuilder().Build();
+    await msSqlContainer.StartAsync();
     ```
 
-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.
+The following example utilizes the [xUnit.net](/test_frameworks/xunit_net/) module to reduce overhead by automatically managing the lifecycle of the dependent container instance. It creates and starts the container using the module-specific builder and injects it as a shared class fixture into the test class.
 
 === "Usage Example"
     ```csharp

docs/modules/postgres.md

@@ -8,7 +8,15 @@ Add the following dependency to your project file:
 dotnet add package Testcontainers.PostgreSql
 ```
 
-You can start an PostgreSQL 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.
+You can start a PostgreSQL container instance from any .NET application. To create and start a container instance with the default configuration, use the module-specific builder as shown below:
+
+=== "Start a PostgreSQL container"
+    ```csharp
+    var postgreSqlContainer = new PostgreSqlBuilder().Build();
+    await postgreSqlContainer.StartAsync();
+    ```
+
+The following example utilizes the [xUnit.net](/test_frameworks/xunit_net/) module to reduce overhead by automatically managing the lifecycle of the dependent container instance. It creates and starts the container using the module-specific builder and injects it as a shared class fixture into the test class.
 
 === "Usage Example"
     ```csharp

docs/modules/pulsar.md

@@ -8,7 +8,7 @@ Add the following dependency to your project file:
 dotnet add package Testcontainers.Pulsar
 ```
 
-You can start a Apache Pulsar container instance from any .NET application. Here, we create different container instances and pass them to the base test class. This allows us to test different configurations.
+You can start an Apache Pulsar container instance from any .NET application. Here, we create different container instances and pass them to the base test class. This allows us to test different configurations.
 
 === "Create Container Instance"
     ```csharp

docs/modules/qdrant.md

@@ -8,7 +8,7 @@ Add the following dependency to your project file:
 dotnet add package Testcontainers.Qdrant
 ```
 
-You can start an Qdrant 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.
+You can start a Qdrant 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

src/Testcontainers.Cassandra/CassandraContainer.cs

@@ -16,9 +16,12 @@ public CassandraContainer(CassandraConfiguration configuration)
     /// <returns>The Cassandra connection string.</returns>
     public string GetConnectionString()
     {
+        var publicPort = GetMappedPublicPort(CassandraBuilder.CqlPort).ToString();
+
         var properties = new Dictionary<string, string>();
         properties.Add("Contact Points", Hostname);
-        properties.Add("Port", GetMappedPublicPort(CassandraBuilder.CqlPort).ToString());
+        properties.Add("Port", publicPort);
+        properties.Add("Cluster Name", $"{Hostname}:{publicPort}");
         return string.Join(";", properties.Select(property => string.Join("=", property.Key, property.Value)));
     }
 

src/Testcontainers.EventHubs/Usings.cs

@@ -4,7 +4,6 @@
 global using System.Linq;
 global using System.Text;
 global using System.Text.Json;
-global using System.Threading.Tasks;
 global using Docker.DotNet.Models;
 global using DotNet.Testcontainers;
 global using DotNet.Testcontainers.Builders;

src/Testcontainers/Configurations/WaitStrategies/IWaitForContainerOS.cs

@@ -2,7 +2,9 @@ namespace DotNet.Testcontainers.Configurations
 {
   using System;
   using System.Collections.Generic;
+  using System.Data.Common;
   using System.Text.RegularExpressions;
+  using DotNet.Testcontainers.Containers;
   using JetBrains.Annotations;
 
   /// <summary>
@@ -112,6 +114,18 @@ public interface IWaitForContainerOS
     [PublicAPI]
     IWaitForContainerOS UntilContainerIsHealthy(long failingStreak = 3, Action<IWaitStrategy> waitStrategyModifier = null);
 
+    /// <summary>
+    /// Waits until a successful connection to the database can be established.
+    /// </summary>
+    /// <remarks>
+    /// To use this wait strategy, the container must implement the <see cref="IDatabaseContainer" /> interface.
+    /// </remarks>
+    /// <param name="dbProviderFactory">The <see cref="DbProviderFactory" /> used to create the database connection.</param>
+    /// <param name="waitStrategyModifier">The wait strategy modifier to cancel the readiness check.</param>
+    /// <returns>A configured instance of <see cref="IWaitForContainerOS" />.</returns>
+    [PublicAPI]
+    IWaitForContainerOS UntilDatabaseIsAvailable(DbProviderFactory dbProviderFactory, Action<IWaitStrategy> waitStrategyModifier = null);
+
     /// <summary>
     /// Returns a collection with all configured wait strategies.
     /// </summary>

src/Testcontainers/Configurations/WaitStrategies/UntilDatabaseIsAvailable.cs

@@ -0,0 +1,52 @@
+namespace DotNet.Testcontainers.Configurations
+{
+  using System;
+  using System.Data.Common;
+  using System.Threading.Tasks;
+  using DotNet.Testcontainers.Containers;
+
+  internal class UntilDatabaseIsAvailable : IWaitUntil
+  {
+    private readonly DbProviderFactory _dbProviderFactory;
+
+    public UntilDatabaseIsAvailable(DbProviderFactory dbProviderFactory)
+    {
+      _dbProviderFactory = dbProviderFactory;
+    }
+
+    public async Task<bool> UntilAsync(IContainer container)
+    {
+      if (container is not IDatabaseContainer dbContainer)
+      {
+        throw new NotSupportedException(
+          $"The 'UntilDatabaseIsAvailable' wait strategy can only be used with database containers. " +
+          $"The provided container type '{container.GetType().FullName}' does not implement '{nameof(IDatabaseContainer)}'.");
+      }
+
+      var connection = _dbProviderFactory.CreateConnection();
+      if (connection == null)
+      {
+        throw new InvalidOperationException(
+          $"Failed to create a database connection. The factory '{_dbProviderFactory.GetType().FullName}' returned null from 'CreateConnection()'.");
+      }
+
+      try
+      {
+        connection.ConnectionString = dbContainer.GetConnectionString();
+
+        await connection.OpenAsync()
+          .ConfigureAwait(false);
+
+        return true;
+      }
+      catch
+      {
+        return false;
+      }
+      finally
+      {
+        connection.Dispose();
+      }
+    }
+  }
+}