feat: Add image name substitution hook (#1710)

Author: HofmeisterAn

docs/custom_configuration/index.md

@@ -61,6 +61,28 @@ Setting the context to `tcc` in this example will use the Docker host running at
     docker.context=tcc
     ```
 
+## Substitute image names
+
+Testcontainers supports substituting an image name with an alternative on the fly, for example to pull from a private registry mirror instead of Docker Hub. This is useful if you have complex rules that a simple prefix cannot express, such as a non-deterministic name mapping, rules depending on the developer or environment, or auditing and restricting the images used in a build.
+
+Set `TestcontainersSettings.ImageNameSubstitution` to a function that receives the original `IImage` and returns the image to use instead. Return the original image (or `null`) to leave it unchanged.
+
+Configure the substitution once before any test resources are created. A static class with a [`[ModuleInitializer]`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.moduleinitializerattribute) method runs automatically before the first type in the test assembly is used:
+
+```csharp
+internal static class TestcontainersConfiguration
+{
+  [ModuleInitializer]
+  public static void Initialize()
+  {
+    TestcontainersSettings.ImageNameSubstitution = image
+      => new DockerImage(image.Repository, "registry.mycompany.com", image.Tag, image.Digest, image.Platform);
+  }
+}
+```
+
+The substitution runs first, then the Docker Hub image name prefix (`TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX`) is applied to the substituted image. As with any image, the prefix is only added when the image does not already specify a registry, so a substitution that sets a registry (such as the examples above) takes precedence over the prefix.
+
 ## Automatically modify Docker Hub image names
 
 Testcontainers can automatically add a registry prefix to Docker Hub image names used in your tests. This is handy if you use a private registry that mirrors Docker Hub images with predictable naming.

src/Testcontainers/Builders/ContainerBuilder`3.cs

@@ -92,7 +92,7 @@ public TBuilderEntity WithImage(string image)
     /// <inheritdoc />
     public TBuilderEntity WithImage(IImage image)
     {
-      return Clone(new ContainerConfiguration(image: image.ApplyHubImageNamePrefix()));
+      return Clone(new ContainerConfiguration(image: image.ApplyImageNameSubstitution()));
     }
 
     /// <inheritdoc />

src/Testcontainers/Builders/ImageFromDockerfileBuilder.cs

@@ -60,7 +60,7 @@ public ImageFromDockerfileBuilder WithName(string name)
     /// <inheritdoc />
     public ImageFromDockerfileBuilder WithName(IImage image)
     {
-      return Merge(DockerResourceConfiguration, new ImageFromDockerfileConfiguration(image: image.ApplyHubImageNamePrefix()));
+      return Merge(DockerResourceConfiguration, new ImageFromDockerfileConfiguration(image: image.ApplyImageNameSubstitution()));
     }
 
     /// <inheritdoc />

src/Testcontainers/Configurations/TestcontainersSettings.cs

@@ -137,6 +137,20 @@ static TestcontainersSettings()
     public static TimeSpan? WaitStrategyTimeout { get; set; }
       = EnvironmentConfiguration.Instance.GetWaitStrategyTimeout() ?? PropertiesFileConfiguration.Instance.GetWaitStrategyTimeout();
 
+    /// <summary>
+    /// Gets or sets a function that substitutes the image name before an image is pulled.
+    /// </summary>
+    /// <remarks>
+    /// This allows replacing an image name with an alternative on the fly, for example to pull
+    /// from a private registry mirror instead of Docker Hub. The substitution runs first; the
+    /// Docker Hub image name prefix (see <see cref="HubImageNamePrefix" />) is then applied to
+    /// the substituted image, but only if that image does not already specify a registry.
+    /// A substitution that sets a registry therefore takes precedence over the prefix.
+    /// Return the original image (or <see langword="null" />) to leave it unchanged.
+    /// </remarks>
+    [CanBeNull]
+    public static Func<IImage, IImage> ImageNameSubstitution { get; set; }
+
     /// <summary>
     /// Gets or sets the host operating system.
     /// </summary>

src/Testcontainers/Images/IImageExtensions.cs

@@ -8,12 +8,27 @@ namespace DotNet.Testcontainers.Images
   internal static class IImageExtensions
   {
     /// <summary>
-    /// Applies the Docker Hub image name prefix if it is configured.
+    /// Applies the configured image name substitution and then the Docker Hub image name prefix.
     /// </summary>
     /// <param name="image">The original <see cref="IImage" /> instance.</param>
     /// <returns>
-    /// A new <see cref="IImage" /> instance with the Docker Hub image name prefix
-    /// applied, or the original instance if no prefix is set.
+    /// A new <see cref="IImage" /> instance with the configured substitution and Docker Hub image
+    /// name prefix applied, or the original instance if neither is configured.
+    /// </returns>
+    public static IImage ApplyImageNameSubstitution(this IImage image)
+    {
+      var substitution = TestcontainersSettings.ImageNameSubstitution;
+      var substitute = substitution == null ? image : substitution(image) ?? image;
+      return substitute.ApplyHubImageNamePrefix();
+    }
+
+    /// <summary>
+    /// Applies the configured Docker Hub image name prefix.
+    /// </summary>
+    /// <param name="image">The original <see cref="IImage" /> instance.</param>
+    /// <returns>
+    /// A new <see cref="IImage" /> instance with the configured Docker Hub image name prefix
+    /// applied, or the original instance if no prefix is configured.
     /// </returns>
     public static IImage ApplyHubImageNamePrefix(this IImage image)
     {

tests/Testcontainers.Tests/Unit/Configurations/DockerImageNameSubstitutionTest.cs

@@ -10,8 +10,108 @@ namespace DotNet.Testcontainers.Tests.Unit
   [CollectionDefinition(nameof(DockerImageNameSubstitutionTest), DisableParallelization = true)]
   public static class DockerImageNameSubstitutionTest
   {
+    public abstract class ImageNameSubstitutionTest : IDisposable
+    {
+      private bool _disposed;
+
+      protected ImageNameSubstitutionTest()
+      {
+        Reset();
+      }
+
+      public void Dispose()
+      {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+      }
+
+      protected virtual void Dispose(bool disposing)
+      {
+        if (_disposed)
+        {
+          return;
+        }
+
+        if (disposing)
+        {
+          Reset();
+        }
+
+        _disposed = true;
+      }
+
+      private static void Reset()
+      {
+        TestcontainersSettings.HubImageNamePrefix = string.Empty;
+        TestcontainersSettings.ImageNameSubstitution = null;
+      }
+    }
+
     [Collection(nameof(DockerImageNameSubstitutionTest))]
-    public sealed class HubImageNamePrefixIsSet : IDisposable
+    public sealed class ImageNameSubstitutionIsSet : ImageNameSubstitutionTest
+    {
+      [Fact]
+      public void SubstitutesImageNameForStringConfiguration()
+      {
+        // Given
+        TestcontainersSettings.ImageNameSubstitution = image => new DockerImage("my.proxy.com/mirror/" + image.FullName);
+
+        // When
+        IContainer container = new ContainerBuilder("bar:1.0.0")
+          .Build();
+
+        // Then
+        Assert.Equal("my.proxy.com/mirror/bar:1.0.0", container.Image.FullName);
+      }
+
+      [Fact]
+      public void SubstitutesImageNameForObjectConfiguration()
+      {
+        // Given
+        TestcontainersSettings.ImageNameSubstitution = image => new DockerImage("my.proxy.com/mirror/" + image.FullName);
+
+        IImage image = new DockerImage("bar:1.0.0");
+
+        // When
+        IContainer container = new ContainerBuilder(image)
+          .Build();
+
+        // Then
+        Assert.Equal("my.proxy.com/mirror/bar:1.0.0", container.Image.FullName);
+      }
+
+      [Fact]
+      public void SubstitutesImageNameBeforeHubImageNamePrefix()
+      {
+        // Given
+        TestcontainersSettings.HubImageNamePrefix = "my.proxy.com";
+        TestcontainersSettings.ImageNameSubstitution = image => new DockerImage("registry.azurecr.io/" + image.FullName);
+
+        // When
+        IContainer container = new ContainerBuilder("bar:1.0.0")
+          .Build();
+
+        // Then
+        Assert.Equal("registry.azurecr.io/bar:1.0.0", container.Image.FullName);
+      }
+
+      [Fact]
+      public void KeepsOriginalImageWhenSubstitutionReturnsNull()
+      {
+        // Given
+        TestcontainersSettings.ImageNameSubstitution = _ => null;
+
+        // When
+        IContainer container = new ContainerBuilder("bar:1.0.0")
+          .Build();
+
+        // Then
+        Assert.Equal("bar:1.0.0", container.Image.FullName);
+      }
+    }
+
+    [Collection(nameof(DockerImageNameSubstitutionTest))]
+    public sealed class HubImageNamePrefixIsSet : ImageNameSubstitutionTest
     {
       public static TheoryData<string, string, string> Substitutions { get; }
         = new TheoryData<string, string, string>
@@ -60,21 +160,11 @@ public void PrependForObjectConfiguration(string hubImageNamePrefix, string imag
         // Then
         Assert.Equal(expectedFullName, container.Image.FullName);
       }
-
-      public void Dispose()
-      {
-        TestcontainersSettings.HubImageNamePrefix = string.Empty;
-      }
     }
 
     [Collection(nameof(DockerImageNameSubstitutionTest))]
-    public sealed class HubImageNamePrefixIsNotSet
+    public sealed class HubImageNamePrefixIsNotSet : ImageNameSubstitutionTest
     {
-      public HubImageNamePrefixIsNotSet()
-      {
-        TestcontainersSettings.HubImageNamePrefix = string.Empty;
-      }
-
       [Fact]
       public void DoNotPrependForStringConfiguration()
       {