Merge branch 'develop' into docs-ch

Author: digital88

build/Parameters.cs

@@ -52,7 +52,7 @@ public static BuildParameters Instance(ICakeContext context)
             IsReleaseBuild = !buildInformation.IsLocalBuild && buildInformation.IsReleaseBuild,
             IsPullRequest = buildInformation.IsPullRequest,
             ShouldPublish = !buildInformation.IsLocalBuild && buildInformation.ShouldPublish,
-            Verbosity = DotNetVerbosity.Quiet,
+            Verbosity = DotNetVerbosity.Minimal,
             CodeSigningCertificateCredentials = BuildCredentials.GetCodeSigningCertificateCredentials(context),
             SonarQubeCredentials = SonarQubeCredentials.GetSonarQubeCredentials(context),
             NuGetCredentials = NuGetCredentials.GetNuGetCredentials(context),

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

src/Testcontainers/Containers/ExecFailedException.cs

@@ -0,0 +1,62 @@
+namespace DotNet.Testcontainers.Containers
+{
+  using System;
+  using System.Linq;
+  using System.Text;
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// Represents an exception that is thrown when executing a command inside a
+  /// running container fails.
+  /// </summary>
+  [PublicAPI]
+  public sealed class ExecFailedException : Exception
+  {
+    private static readonly string[] LineEndings = new[] { "\r\n", "\n" };
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ExecFailedException" /> class.
+    /// </summary>
+    /// <param name="execResult">The result of the failed command.</param>
+    public ExecFailedException(ExecResult execResult)
+      : base(CreateMessage(execResult))
+    {
+      ExecResult = execResult;
+    }
+
+    /// <summary>
+    /// Gets the result of the failed command.
+    /// </summary>
+    public ExecResult ExecResult { get; }
+
+    private static string CreateMessage(ExecResult execResult)
+    {
+      var exceptionInfo = new StringBuilder(256);
+      exceptionInfo.Append($"Process exited with code {execResult.ExitCode}.");
+
+      if (!string.IsNullOrEmpty(execResult.Stdout))
+      {
+        var stdoutLines = execResult.Stdout
+          .Split(LineEndings, StringSplitOptions.RemoveEmptyEntries)
+          .Select(line => "    " + line);
+
+        exceptionInfo.AppendLine();
+        exceptionInfo.AppendLine("  Stdout: ");
+        exceptionInfo.Append(string.Join(Environment.NewLine, stdoutLines));
+      }
+
+      if (!string.IsNullOrEmpty(execResult.Stderr))
+      {
+        var stderrLines = execResult.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/ExecResultExtensions.cs

@@ -0,0 +1,33 @@
+namespace DotNet.Testcontainers.Containers
+{
+  using System;
+  using System.Threading.Tasks;
+
+  /// <summary>
+  /// Extension methods for working with <see cref="ExecResult" /> instances.
+  /// </summary>
+  public static class ExecResultExtensions
+  {
+    /// <summary>
+    /// Awaits the <see cref="Task{ExecResult}" /> and throws an exception if the result's exit code is not successful.
+    /// </summary>
+    /// <param name="execTask">The task returning an <see cref="ExecResult" />.</param>
+    /// <param name="successExitCodes">A list of exit codes that should be treated as successful. If none are provided, only exit code <c>0</c> is treated as successful.</param>
+    /// <returns>The <see cref="ExecResult" /> if the exit code is in the list of success exit codes.</returns>
+    /// <exception cref="ExecFailedException">Thrown if the exit code is not in the list of success exit codes.</exception>
+    public static async Task<ExecResult> ThrowOnFailure(this Task<ExecResult> execTask, params long[] successExitCodes)
+    {
+      successExitCodes = successExitCodes == null || successExitCodes.Length == 0 ? new long[] { 0 } : successExitCodes;
+
+      var execResult = await execTask
+        .ConfigureAwait(false);
+
+      if (Array.IndexOf(successExitCodes, execResult.ExitCode) < 0)
+      {
+        throw new ExecFailedException(execResult);
+      }
+
+      return execResult;
+    }
+  }
+}

tests/Testcontainers.ActiveMq.Tests/ArtemisContainerTest.cs

@@ -22,9 +22,12 @@ await _artemisContainer.StartAsync()
             .ConfigureAwait(false);
     }
 
-    public ValueTask DisposeAsync()
+    public async ValueTask DisposeAsync()
     {
-        return _artemisContainer.DisposeAsync();
+        await DisposeAsyncCore()
+            .ConfigureAwait(false);
+
+        GC.SuppressFinalize(this);
     }
     // # --8<-- [end:UseArtemisContainer]
 
@@ -73,6 +76,11 @@ await producer.SendAsync(producedMessage)
     }
     // # --8<-- [end:ArtemisContainerEstablishesConnection]
 
+    protected virtual ValueTask DisposeAsyncCore()
+    {
+        return _artemisContainer.DisposeAsync();
+    }
+
     // # --8<-- [start:UseArtemisContainerDefaultAuth]
     [UsedImplicitly]
     public sealed class DefaultCredentialsConfiguration : ArtemisContainerTest

tests/Testcontainers.Azurite.Tests/AzuriteContainerTest.cs

@@ -15,9 +15,12 @@ await _azuriteContainer.StartAsync()
             .ConfigureAwait(false);
     }
 
-    public ValueTask DisposeAsync()
+    public async ValueTask DisposeAsync()
     {
-        return _azuriteContainer.DisposeAsync();
+        await DisposeAsyncCore()
+            .ConfigureAwait(false);
+
+        GC.SuppressFinalize(this);
     }
 
     [Fact]
@@ -65,6 +68,11 @@ public async Task EstablishesTableServiceConnection()
         Assert.False(HasError(properties));
     }
 
+    protected virtual ValueTask DisposeAsyncCore()
+    {
+        return _azuriteContainer.DisposeAsync();
+    }
+
     private static bool HasError<TResponseEntity>(NullableResponse<TResponseEntity> response)
     {
         using (var rawResponse = response.GetRawResponse())
@@ -104,6 +112,7 @@ public AzuriteMemoryLimitConfiguration()
         }
 
         [Fact]
+        [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
         public async Task MemoryLimitIsConfigured()
         {
             // Given

tests/Testcontainers.Commons/DockerCli.cs

@@ -44,7 +44,7 @@ public enum DockerResource
     public static bool PlatformIsEnabled(DockerPlatform platform)
     {
         var commandResult = new Command("version", "--format {{.Server.Os}}").Execute();
-        return 0.Equals(commandResult.ExitCode) && commandResult.Stdout.Contains(platform.ToString().ToLowerInvariant());
+        return 0.Equals(commandResult.ExitCode) && commandResult.Stdout.Contains(platform.ToString(), StringComparison.OrdinalIgnoreCase);
     }
 
     public static bool ResourceExists(DockerResource resource, string id)