[testcontainers#466] #IMPLEMENT 'assemblyName: DotNet.Testcontainers;…

… function: Image Name Substitution'

src/DotNet.Testcontainers/Builders/ITestcontainersBuilder.cs

@@ -30,10 +30,10 @@ public interface ITestcontainersBuilder<out TDockerContainer> : IAbstractBuilder
     /// <summary>
     /// Sets the Docker image, which is used to create the Testcontainer instances.
     /// </summary>
-    /// <param name="image">The Docker image.</param>
+    /// <param name="imageName">The Docker image.</param>
     /// <returns>A configured instance of <see cref="ITestcontainersBuilder{TDockerContainer}" />.</returns>
     [PublicAPI]
-    ITestcontainersBuilder<TDockerContainer> WithImage(string image);
+    ITestcontainersBuilder<TDockerContainer> WithImage(string imageName);
 
     /// <summary>
     /// Sets the Docker image, which is used to create the Testcontainer instances.

src/DotNet.Testcontainers/Builders/TestcontainersBuilder.cs

@@ -78,15 +78,16 @@ public ITestcontainersBuilder<TDockerContainer> ConfigureContainer(Action<TDocke
     }
 
     /// <inheritdoc cref="ITestcontainersBuilder{TDockerContainer}" />
-    public ITestcontainersBuilder<TDockerContainer> WithImage(string image)
+    public ITestcontainersBuilder<TDockerContainer> WithImage(string imageName)
     {
-      return this.WithImage(new DockerImage(image));
+      return this.WithImage(new DockerImage(imageName));
     }
 
     /// <inheritdoc cref="ITestcontainersBuilder{TDockerContainer}" />
     public ITestcontainersBuilder<TDockerContainer> WithImage(IDockerImage image)
     {
-      return this.MergeNewConfiguration(new TestcontainersConfiguration(image: image));
+      var modifiedImage = MaybeApplyImageNameSubstitution(image);
+      return this.MergeNewConfiguration(new TestcontainersConfiguration(image: modifiedImage));
     }
 
     /// <inheritdoc cref="ITestcontainersBuilder{TDockerContainer}" />
@@ -330,5 +331,22 @@ protected virtual ITestcontainersBuilder<TDockerContainer> MergeNewConfiguration
       var updatedDockerResourceConfiguration = new TestcontainersConfiguration(endpoint, dockerRegistryAuthConfig, image, name, hostname, workingDirectory, entrypoint, command, environments, labels, exposedPorts, portBindings, mounts, networks, outputConsumer, waitStrategies, startupCallback, autoRemove, privileged);
       return new TestcontainersBuilder<TDockerContainer>(updatedDockerResourceConfiguration, moduleConfiguration ?? this.mergeModuleConfiguration);
     }
+
+    private static IDockerImage MaybeApplyImageNameSubstitution(IDockerImage originalImage)
+    {
+      var applySubstitution = !string.IsNullOrWhiteSpace(TestcontainersSettings.DockerHubImagePrefix);
+      if (!applySubstitution)
+      {
+        return originalImage;
+      }
+
+      var hostedOnDockerHub = string.IsNullOrWhiteSpace(originalImage.GetHostname());
+      if (!hostedOnDockerHub)
+      {
+        return originalImage;
+      }
+
+      return new DockerImage(originalImage.Repository.Length == 0 ? TestcontainersSettings.DockerHubImagePrefix : $"{TestcontainersSettings.DockerHubImagePrefix}/{originalImage.Repository}", originalImage.Name, originalImage.Tag);
+    }
   }
 }

src/DotNet.Testcontainers/Configurations/Containers/ITestcontainersConfiguration.cs

@@ -4,6 +4,7 @@ namespace DotNet.Testcontainers.Configurations
   using System.Collections.Generic;
   using System.Threading;
   using System.Threading.Tasks;
+  using Builders;
   using DotNet.Testcontainers.Containers;
   using DotNet.Testcontainers.Images;
   using DotNet.Testcontainers.Networks;

src/DotNet.Testcontainers/Configurations/TestcontainersSettings.cs

@@ -17,6 +17,11 @@ public static class TestcontainersSettings
     public static bool ResourceReaperEnabled { get; set; }
       = true;
 
+    /// <summary>
+    /// Gets or sets a prefix to prepend to image names for images hosted on DockerHub.
+    /// </summary>
+    public static string DockerHubImagePrefix { get; set; }
+
     /// <summary>
     /// Gets or sets the logger.
     /// </summary>

src/DotNet.Testcontainers/Containers/IDockerContainer.cs

@@ -96,6 +96,15 @@ public interface IRunningDockerContainer
     [NotNull]
     string Hostname { get; }
 
+    /// <summary>
+    /// Gets the Testcontainers image name.
+    /// </summary>
+    /// <value>
+    /// Returns the name of the image this container has been created from.
+    /// </value>
+    [NotNull]
+    string ImageName { get; }
+
     /// <summary>
     /// Gets the Testcontainers state.
     /// </summary>

src/DotNet.Testcontainers/Containers/TestcontainersContainer.cs

@@ -103,6 +103,15 @@ public string Hostname
       }
     }
 
+    /// <inheritdoc />
+    public string ImageName
+    {
+      get
+      {
+        return this.configuration.Image.FullName;
+      }
+    }
+
     /// <inheritdoc />
     public TestcontainersState State
     {

tests/DotNet.Testcontainers.Tests/Unit/Builders/TestcontainerBuilderTest.cs

@@ -0,0 +1,68 @@
+namespace DotNet.Testcontainers.Tests.Unit.Builders;
+
+using DotNet.Testcontainers.Builders;
+using DotNet.Testcontainers.Configurations;
+using DotNet.Testcontainers.Containers;
+using Images;
+using Xunit;
+
+public class TestcontainerBuilderTest
+{
+  [Theory]
+  [InlineData("my.proxy.com", "bar", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:latest", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:1.0.0", "my.proxy.com/bar:1.0.0")]
+  [InlineData("my.proxy.com/my-path", "bar:1.0.0", "my.proxy.com/my-path/bar:1.0.0")]
+  [InlineData("my.proxy.com:443", "bar:1.0.0", "my.proxy.com:443/bar:1.0.0")]
+  [InlineData("my.proxy.com", "foo/bar:1.0.0", "my.proxy.com/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com/my-path", "foo/bar:1.0.0", "my.proxy.com/my-path/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com:443", "foo/bar:1.0.0", "my.proxy.com:443/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com:443/my-path", "foo/bar:1.0.0", "my.proxy.com:443/my-path/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io/foo/bar:1.0.0", "myregistry.azurecr.io/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io:443/foo/bar:1.0.0", "myregistry.azurecr.io:443/foo/bar:1.0.0")]
+  public void ImageNameFromStringIsPrefixedWhenPrefixIsSet(string prefix, string originalImageName, string expectedName)
+  {
+    TestcontainersSettings.DockerHubImagePrefix = prefix;
+
+    var container = new TestcontainersBuilder<TestcontainersContainer>()
+      .WithImage(originalImageName)
+      .Build();
+
+    Assert.Equal(expectedName, container.ImageName);
+  }
+
+  [Theory]
+  [InlineData("my.proxy.com", "bar", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:latest", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:1.0.0", "my.proxy.com/bar:1.0.0")]
+  [InlineData("my.proxy.com/my-path", "bar:1.0.0", "my.proxy.com/my-path/bar:1.0.0")]
+  [InlineData("my.proxy.com:443", "bar:1.0.0", "my.proxy.com:443/bar:1.0.0")]
+  [InlineData("my.proxy.com", "foo/bar:1.0.0", "my.proxy.com/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com/my-path", "foo/bar:1.0.0", "my.proxy.com/my-path/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com:443", "foo/bar:1.0.0", "my.proxy.com:443/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com:443/my-path", "foo/bar:1.0.0", "my.proxy.com:443/my-path/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io/foo/bar:1.0.0", "myregistry.azurecr.io/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io:443/foo/bar:1.0.0", "myregistry.azurecr.io:443/foo/bar:1.0.0")]
+  public void ImageNameFromClassIsPrefixedWhenPrefixIsSet(string prefix, string originalImageName, string expectedName)
+  {
+    TestcontainersSettings.DockerHubImagePrefix = prefix;
+
+    var container = new TestcontainersBuilder<TestcontainersContainer>()
+      .WithImage(new DockerImage(originalImageName))
+      .Build();
+
+    Assert.Equal(expectedName, container.ImageName);
+  }
+
+  [Fact]
+  public void ImageNameIsNotPrefixedWhenPrefixIsNotSet()
+  {
+    TestcontainersSettings.DockerHubImagePrefix = null;
+
+    var container = new TestcontainersBuilder<TestcontainersContainer>()
+      .WithImage("foo/bar:1.0.0")
+      .Build();
+
+    Assert.Equal("foo/bar:1.0.0", container.ImageName);
+  }
+}