Skip to content

feat: Throw DockerUnavailableException when Docker is not available #1308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 16, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions src/Testcontainers/Builders/AbstractBuilder`4.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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))
Expand All @@ -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);
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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()
{
Expand Down Expand Up @@ -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;
}
}
Expand Down
31 changes: 31 additions & 0 deletions src/Testcontainers/Builders/DockerUnavailableException.cs
Original file line number Diff line number Diff line change
@@ -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)
{
}
}
}
27 changes: 14 additions & 13 deletions src/Testcontainers/Configurations/TestcontainersSettings.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down