Throw the new DockerUnavailableException when Docker is not available

src/Testcontainers/Builders/AbstractBuilder`4.cs

@@ -2,6 +2,7 @@ namespace DotNet.Testcontainers.Builders
 {
   using System;
   using System.Collections.Generic;
+  using System.Linq;
   using DotNet.Testcontainers.Clients;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Containers;
@@ -141,9 +142,21 @@ 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));
+      if (DockerResourceConfiguration.DockerEndpointAuthConfig == null)
+      {
+        var message = TestcontainersSettings.UnavailableEndpoints.Count == 0
+          ? "Docker is either not running or misconfigured. Please ensure that Docker is running and that the endpoint is properly configured."
+          : $"Docker is either not running or misconfigured. Please ensure that Docker is available at {string.Join(" or ", TestcontainersSettings.UnavailableEndpoints.Select(e => e.Uri))}";
+
+        var innerException = TestcontainersSettings.UnavailableEndpoints.Count switch
+        {
+          0 => null,
+          1 => TestcontainersSettings.UnavailableEndpoints[0].Exception,
+          _ => new AggregateException(TestcontainersSettings.UnavailableEndpoints.Select(e => e.Exception)),
+        };
+        throw new DockerUnavailableException(message + "\nYou can customize your configuration using either the environment variables or the ~/.testcontainers.properties file. " +
+                                             "For more information, visit:\nhttps://dotnet.testcontainers.org/custom_configuration/", innerException);
+      }
 
       const string reuseNotSupported = "Reuse cannot be used in conjunction with WithCleanUp(true).";
       _ = Guard.Argument(DockerResourceConfiguration, nameof(IResourceConfiguration<TCreateResourceEntity>.Reuse))

src/Testcontainers/Builders/DockerEndpointAuthenticationProvider.cs

@@ -3,6 +3,7 @@ namespace DotNet.Testcontainers.Builders
   using System;
   using System.Threading;
   using System.Threading.Tasks;
+  using JetBrains.Annotations;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Containers;
 
@@ -11,6 +12,9 @@ internal class DockerEndpointAuthenticationProvider : IDockerEndpointAuthenticat
   {
     private static readonly TaskFactory TaskFactory = new TaskFactory(CancellationToken.None, TaskCreationOptions.None, TaskContinuationOptions.None, TaskScheduler.Default);
 
+    [CanBeNull]
+    public (Uri, Exception)? UnavailableEndpoint;
+
     /// <inheritdoc />
     public virtual bool IsApplicable()
     {
@@ -40,8 +44,9 @@ await dockerClient.System.PingAsync()
 
                 return true;
               }
-              catch (Exception)
+              catch (Exception e)
               {
+                UnavailableEndpoint = (dockerClientConfiguration.EndpointBaseUri, e);
                 return false;
               }
             }

src/Testcontainers/Configurations/TestcontainersSettings.cs

@@ -18,44 +18,54 @@ namespace DotNet.Testcontainers.Configurations
   public static class TestcontainersSettings
   {
     [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());
+    private static readonly IDockerEndpointAuthenticationProvider DockerEndpointAuthProvider;
 
     [CanBeNull]
-    private static readonly IDockerEndpointAuthenticationConfiguration DockerEndpointAuthConfig
-      = DockerEndpointAuthProvider?.GetAuthConfig();
+    private static readonly IDockerEndpointAuthenticationConfiguration DockerEndpointAuthConfig;
+
+    internal static readonly IReadOnlyList<(Uri Uri, Exception Exception)> UnavailableEndpoints;
 
     static TestcontainersSettings()
     {
+      var providers = new IDockerEndpointAuthenticationProvider[]
+      {
+        new TestcontainersEndpointAuthenticationProvider(),
+        new MTlsEndpointAuthenticationProvider(),
+        new TlsEndpointAuthenticationProvider(),
+        new EnvironmentEndpointAuthenticationProvider(),
+        new NpipeEndpointAuthenticationProvider(),
+        new UnixEndpointAuthenticationProvider(),
+        new DockerDesktopEndpointAuthenticationProvider(),
+        new RootlessUnixEndpointAuthenticationProvider(),
+      };
+
+      DockerEndpointAuthProvider = providers.Where(authProvider => authProvider.IsApplicable()).FirstOrDefault(authProvider => authProvider.IsAvailable());
+      DockerEndpointAuthConfig = DockerEndpointAuthProvider?.GetAuthConfig();
+      UnavailableEndpoints = providers.OfType<DockerEndpointAuthenticationProvider>().Select(e => e.UnavailableEndpoint).Where(e => e.HasValue).Select(e => e.Value).ToList();
+      if (DockerEndpointAuthProvider is ICustomConfiguration config)
+      {
+        DockerHostOverride = config.GetDockerHostOverride();
+        DockerSocketOverride = config.GetDockerSocketOverride();
+      }
+      else
+      {
+        DockerHostOverride = EnvironmentConfiguration.Instance.GetDockerHostOverride() ?? PropertiesFileConfiguration.Instance.GetDockerHostOverride();
+        DockerSocketOverride = EnvironmentConfiguration.Instance.GetDockerSocketOverride() ?? PropertiesFileConfiguration.Instance.GetDockerSocketOverride();
+      }
+      OS = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? new Windows(DockerEndpointAuthConfig) : new Unix(DockerEndpointAuthConfig);
     }
 
     /// <summary>
     /// Gets or sets the Docker host override value.
     /// </summary>
     [CanBeNull]
     public static string DockerHostOverride { get; set; }
-      = DockerEndpointAuthProvider is ICustomConfiguration config
-        ? config.GetDockerHostOverride() : EnvironmentConfiguration.Instance.GetDockerHostOverride() ?? PropertiesFileConfiguration.Instance.GetDockerHostOverride();
 
     /// <summary>
     /// Gets or sets the Docker socket override value.
     /// </summary>
     [CanBeNull]
     public static string DockerSocketOverride { get; set; }
-      = DockerEndpointAuthProvider is ICustomConfiguration config
-        ? config.GetDockerSocketOverride() : EnvironmentConfiguration.Instance.GetDockerSocketOverride() ?? PropertiesFileConfiguration.Instance.GetDockerSocketOverride();
 
     /// <summary>
     /// Gets or sets a value indicating whether the <see cref="ResourceReaper" /> is enabled or not.
@@ -141,7 +151,6 @@ static TestcontainersSettings()
     /// </summary>
     [NotNull]
     public static IOperatingSystem OS { get; set; }
-      = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? new Windows(DockerEndpointAuthConfig) : new Unix(DockerEndpointAuthConfig);
 
     /// <inheritdoc cref="PortForwardingContainer.ExposeHostPortsAsync" />
     public static Task ExposeHostPortsAsync(ushort port, CancellationToken ct = default)

src/Testcontainers/DockerUnavailableException.cs

@@ -0,0 +1,21 @@
+namespace DotNet.Testcontainers
+{
+  using System;
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// The exception that is thrown when Docker is not available (because it is either not running or misconfigured).
+  /// </summary>
+  [PublicAPI]
+  public sealed class DockerUnavailableException : Exception
+  {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DockerUnavailableException"/> class, using the provided message.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="innerException">The exception that is the cause of the current exception.</param>
+    internal DockerUnavailableException(string message, Exception innerException) : base(message, innerException)
+    {
+    }
+  }
+}