feat: Add wait strategy to check external (TCP) port availability (#1495)

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

Author: WhiteTomX

docs/api/wait_strategies.md

@@ -4,7 +4,7 @@ Wait strategies are useful to detect if a container is ready for testing (i.e.,
 
 ```csharp
 _ = Wait.ForUnixContainer()
-  .UntilPortIsAvailable(80)
+  .UntilInternalTcpPortIsAvailable(80)
   .UntilFileExists("/tmp/foo")
   .UntilFileExists("/tmp/bar")
   .UntilOperationIsSucceeded(() => true, 1)
@@ -51,6 +51,36 @@ _ = Wait.ForUnixContainer()
     .ForStatusCodeMatching(statusCode => statusCode >= HttpStatusCode.OK && statusCode < HttpStatusCode.MultipleChoices));
 ```
 
+## Wait until a TCP port is available
+
+Testcontainers provides two distinct strategies for waiting until a TCP port becomes available, each serving different purposes depending on your testing needs.
+
+### Wait until an internal TCP port is available
+
+`UntilInternalTcpPortIsAvailable(int)` checks if a service inside the container is listening on the specified port by testing connectivity from within the container itself. This strategy verifies that your application or service has actually started and is ready to accept connections.
+
+```csharp
+_ = Wait.ForUnixContainer()
+  .UntilInternalTcpPortIsAvailable(8080);
+```
+
+!!!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.
+
+### Wait until an external TCP port is available
+
+`UntilExternalTcpPortIsAvailable(int)` checks if the port is accessible from the test host to the container. This verifies that the port mapping has been established and the port is reachable externally.
+
+```csharp
+_ = Wait.ForUnixContainer()
+  .UntilExternalTcpPortIsAvailable(8080);
+```
+
+!!!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.
+
 ## Wait until the container is healthy
 
 If the Docker image supports Dockers's [HEALTHCHECK][docker-docs-healthcheck] feature, like the following configuration:

docs/examples/aspnet.md

@@ -106,7 +106,7 @@ _weatherForecastContainer = new ContainerBuilder()
   .WithEnvironment("ASPNETCORE_Kestrel__Certificates__Default__Path", WeatherForecastImage.CertificateFilePath)
   .WithEnvironment("ASPNETCORE_Kestrel__Certificates__Default__Password", WeatherForecastImage.CertificatePassword)
   .WithEnvironment("ConnectionStrings__DefaultConnection", connectionString)
-  .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(WeatherForecastImage.HttpsPort))
+  .WithWaitStrategy(Wait.ForUnixContainer().UntilInternalTcpPortIsAvailable(WeatherForecastImage.HttpsPort))
   .Build();
 ```
 

src/Testcontainers/Configurations/WaitStrategies/IWaitForContainerOS.cs

@@ -65,8 +65,40 @@ public interface IWaitForContainerOS
     /// <param name="waitStrategyModifier">The wait strategy modifier to cancel the readiness check.</param>
     /// <returns>A configured instance of <see cref="IWaitForContainerOS" />.</returns>
     [PublicAPI]
+    [Obsolete("Use UntilInternalTcpPortIsAvailable or UntilExternalTcpPortIsAvailable instead. This method corresponds to the internal variant.")]
     IWaitForContainerOS UntilPortIsAvailable(int port, Action<IWaitStrategy> waitStrategyModifier = null);
 
+    /// <summary>
+    /// Waits until a TCP port is available from within the container itself.
+    /// This verifies that a service inside the container is listening on the specified port.
+    /// </summary>
+    /// <param name="containerPort">The TCP port of the service running inside the container.</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 UntilInternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null);
+
+    /// <summary>
+    /// Waits until a TCP port is available from the test host to the container.
+    /// This verifies that the port is exposed and reachable externally.
+    /// </summary>
+    /// <remarks>
+    /// This does not necessarily mean that the TCP connection to the service running inside
+    /// the container was successful. For container runtimes like Docker Desktop, Podman, or similar,
+    /// this usually only indicates that the port has been mapped and that a connection could be
+    /// established to the host-side proxy that maps the port.
+    ///
+    /// This wait strategy is particularly useful for container runtimes that may take some time
+    /// to finish setting up port mappings. In some cases, other strategies such as log-based
+    /// readiness checks may indicate readiness before the runtime has fully configured the port
+    /// mapping, leading to connection failures. This strategy helps to avoid that race condition.
+    /// </remarks>
+    /// <param name="containerPort">The TCP port of the service running inside the container.</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 UntilExternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null);
+
     /// <summary>
     /// Waits until the file exists.
     /// </summary>

src/Testcontainers/Configurations/WaitStrategies/UntilExternalTcpPortIsAvailable.cs

@@ -0,0 +1,39 @@
+namespace DotNet.Testcontainers.Configurations
+{
+  using System.Net.Sockets;
+  using System.Threading.Tasks;
+  using DotNet.Testcontainers.Containers;
+
+  internal class UntilExternalTcpPortIsAvailable : IWaitUntil
+  {
+    private readonly int _containerPort;
+
+    public UntilExternalTcpPortIsAvailable(int containerPort)
+    {
+      _containerPort = containerPort;
+    }
+
+    public async Task<bool> UntilAsync(IContainer container)
+    {
+      var hostPort = container.GetMappedPublicPort(_containerPort);
+
+      var tcpClient = new TcpClient();
+
+      try
+      {
+        await tcpClient.ConnectAsync(container.Hostname, hostPort)
+          .ConfigureAwait(false);
+
+        return true;
+      }
+      catch
+      {
+        return false;
+      }
+      finally
+      {
+        tcpClient.Dispose();
+      }
+    }
+  }
+}

src/Testcontainers/Configurations/WaitStrategies/UntilUnixPortIsAvailable.cs renamed to src/Testcontainers/Configurations/WaitStrategies/UntilInternalTcpPortIsAvailableOnUnix.cs

@@ -1,9 +1,9 @@
 namespace DotNet.Testcontainers.Configurations
 {
-  internal class UntilUnixPortIsAvailable : UntilUnixCommandIsCompleted
+  internal class UntilInternalTcpPortIsAvailableOnUnix : UntilUnixCommandIsCompleted
   {
-    public UntilUnixPortIsAvailable(int port)
-      : base(string.Format("true && (grep -i ':0*{0:X}' /proc/net/tcp* || nc -vz -w 1 localhost {0:D} || /bin/bash -c '</dev/tcp/localhost/{0:D}')", port))
+    public UntilInternalTcpPortIsAvailableOnUnix(int containerPort)
+      : base(string.Format("true && (grep -i ':0*{0:X}' /proc/net/tcp* || nc -vz -w 1 localhost {0:D} || /bin/bash -c '</dev/tcp/localhost/{0:D}')", containerPort))
     {
     }
   }

src/Testcontainers/Configurations/WaitStrategies/UntilInternalTcpPortIsAvailableOnWindows.cs

@@ -0,0 +1,10 @@
+namespace DotNet.Testcontainers.Configurations
+{
+  internal class UntilInternalTcpPortIsAvailableOnWindows : UntilWindowsCommandIsCompleted
+  {
+    public UntilInternalTcpPortIsAvailableOnWindows(int containerPort)
+      : base($"Exit(-Not((Test-NetConnection -ComputerName 'localhost' -Port {containerPort}).TcpTestSucceeded))")
+    {
+    }
+  }
+}

src/Testcontainers/Configurations/WaitStrategies/UntilWindowsPortIsAvailable.cs

@@ -30,6 +30,9 @@ protected WaitForContainerOS()
     /// <inheritdoc />
     public abstract IWaitForContainerOS UntilPortIsAvailable(int port, Action<IWaitStrategy> waitStrategyModifier = null);
 
+    /// <inheritdoc />
+    public abstract IWaitForContainerOS UntilInternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null);
+
     /// <inheritdoc />
     public virtual IWaitForContainerOS AddCustomWaitStrategy(IWaitUntil waitUntil, Action<IWaitStrategy> waitStrategyModifier = null)
     {
@@ -44,6 +47,12 @@ public virtual IWaitForContainerOS AddCustomWaitStrategy(IWaitUntil waitUntil, A
       return this;
     }
 
+    /// <inheritdoc />
+    public IWaitForContainerOS UntilExternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null)
+    {
+      return AddCustomWaitStrategy(new UntilExternalTcpPortIsAvailable(containerPort), waitStrategyModifier);
+    }
+
     /// <inheritdoc />
     public virtual IWaitForContainerOS UntilFileExists(string filePath, FileSystem fileSystem = FileSystem.Host, Action<IWaitStrategy> waitStrategyModifier = null)
     {

src/Testcontainers/Configurations/WaitStrategies/WaitForContainerOS.cs

@@ -28,7 +28,13 @@ public override IWaitForContainerOS UntilCommandIsCompleted(IEnumerable<string>
     /// <inheritdoc />
     public override IWaitForContainerOS UntilPortIsAvailable(int port, Action<IWaitStrategy> waitStrategyModifier = null)
     {
-      return AddCustomWaitStrategy(new UntilUnixPortIsAvailable(port), waitStrategyModifier);
+      return UntilInternalTcpPortIsAvailable(port, waitStrategyModifier);
+    }
+
+    /// <inheritdoc />
+    public override IWaitForContainerOS UntilInternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null)
+    {
+      return AddCustomWaitStrategy(new UntilInternalTcpPortIsAvailableOnUnix(containerPort), waitStrategyModifier);
     }
   }
 }

src/Testcontainers/Configurations/WaitStrategies/WaitForContainerUnix.cs

@@ -28,7 +28,13 @@ public override IWaitForContainerOS UntilCommandIsCompleted(IEnumerable<string>
     /// <inheritdoc />
     public override IWaitForContainerOS UntilPortIsAvailable(int port, Action<IWaitStrategy> waitStrategyModifier = null)
     {
-      return AddCustomWaitStrategy(new UntilWindowsPortIsAvailable(port), waitStrategyModifier);
+      return UntilInternalTcpPortIsAvailable(port, waitStrategyModifier);
+    }
+
+    /// <inheritdoc />
+    public override IWaitForContainerOS UntilInternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null)
+    {
+      return AddCustomWaitStrategy(new UntilInternalTcpPortIsAvailableOnWindows(containerPort), waitStrategyModifier);
     }
   }
 }