feat: Support getting all mapped ports (#1485)

Author: HofmeisterAn

src/Testcontainers/Containers/DockerContainer.cs

@@ -252,6 +252,13 @@ public long HealthCheckFailingStreak
       }
     }
 
+    /// <inheritdoc />
+    public ushort GetMappedPublicPort()
+    {
+      using var enumerator = GetMappedPublicPorts().Values.GetEnumerator();
+      return enumerator.MoveNext() ? enumerator.Current : throw new InvalidOperationException("No mapped port found.");
+    }
+
     /// <inheritdoc />
     public ushort GetMappedPublicPort(int containerPort)
     {
@@ -265,16 +272,40 @@ public ushort GetMappedPublicPort(string containerPort)
 
       var qualifiedContainerPort = ContainerConfigurationConverter.GetQualifiedPort(containerPort);
 
-      if (_container.NetworkSettings.Ports.TryGetValue(qualifiedContainerPort, out var portBindings) && ushort.TryParse(portBindings[0].HostPort, out var publicPort))
+      if (_container.NetworkSettings.Ports.TryGetValue(qualifiedContainerPort, out var portBindings) && ushort.TryParse(portBindings[0].HostPort, out var hostPort))
       {
-        return publicPort;
+        return hostPort;
       }
       else
       {
         throw new InvalidOperationException($"Exposed port {qualifiedContainerPort} is not mapped.");
       }
     }
 
+    /// <inheritdoc />
+    public IReadOnlyDictionary<ushort, ushort> GetMappedPublicPorts()
+    {
+      ThrowIfResourceNotFound();
+
+      return _container.NetworkSettings.Ports
+        .Where(
+          kvp =>
+          {
+            return kvp.Key.Contains('/') && kvp.Value != null && kvp.Value.Count > 0;
+          })
+        .ToDictionary(
+          kvp =>
+          {
+            var containerPort = kvp.Key.Substring(0, kvp.Key.IndexOf('/'));
+            return ushort.Parse(containerPort);
+          },
+          kvp =>
+          {
+            var hostPort = kvp.Value[0].HostPort;
+            return ushort.Parse(hostPort);
+          });
+    }
+
     /// <inheritdoc />
     public Task<long> GetExitCodeAsync(CancellationToken ct = default)
     {

src/Testcontainers/Containers/IContainer.cs

@@ -163,6 +163,12 @@ public interface IContainer : IAsyncDisposable
     /// </summary>
     long HealthCheckFailingStreak { get; }
 
+    /// <summary>
+    /// Resolves the first public assigned host port.
+    /// </summary>
+    /// <returns>Returns the first public assigned host port.</returns>
+    ushort GetMappedPublicPort();
+
     /// <summary>
     /// Resolves the public assigned host port.
     /// </summary>
@@ -171,7 +177,7 @@ public interface IContainer : IAsyncDisposable
     /// </remarks>
     /// <param name="containerPort">The container port.</param>
     /// <returns>Returns the public assigned host port.</returns>
-    /// <exception cref="InvalidOperationException">Container has not been created.</exception>
+    /// <exception cref="InvalidOperationException">Container has not been created, or no mapped port was found.</exception>
     ushort GetMappedPublicPort(int containerPort);
 
     /// <summary>
@@ -185,6 +191,13 @@ public interface IContainer : IAsyncDisposable
     /// <exception cref="InvalidOperationException">Container has not been created.</exception>
     ushort GetMappedPublicPort(string containerPort);
 
+    /// <summary>
+    /// Resolves all public assigned host ports.
+    /// </summary>
+    /// <returns>Returns all public assigned host ports.</returns>
+    /// <exception cref="InvalidOperationException">Container has not been created.</exception>
+    IReadOnlyDictionary<ushort, ushort> GetMappedPublicPorts();
+
     /// <summary>
     /// Gets the container exit code.
     /// </summary>
@@ -284,15 +297,15 @@ public interface IContainer : IAsyncDisposable
     /// </summary>
     /// <param name="filePath">An absolute path or a name value within the container.</param>
     /// <param name="ct">Cancellation token.</param>
-    /// <returns>Task that completes when the file has been read.</returns>
+    /// <returns>A task that completes when the file has been read.</returns>
     Task<byte[]> ReadFileAsync(string filePath, CancellationToken ct = default);
 
     /// <summary>
     /// Executes a command in the container.
     /// </summary>
     /// <param name="command">Shell command.</param>
     /// <param name="ct">Cancellation token.</param>
-    /// <returns>Task that completes when the shell command has been executed.</returns>
+    /// <returns>A task that completes when the shell command has been executed.</returns>
     Task<ExecResult> ExecAsync(IList<string> command, CancellationToken ct = default);
   }
 }

src/Testcontainers/Images/IgnoreFile.cs

@@ -185,17 +185,17 @@ public string Replace(string input)
       /// <inheritdoc />
       public string Replace(string input)
       {
-        // Find last non recursive wildcard in pattern.
+        // Find last non-recursive wildcard in pattern.
         var index = input.LastIndexOf("*", StringComparison.Ordinal);
 
-        // If last character is a non recursive wildcard, add the end of string regular expression.
+        // If last character is a non-recursive wildcard, add the end of string regular expression.
         if (input.EndsWith("*", StringComparison.Ordinal) && index >= 0)
         {
           input = input.Remove(index, 1).Insert(index, $"{MatchAllExceptPathSeparator}?$");
           index = -1;
         }
 
-        // Replace the last non recursive wildcard with a match-zero-or-one quantifier regular expression.
+        // Replace the last non-recursive wildcard with a match-zero-or-one quantifier regular expression.
 #if NETSTANDARD2_0
         if (input.Contains("*") && index >= 0)
 #else
@@ -205,7 +205,7 @@ public string Replace(string input)
           input = input.Remove(index, 1).Insert(index, $"{MatchAllExceptPathSeparator}?");
         }
 
-        // Replace remaining non recursive wildcards.
+        // Replace remaining non-recursive wildcards.
         return input.Replace("*", MatchAllExceptPathSeparator);
       }
     }

tests/Testcontainers.Platform.Linux.Tests/PortBindingTest.cs

@@ -0,0 +1,65 @@
+namespace Testcontainers.Tests;
+
+public abstract class PortBindingTest : IAsyncLifetime
+{
+    private readonly IContainer _container;
+
+    private PortBindingTest(ushort[] expectedPorts)
+    {
+        var containerBuilder = new ContainerBuilder().WithImage(CommonImages.Alpine).WithEntrypoint(CommonCommands.SleepInfinity);
+        _container = expectedPorts.Aggregate(containerBuilder, (builder, port) => builder.WithPortBinding(port, true)).Build();
+    }
+
+    public async ValueTask InitializeAsync()
+    {
+        await _container.StartAsync()
+            .ConfigureAwait(false);
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await DisposeAsyncCore()
+            .ConfigureAwait(false);
+
+        GC.SuppressFinalize(this);
+    }
+
+    protected virtual ValueTask DisposeAsyncCore()
+    {
+        return _container.DisposeAsync();
+    }
+
+    public abstract class MappedPublicPorts : PortBindingTest
+    {
+        private readonly ushort[] _expectedPorts;
+
+        protected MappedPublicPorts(ushort[] expectedPorts)
+            : base(expectedPorts)
+        {
+            _expectedPorts = expectedPorts;
+        }
+
+        [Fact]
+        public void ShouldReturnExpectedPorts()
+        {
+            var actualPorts = _container.GetMappedPublicPorts();
+            Assert.Equal(_expectedPorts, actualPorts.Keys);
+        }
+
+        [Fact]
+        public void ShouldThrowWhenNoPortsExist()
+        {
+            var exception = Record.Exception(() => _container.GetMappedPublicPort());
+            Assert.Equal(exception == null, _expectedPorts.Length > 0);
+        }
+    }
+
+    public sealed class NoPortBindingTest()
+        : MappedPublicPorts(Array.Empty<ushort>());
+
+    public sealed class SinglePortBindingTest()
+        : MappedPublicPorts(new ushort[] { 8080 });
+
+    public sealed class MultiplePortBindingTest()
+        : MappedPublicPorts(new ushort[] { 8080, 8081 });
+}