feat: Throw if container not running (#1550)

Author: HofmeisterAn

docs/api/wait_strategies.md

@@ -19,6 +19,17 @@ _ = Wait.ForUnixContainer()
 
 Besides configuring the wait strategy, cancelling a container start can always be done utilizing a [CancellationToken](create_docker_container.md#canceling-a-container-start).
 
+## Wait strategy modes
+
+Wait strategy modes define how Testcontainers for .NET handles container readiness checks. By default, wait strategies assume the container remains running throughout the startup. If a container exits unexpectedly during startup, Testcontainers for .NET will throw a `ContainerNotRunningException` containing the exit code and logs.
+
+Some containers are intended to stop after completing short-lived tasks like migrations or setup scripts. In these cases, the container exit is expected, not a failure. Use `WaitStrategyMode.OneShot` to treat a normal exit as successful rather than throwing an exception.
+
+```csharp
+_ = Wait.ForUnixContainer()
+  .UntilMessageIsLogged("Migration completed", o => o.WithMode(WaitStrategyMode.OneShot));
+```
+
 ## Wait until an HTTP(S) endpoint is available
 
 You can choose to wait for an HTTP(S) endpoint to return a particular HTTP response status code or to match a predicate. The default configuration tries to access the HTTP endpoint running inside the container. Chose `ForPort(ushort)` or `ForPath(string)` to adjust the endpoint or `UsingTls()` to switch to HTTPS. When using `UsingTls()` port 443 is used as a default. If your container exposes a different HTTPS port, make sure that the correct waiting port is configured accordingly.

docs/custom_configuration/index.md

@@ -81,13 +81,13 @@ Once configured, Testcontainers will rewrite Docker Hub image names by adding th
 For example, the image:
 
 ```
-testcontainers/helloworld:1.2.0
+testcontainers/helloworld:1.3.0
 ```
 
 will automatically become:
 
 ```
-registry.mycompany.com/mirror/testcontainers/helloworld:1.2.0
+registry.mycompany.com/mirror/testcontainers/helloworld:1.3.0
 ```
 
 ## Enable logging

docs/index.md

@@ -7,8 +7,8 @@ dotnet add package Testcontainers
 ```csharp title="Run the Hello World container"
 // Create a new instance of a container.
 var container = new ContainerBuilder()
-  // Set the image for the container to "testcontainers/helloworld:1.2.0".
-  .WithImage("testcontainers/helloworld:1.2.0")
+  // Set the image for the container to "testcontainers/helloworld:1.3.0".
+  .WithImage("testcontainers/helloworld:1.3.0")
   // Bind port 8080 of the container to a random port on the host.
   .WithPortBinding(8080, true)
   // Wait until the HTTP endpoint of the container is available.

src/Testcontainers.MongoDb/MongoDbBuilder.cs

@@ -158,7 +158,7 @@ protected override MongoDbBuilder Merge(MongoDbConfiguration oldValue, MongoDbCo
     /// <param name="configuration">The container configuration.</param>
     /// <param name="ct">Cancellation token.</param>
     /// <returns>Task that completes when the replica set initiation has been executed.</returns>
-    private async Task InitiateReplicaSetAsync(MongoDbContainer container, MongoDbConfiguration configuration, CancellationToken ct)
+    private static async Task InitiateReplicaSetAsync(MongoDbContainer container, MongoDbConfiguration configuration, CancellationToken ct)
     {
         if (string.IsNullOrEmpty(configuration.ReplicaSetName))
         {
@@ -224,7 +224,7 @@ public Task<bool> UntilAsync(IContainer container)
         }
 
         /// <inheritdoc cref="IWaitUntil.UntilAsync" />
-        private async Task<bool> UntilAsync(MongoDbContainer container)
+        private static async Task<bool> UntilAsync(MongoDbContainer container)
         {
             var execResult = await container.ExecScriptAsync(ScriptContent)
                 .ConfigureAwait(false);

src/Testcontainers/Configurations/WaitStrategies/IWaitStrategy.cs

@@ -9,6 +9,13 @@ namespace DotNet.Testcontainers.Configurations
   [PublicAPI]
   public interface IWaitStrategy
   {
+    /// <summary>
+    /// Sets the wait strategy mode.
+    /// </summary>
+    /// <param name="mode">The wait strategy mode.</param>
+    /// <returns>The updated instance of the wait strategy.</returns>
+    IWaitStrategy WithMode(WaitStrategyMode mode);
+
     /// <summary>
     /// Sets the number of retries for the wait strategy.
     /// </summary>

src/Testcontainers/Configurations/WaitStrategies/WaitForContainerOS.cs

@@ -15,7 +15,10 @@ internal abstract class WaitForContainerOS : IWaitForContainerOS
     /// </summary>
     protected WaitForContainerOS()
     {
-      _waitStrategies.Add(new WaitStrategy(new UntilContainerIsRunning()));
+      var waitStrategy = new WaitStrategy(new UntilContainerIsRunning());
+      _ = waitStrategy.WithMode(WaitStrategyMode.OneShot);
+
+      _waitStrategies.Add(waitStrategy);
     }
 
     /// <inheritdoc />
@@ -31,7 +34,7 @@ protected WaitForContainerOS()
     public abstract IWaitForContainerOS UntilInternalTcpPortIsAvailable(int containerPort, Action<IWaitStrategy> waitStrategyModifier = null);
 
     /// <inheritdoc />
-    public virtual IWaitForContainerOS AddCustomWaitStrategy(IWaitUntil waitUntil, Action<IWaitStrategy> waitStrategyModifier = null)
+    public IWaitForContainerOS AddCustomWaitStrategy(IWaitUntil waitUntil, Action<IWaitStrategy> waitStrategyModifier = null)
     {
       var waitStrategy = new WaitStrategy(waitUntil);
 
@@ -51,7 +54,7 @@ public IWaitForContainerOS UntilExternalTcpPortIsAvailable(int containerPort, Ac
     }
 
     /// <inheritdoc />
-    public virtual IWaitForContainerOS UntilFileExists(string filePath, FileSystem fileSystem = FileSystem.Host, Action<IWaitStrategy> waitStrategyModifier = null)
+    public IWaitForContainerOS UntilFileExists(string filePath, FileSystem fileSystem = FileSystem.Host, Action<IWaitStrategy> waitStrategyModifier = null)
     {
       switch (fileSystem)
       {
@@ -76,19 +79,19 @@ public IWaitForContainerOS UntilMessageIsLogged(Regex pattern, Action<IWaitStrat
     }
 
     /// <inheritdoc />
-    public virtual IWaitForContainerOS UntilHttpRequestIsSucceeded(Func<HttpWaitStrategy, HttpWaitStrategy> request, Action<IWaitStrategy> waitStrategyModifier = null)
+    public IWaitForContainerOS UntilHttpRequestIsSucceeded(Func<HttpWaitStrategy, HttpWaitStrategy> request, Action<IWaitStrategy> waitStrategyModifier = null)
     {
       return AddCustomWaitStrategy(request.Invoke(new HttpWaitStrategy()), waitStrategyModifier);
     }
 
     /// <inheritdoc />
-    public virtual IWaitForContainerOS UntilContainerIsHealthy(long failingStreak = 3, Action<IWaitStrategy> waitStrategyModifier = null)
+    public IWaitForContainerOS UntilContainerIsHealthy(long failingStreak = 3, Action<IWaitStrategy> waitStrategyModifier = null)
     {
       return AddCustomWaitStrategy(new UntilContainerIsHealthy(failingStreak), waitStrategyModifier);
     }
 
     /// <inheritdoc />
-    public virtual IWaitForContainerOS UntilDatabaseIsAvailable(DbProviderFactory dbProviderFactory, Action<IWaitStrategy> waitStrategyModifier = null)
+    public IWaitForContainerOS UntilDatabaseIsAvailable(DbProviderFactory dbProviderFactory, Action<IWaitStrategy> waitStrategyModifier = null)
     {
       return AddCustomWaitStrategy(new UntilDatabaseIsAvailable(dbProviderFactory), waitStrategyModifier);
     }

src/Testcontainers/Configurations/WaitStrategies/WaitStrategy.cs

@@ -41,6 +41,12 @@ public WaitStrategy(IWaitUntil waitUntil)
       _ = WithStrategy(waitUntil);
     }
 
+    /// <summary>
+    /// Gets the wait strategy mode.
+    /// </summary>
+    public WaitStrategyMode Mode { get; private set; }
+      =  WaitStrategyMode.Running;
+
     /// <summary>
     /// Gets the number of retries.
     /// </summary>
@@ -59,6 +65,13 @@ public WaitStrategy(IWaitUntil waitUntil)
     public TimeSpan Timeout { get; private set; }
       = TestcontainersSettings.WaitStrategyTimeout ?? TimeSpan.FromHours(1);
 
+    /// <inheritdoc />
+    public IWaitStrategy WithMode(WaitStrategyMode mode)
+    {
+      Mode = mode;
+      return this;
+    }
+
     /// <inheritdoc />
     public IWaitStrategy WithRetries(ushort retries)
     {

src/Testcontainers/Configurations/WaitStrategies/WaitStrategyMode.cs

@@ -0,0 +1,30 @@
+namespace DotNet.Testcontainers.Configurations
+{
+  using DotNet.Testcontainers.Containers;
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// Represents the execution mode for a wait strategy.
+  /// </summary>
+  [PublicAPI]
+  public enum WaitStrategyMode
+  {
+    /// <summary>
+    /// Indicates that the container is expected to be in the <c>Running</c> state.
+    /// </summary>
+    /// <remarks>
+    /// When this mode is used, the library verifies that the container is running. If
+    /// the container is not running, it collects the container's <c>stdout</c> and
+    /// <c>stderr</c> logs and throws a <see cref="ContainerNotRunningException" /> exception.
+    /// </remarks>
+    Running,
+
+    /// <summary>
+    /// Executes the wait strategy without requiring the container to be running.
+    /// </summary>
+    /// <remarks>
+    /// This mode does not check the container's running state.
+    /// </remarks>
+    OneShot,
+  }
+}

src/Testcontainers/Containers/ContainerNotRunningException.cs

@@ -0,0 +1,60 @@
+namespace DotNet.Testcontainers.Containers
+{
+  using System;
+  using System.Linq;
+  using System.Text;
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// Represents an exception that is thrown when a container is not running anymore,
+  /// and exited unexpectedly.
+  /// </summary>
+  [PublicAPI]
+  public sealed class ContainerNotRunningException : Exception
+  {
+    private static readonly string[] LineEndings = new[] { "\r\n", "\n" };
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContainerNotRunningException" /> class.
+    /// </summary>
+    /// <param name="id">The container id.</param>
+    /// <param name="stdout">The stdout.</param>
+    /// <param name="stderr">The stderr.</param>
+    /// <param name="exitCode">The exit code.</param>
+    /// <param name="exception">The inner exception.</param>
+    public ContainerNotRunningException(string id, string stdout, string stderr, long exitCode, [CanBeNull] Exception exception)
+      : base(CreateMessage(id, stdout, stderr, exitCode), exception)
+    {
+    }
+
+    private static string CreateMessage(string id, string stdout, string stderr, long exitCode)
+    {
+      var exceptionInfo = new StringBuilder(256);
+      exceptionInfo.Append($"Container {id} exited with code {exitCode}.");
+
+      if (!string.IsNullOrEmpty(stdout))
+      {
+        var stdoutLines = stdout
+          .Split(LineEndings, StringSplitOptions.RemoveEmptyEntries)
+          .Select(line => "    " + line);
+
+        exceptionInfo.AppendLine();
+        exceptionInfo.AppendLine("  Stdout: ");
+        exceptionInfo.Append(string.Join(Environment.NewLine, stdoutLines));
+      }
+
+      if (!string.IsNullOrEmpty(stderr))
+      {
+        var stderrLines = stderr
+          .Split(LineEndings, StringSplitOptions.RemoveEmptyEntries)
+          .Select(line => "    " + line);
+
+        exceptionInfo.AppendLine();
+        exceptionInfo.AppendLine("  Stderr: ");
+        exceptionInfo.Append(string.Join(Environment.NewLine, stderrLines));
+      }
+
+      return exceptionInfo.ToString();
+    }
+  }
+}

src/Testcontainers/Containers/DockerContainer.cs

@@ -671,11 +671,27 @@ protected override bool Exists()
     /// <returns>A task representing the asynchronous operation, returning true if the wait strategy indicates readiness; otherwise, false.</returns>
     private async Task<bool> CheckReadinessAsync(WaitStrategy waitStrategy, CancellationToken ct = default)
     {
+      Exception exception = null;
+
       _container = await _client.Container.ByIdAsync(_container.ID, ct)
         .ConfigureAwait(false);
 
-      return await waitStrategy.UntilAsync(this, ct)
-        .ConfigureAwait(false);
+      try
+      {
+        return await waitStrategy.UntilAsync(this, ct)
+          .ConfigureAwait(false);
+      }
+      catch (DockerApiException e)
+      {
+        exception = e;
+      }
+      finally
+      {
+        await ThrowIfContainerNotRunningAsync(waitStrategy.Mode, exception)
+          .ConfigureAwait(false);
+      }
+
+      return false;
     }
 
     /// <summary>
@@ -699,13 +715,36 @@ await WaitStrategy.WaitUntilAsync(() => CheckReadinessAsync(waitStrategy, ct), w
       return true;
     }
 
+    /// <summary>
+    /// Throws <see cref="ContainerNotRunningException" /> when the container exited unexpectedly.
+    /// </summary>
+    /// <param name="waitStrategyMode">The wait strategy mode.</param>
+    /// <param name="innerException">The inner exception.</param>
+    /// <exception cref="ContainerNotRunningException">The container exited unexpectedly.</exception>
+    private async Task ThrowIfContainerNotRunningAsync(WaitStrategyMode waitStrategyMode, [CanBeNull] Exception innerException = null)
+    {
+      if (innerException == null && (TestcontainersStates.Exited != State || WaitStrategyMode.Running != waitStrategyMode))
+      {
+        return;
+      }
+
+      var (stdout, stderr) = await GetLogsAsync()
+        .ConfigureAwait(false);
+
+      var exitCode = await GetExitCodeAsync()
+        .ConfigureAwait(false);
+
+      throw new ContainerNotRunningException(Id, stdout, stderr, exitCode, innerException);
+    }
+
     private sealed class WaitUntilPortBindingsMapped : WaitStrategy
     {
       private readonly DockerContainer _parent;
 
       public WaitUntilPortBindingsMapped(DockerContainer parent)
       {
         _parent = parent;
+        _ = WithMode(WaitStrategyMode.OneShot);
         _ = WithInterval(TimeSpan.FromSeconds(1));
         _ = WithTimeout(TimeSpan.FromSeconds(15));
       }