feat: Require explicit container image when creating container builder (#1584)

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

Author: digital88

src/Templates/CSharp/Testcontainers.ModuleName/ModuleNameBuilder.cs

@@ -7,19 +7,40 @@ public sealed class ModuleNameBuilder : ContainerBuilder<ModuleNameBuilder, Modu
     /// <summary>
     /// Initializes a new instance of the <see cref="ModuleNameBuilder" /> class.
     /// </summary>
-    public ModuleNameBuilder()
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>repository:tag</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/..." />.
+    /// </remarks>
+    public ModuleNameBuilder(string image)
         : this(new ModuleNameConfiguration())
     {
         // 1) To change the ContainerBuilder default configuration override the DockerResourceConfiguration property and the "ModuleNameBuilder Init()" method.
-        //    Append the module configuration to base.Init() e.g. base.Init().WithImage("alpine:3.17") to set the modules' default image.
+        //    Append the module configuration to base.Init() e.g. base.Init().WithXXX().
 
         // 2) To customize the ContainerBuilder validation override the "void Validate()" method.
         //    Use Testcontainers' Guard.Argument<TType>(TType, string) or your own guard implementation to validate the module configuration.
 
         // 3) Add custom builder methods to extend the ContainerBuilder capabilities such as "ModuleNameBuilder WithModuleNameConfig(object)".
         //    Merge the current module configuration with a new instance of the immutable ModuleNameConfiguration type to update the module configuration.
 
-        // DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        // DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ModuleNameBuilder" /> class.
+    /// </summary>
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/..." />.
+    /// </remarks>
+    public ModuleNameBuilder(IImage image)
+        : this(new ModuleNameConfiguration())
+    {
+        // DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>

src/Testcontainers.ActiveMq/ArtemisBuilder.cs

@@ -4,6 +4,7 @@ namespace Testcontainers.ActiveMq;
 [PublicAPI]
 public sealed class ArtemisBuilder : ContainerBuilder<ArtemisBuilder, ArtemisContainer, ActiveMqConfiguration>
 {
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public const string ArtemisImage = "apache/activemq-artemis:2.31.2";
 
     public const ushort ArtemisMainPort = 61616;
@@ -17,10 +18,42 @@ public sealed class ArtemisBuilder : ContainerBuilder<ArtemisBuilder, ArtemisCon
     /// <summary>
     /// Initializes a new instance of the <see cref="ArtemisBuilder" /> class.
     /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public ArtemisBuilder()
+        : this(ArtemisImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ArtemisBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>apache/activemq-artemis:2.31.2</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/apache/activemq-artemis/tags" />.
+    /// </remarks>
+    public ArtemisBuilder(string image)
+        : this(new ActiveMqConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ArtemisBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/apache/activemq-artemis/tags" />.
+    /// </remarks>
+    public ArtemisBuilder(IImage image)
         : this(new ActiveMqConfiguration())
     {
-        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>
@@ -69,7 +102,6 @@ public override ArtemisContainer Build()
     protected override ArtemisBuilder Init()
     {
         return base.Init()
-            .WithImage(ArtemisImage)
             .WithPortBinding(ArtemisMainPort, true)
             .WithPortBinding(ArtemisConsolePort, true)
             .WithUsername(DefaultUsername)

src/Testcontainers.ActiveMq/Usings.cs

@@ -4,4 +4,5 @@
 global using DotNet.Testcontainers.Builders;
 global using DotNet.Testcontainers.Configurations;
 global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Images;
 global using JetBrains.Annotations;

src/Testcontainers.ArangoDb/ArangoDbBuilder.cs

@@ -4,6 +4,7 @@ namespace Testcontainers.ArangoDb;
 [PublicAPI]
 public sealed class ArangoDbBuilder : ContainerBuilder<ArangoDbBuilder, ArangoDbContainer, ArangoDbConfiguration>
 {
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public const string ArangoDbImage = "arangodb:3.11.5";
 
     public const ushort ArangoDbPort = 8529;
@@ -15,10 +16,42 @@ public sealed class ArangoDbBuilder : ContainerBuilder<ArangoDbBuilder, ArangoDb
     /// <summary>
     /// Initializes a new instance of the <see cref="ArangoDbBuilder" /> class.
     /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public ArangoDbBuilder()
+        : this(ArangoDbImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ArangoDbBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>arangodb:3.11.5</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/_/arangodb/tags" />.
+    /// </remarks>
+    public ArangoDbBuilder(string image)
+        : this(new ArangoDbConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ArangoDbBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/_/arangodb/tags" />.
+    /// </remarks>
+    public ArangoDbBuilder(IImage image)
         : this(new ArangoDbConfiguration())
     {
-        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>
@@ -56,7 +89,6 @@ public override ArangoDbContainer Build()
     protected override ArangoDbBuilder Init()
     {
         return base.Init()
-            .WithImage(ArangoDbImage)
             .WithPortBinding(ArangoDbPort, true)
             .WithPassword(DefaultPassword)
             .WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("Have fun!"));

src/Testcontainers.ArangoDb/Usings.cs

@@ -4,4 +4,5 @@
 global using DotNet.Testcontainers.Builders;
 global using DotNet.Testcontainers.Configurations;
 global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Images;
 global using JetBrains.Annotations;

src/Testcontainers.Azurite/AzuriteBuilder.cs

@@ -4,6 +4,7 @@ namespace Testcontainers.Azurite;
 [PublicAPI]
 public sealed class AzuriteBuilder : ContainerBuilder<AzuriteBuilder, AzuriteContainer, AzuriteConfiguration>
 {
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public const string AzuriteImage = "mcr.microsoft.com/azure-storage/azurite:3.28.0";
 
     public const ushort BlobPort = 10000;
@@ -28,10 +29,40 @@ static AzuriteBuilder()
     /// <summary>
     /// Initializes a new instance of the <see cref="AzuriteBuilder" /> class.
     /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public AzuriteBuilder()
+        : this(AzuriteImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AzuriteBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>mcr.microsoft.com/azure-storage/azurite:3.28.0</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/microsoft/azure-storage-azurite/tags" />.
+    /// </remarks>
+    public AzuriteBuilder(string image)
+        : this(new AzuriteConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AzuriteBuilder" /> class.
+    /// </summary>
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/microsoft/azure-storage-azurite/tags" />.
+    /// </remarks>
+    public AzuriteBuilder(IImage image)
         : this(new AzuriteConfiguration())
     {
-        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>
@@ -97,7 +128,6 @@ public override AzuriteContainer Build()
     protected override AzuriteBuilder Init()
     {
         return base.Init()
-            .WithImage(AzuriteImage)
             .WithPortBinding(BlobPort, true)
             .WithPortBinding(QueuePort, true)
             .WithPortBinding(TablePort, true)

src/Testcontainers.Azurite/Usings.cs

@@ -5,4 +5,5 @@
 global using DotNet.Testcontainers.Builders;
 global using DotNet.Testcontainers.Configurations;
 global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Images;
 global using JetBrains.Annotations;

src/Testcontainers.BigQuery/BigQueryBuilder.cs

@@ -4,6 +4,7 @@ namespace Testcontainers.BigQuery;
 [PublicAPI]
 public sealed class BigQueryBuilder : ContainerBuilder<BigQueryBuilder, BigQueryContainer, BigQueryConfiguration>
 {
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public const string BigQueryImage = "ghcr.io/goccy/bigquery-emulator:0.4";
 
     public const ushort BigQueryPort = 9050;
@@ -13,10 +14,42 @@ public sealed class BigQueryBuilder : ContainerBuilder<BigQueryBuilder, BigQuery
     /// <summary>
     /// Initializes a new instance of the <see cref="BigQueryBuilder" /> class.
     /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public BigQueryBuilder()
+        : this(BigQueryImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BigQueryBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>ghcr.io/goccy/bigquery-emulator:0.4</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://github.com/goccy/bigquery-emulator/pkgs/container/bigquery-emulator" />.
+    /// </remarks>
+    public BigQueryBuilder(string image)
+        : this(new BigQueryConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BigQueryBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://github.com/goccy/bigquery-emulator/pkgs/container/bigquery-emulator" />.
+    /// </remarks>
+    public BigQueryBuilder(IImage image)
         : this(new BigQueryConfiguration())
     {
-        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>
@@ -53,7 +86,6 @@ public override BigQueryContainer Build()
     protected override BigQueryBuilder Init()
     {
         return base.Init()
-            .WithImage(BigQueryImage)
             .WithPortBinding(BigQueryPort, true)
             .WithProject(DefaultProjectId)
             .WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("(?s).*listening.*$"));

src/Testcontainers.BigQuery/Usings.cs

@@ -3,4 +3,5 @@
 global using DotNet.Testcontainers.Builders;
 global using DotNet.Testcontainers.Configurations;
 global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Images;
 global using JetBrains.Annotations;

src/Testcontainers.Bigtable/BigtableBuilder.cs

@@ -4,17 +4,50 @@ namespace Testcontainers.Bigtable;
 [PublicAPI]
 public sealed class BigtableBuilder : ContainerBuilder<BigtableBuilder, BigtableContainer, BigtableConfiguration>
 {
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public const string GoogleCloudCliImage = "gcr.io/google.com/cloudsdktool/google-cloud-cli:446.0.1-emulators";
 
     public const ushort BigtablePort = 9000;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="BigtableBuilder" /> class.
     /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
     public BigtableBuilder()
+        : this(GoogleCloudCliImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BigtableBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// The full Docker image name, including the image repository and tag
+    /// (e.g., <c>gcr.io/google.com/cloudsdktool/google-cloud-cli:446.0.1-emulators</c>).
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://console.cloud.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli" />.
+    /// </remarks>
+    public BigtableBuilder(string image)
+        : this(new BigtableConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BigtableBuilder" /> class.
+    /// </summary>
+    /// <param name="image">
+    /// An <see cref="IImage" /> instance that specifies the Docker image to be used
+    /// for the container builder configuration.
+    /// </param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://console.cloud.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli" />.
+    /// </remarks>
+    public BigtableBuilder(IImage image)
         : this(new BigtableConfiguration())
     {
-        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
     }
 
     /// <summary>
@@ -41,7 +74,6 @@ public override BigtableContainer Build()
     protected override BigtableBuilder Init()
     {
         return base.Init()
-            .WithImage(GoogleCloudCliImage)
             .WithPortBinding(BigtablePort, true)
             .WithEntrypoint("gcloud")
             .WithCommand("beta", "emulators", "bigtable", "start", "--host-port", "0.0.0.0:" + BigtablePort)