Add DockerEnvironmentNotAvailableFailureAnalyzer

Introduce a FailureAnalyzer to provide actionable guidance
when Testcontainers fails to detect a running Docker-compatible environment.

Signed-off-by: Dmytro Nosan <[email protected]>

Author: nosan

core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/diagnostics/DockerEnvironmentNotAvailableFailureAnalyzer.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2012-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.testcontainers.diagnostics;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
+import org.springframework.boot.diagnostics.FailureAnalysis;
+import org.springframework.util.StringUtils;
+
+/**
+ * Failure analyzer for Docker environment not available.
+ *
+ * @author Dmytro Nosan
+ */
+class DockerEnvironmentNotAvailableFailureAnalyzer extends AbstractFailureAnalyzer<IllegalStateException> {
+
+	private static final String EXPECTED_MESSAGE = "Could not find a valid Docker environment";
+
+	@Override
+	protected @Nullable FailureAnalysis analyze(Throwable rootFailure, IllegalStateException cause) {
+		if (!StringUtils.hasText(cause.getMessage()) || !cause.getMessage().contains(EXPECTED_MESSAGE)) {
+			return null;
+		}
+		String action = """
+				    - Ensure a Docker-compatible container engine is installed and running. This includes:
+				        * Docker: (Desktop/Engine) Ensure the service is active. Verify accessibility by running `docker info`.
+				        * Podman: Ensure the Podman socket is active and export the `DOCKER_HOST` environment variable to point to it.
+				        * Colima: Ensure the Colima VM is started and the Docker context is active.
+				    - If using a non-default setup (e.g., remote host, WSL), confirm the `DOCKER_HOST` environment variable is correctly set.
+				    - If running Testcontainers in CI, ensure the runner has access to the daemon.
+				    - Review the Testcontainers documentation for troubleshooting and advanced configuration options.
+				""";
+		return new FailureAnalysis("Could not find a valid Docker environment for Testcontainers.", action, cause);
+	}
+
+}

core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/diagnostics/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2012-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Classes for diagnosing issues with Testcontainers.
+ */
+@NullMarked
+package org.springframework.boot.testcontainers.diagnostics;
+
+import org.jspecify.annotations.NullMarked;

core/spring-boot-testcontainers/src/main/resources/META-INF/spring.factories

@@ -6,3 +6,6 @@ org.springframework.boot.testcontainers.lifecycle.TestcontainersLifecycleApplica
 org.springframework.test.context.ContextCustomizerFactory=\
 org.springframework.boot.testcontainers.service.connection.ServiceConnectionContextCustomizerFactory
 
+# Failure Analyzers
+org.springframework.boot.diagnostics.FailureAnalyzer=\
+org.springframework.boot.testcontainers.diagnostics.DockerEnvironmentNotAvailableFailureAnalyzer

core/spring-boot-testcontainers/src/test/java/org/springframework/boot/testcontainers/diagnostics/DockerEnvironmentNotAvailableFailureAnalyzerTests.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2012-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.testcontainers.diagnostics;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.boot.diagnostics.FailureAnalysis;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link DockerEnvironmentNotAvailableFailureAnalyzer}.
+ *
+ * @author Dmytro Nosan
+ */
+class DockerEnvironmentNotAvailableFailureAnalyzerTests {
+
+	private final DockerEnvironmentNotAvailableFailureAnalyzer analyzer = new DockerEnvironmentNotAvailableFailureAnalyzer();
+
+	@Test
+	void shouldReturnFailureAnalysisWhenMessageMatches() {
+		IllegalStateException cause = new IllegalStateException(
+				"Could not find a valid Docker environment. Please see logs and check configuration");
+		FailureAnalysis analysis = this.analyzer
+			.analyze(new RuntimeException("Root", new RuntimeException("Intermediate", cause)));
+		assertThat(analysis).isNotNull();
+		assertThat(analysis.getDescription())
+			.isEqualTo("Could not find a valid Docker environment for Testcontainers.");
+		assertThat(analysis.getAction())
+			.contains("Ensure a Docker-compatible container engine is installed and running");
+		assertThat(analysis.getCause()).isSameAs(cause);
+	}
+
+	@Test
+	void shouldReturnNullWhenMessageDoesNotMatch() {
+		FailureAnalysis analysis = this.analyzer.analyze(new IllegalStateException("Some message"));
+		assertThat(analysis).isNull();
+	}
+
+	@Test
+	void shouldReturnNullWhenMessageIsNull() {
+		FailureAnalysis analysis = this.analyzer.analyze(new IllegalStateException());
+		assertThat(analysis).isNull();
+	}
+
+}