feat: Throw DockerUnavailableException when Docker is not available (#1308)

Co-authored-by: Andre Hofmeister <9199345+HofmeisterAn@users.noreply.github.com>

Author: 0xced

src/Testcontainers/Builders/AbstractBuilder`4.cs

@@ -2,6 +2,8 @@ namespace DotNet.Testcontainers.Builders
 {
   using System;
   using System.Collections.Generic;
+  using System.Linq;
+  using System.Text;
   using DotNet.Testcontainers.Clients;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Containers;
@@ -141,9 +143,8 @@ protected virtual void Validate()
       _ = Guard.Argument(DockerResourceConfiguration.Logger, nameof(IResourceConfiguration<TCreateResourceEntity>.Logger))
         .NotNull();
 
-      const string containerRuntimeNotFound = "Docker is either not running or misconfigured. Please ensure that Docker is running and that the endpoint is properly configured. You can customize your configuration using either the environment variables or the ~/.testcontainers.properties file. For more information, visit:\nhttps://dotnet.testcontainers.org/custom_configuration/";
       _ = Guard.Argument(DockerResourceConfiguration.DockerEndpointAuthConfig, nameof(IResourceConfiguration<TCreateResourceEntity>.DockerEndpointAuthConfig))
-        .ThrowIf(argument => argument.Value == null, argument => new ArgumentException(containerRuntimeNotFound, argument.Name));
+        .ThrowIf(argument => argument.Value == null, CreateDockerUnavailableException);
 
       const string reuseNotSupported = "Reuse cannot be used in conjunction with WithCleanUp(true).";
       _ = Guard.Argument(DockerResourceConfiguration, nameof(IResourceConfiguration<TCreateResourceEntity>.Reuse))
@@ -164,5 +165,23 @@ protected virtual void Validate()
     /// <param name="newValue">The new Docker resource configuration.</param>
     /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
     protected abstract TBuilderEntity Merge(TConfigurationEntity oldValue, TConfigurationEntity newValue);
+
+    private static Exception CreateDockerUnavailableException(Guard.ArgumentInfo<IDockerEndpointAuthenticationConfiguration> argument)
+    {
+      var unavailableExceptions = TestcontainersSettings.DockerEndpointAuthProviders
+        .Select(authProvider => authProvider.LastException)
+        .Where(exception => exception != null);
+
+      var exception = new AggregateException(unavailableExceptions);
+
+      var exceptionInfo = new StringBuilder(512);
+      exceptionInfo.AppendLine("Docker is either not running or misconfigured. Please ensure that Docker is running and that the endpoint is properly configured.");
+      exceptionInfo.AppendLine("You can customize your configuration using either the environment variables or the ~/.testcontainers.properties file.");
+      exceptionInfo.AppendLine("For more information, visit: https://dotnet.testcontainers.org/custom_configuration/.");
+      exceptionInfo.AppendLine("  Details: ");
+      exceptionInfo.Append(string.Join(Environment.NewLine, exception.InnerExceptions.Select(e => "    " + e.Message)));
+
+      return new DockerUnavailableException(exceptionInfo.ToString(), exception);
+    }
   }
 }

src/Testcontainers/Builders/DockerEndpointAuthenticationProvider.cs

@@ -5,12 +5,22 @@ namespace DotNet.Testcontainers.Builders
   using System.Threading.Tasks;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Containers;
+  using JetBrains.Annotations;
 
   /// <inheritdoc cref="IDockerEndpointAuthenticationProvider" />
   internal class DockerEndpointAuthenticationProvider : IDockerEndpointAuthenticationProvider
   {
     private static readonly TaskFactory TaskFactory = new TaskFactory(CancellationToken.None, TaskCreationOptions.None, TaskContinuationOptions.None, TaskScheduler.Default);
 
+    [CanBeNull]
+    private Exception _cachedException;
+
+    /// <summary>
+    /// Exposes the exception that occurred during the last Docker availability check.
+    /// </summary>
+    [CanBeNull]
+    public Exception LastException => _cachedException;
+
     /// <inheritdoc />
     public virtual bool IsApplicable()
     {
@@ -38,10 +48,15 @@ public virtual bool IsAvailable()
                 await dockerClient.System.PingAsync()
                   .ConfigureAwait(false);
 
+                _cachedException = null;
+
                 return true;
               }
-              catch (Exception)
+              catch (Exception e)
               {
+                var message = $"Failed to connect to Docker endpoint at '{dockerClientConfiguration.EndpointBaseUri}'.";
+                _cachedException = new DockerUnavailableException(message, e);
+
                 return false;
               }
             }

src/Testcontainers/Builders/DockerUnavailableException.cs

@@ -0,0 +1,31 @@
+namespace DotNet.Testcontainers.Builders
+{
+  using System;
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// Represents an exception that is thrown when a connection to the Docker endpoint
+  /// cannot be established successfully.
+  /// </summary>
+  [PublicAPI]
+  public sealed class DockerUnavailableException : Exception
+  {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DockerUnavailableException" /> class.
+    /// </summary>
+    /// <param name="message">The message that describes the error.</param>
+    public DockerUnavailableException(string message) : base(message)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DockerUnavailableException" /> class.
+    /// </summary>
+    /// <param name="message">The message that describes the error.</param>
+    /// <param name="innerException">The exception that is the cause of the current exception.</param>
+    public DockerUnavailableException(string message, Exception innerException)
+      : base(message, innerException)
+    {
+    }
+  }
+}

src/Testcontainers/Configurations/TestcontainersSettings.cs

@@ -17,21 +17,22 @@ namespace DotNet.Testcontainers.Configurations
   [PublicAPI]
   public static class TestcontainersSettings
   {
+    internal static readonly List<DockerEndpointAuthenticationProvider> DockerEndpointAuthProviders
+      = new List<DockerEndpointAuthenticationProvider>
+      {
+        new TestcontainersEndpointAuthenticationProvider(),
+        new MTlsEndpointAuthenticationProvider(),
+        new TlsEndpointAuthenticationProvider(),
+        new EnvironmentEndpointAuthenticationProvider(),
+        new NpipeEndpointAuthenticationProvider(),
+        new UnixEndpointAuthenticationProvider(),
+        new DockerDesktopEndpointAuthenticationProvider(),
+        new RootlessUnixEndpointAuthenticationProvider(),
+      };
+
     [CanBeNull]
     private static readonly IDockerEndpointAuthenticationProvider DockerEndpointAuthProvider
-      = new IDockerEndpointAuthenticationProvider[]
-        {
-          new TestcontainersEndpointAuthenticationProvider(),
-          new MTlsEndpointAuthenticationProvider(),
-          new TlsEndpointAuthenticationProvider(),
-          new EnvironmentEndpointAuthenticationProvider(),
-          new NpipeEndpointAuthenticationProvider(),
-          new UnixEndpointAuthenticationProvider(),
-          new DockerDesktopEndpointAuthenticationProvider(),
-          new RootlessUnixEndpointAuthenticationProvider(),
-        }
-        .Where(authProvider => authProvider.IsApplicable())
-        .FirstOrDefault(authProvider => authProvider.IsAvailable());
+      = DockerEndpointAuthProviders.FirstOrDefault(authProvider => authProvider.IsApplicable() && authProvider.IsAvailable());
 
     [CanBeNull]
     private static readonly IDockerEndpointAuthenticationConfiguration DockerEndpointAuthConfig