Improve startup wait checks (#6384)

* Log a warning if the container image and server architectures do not match
* Make sure a container exiting successfully is properly handled
* We don't need to continue checking if the container stops running

Co-authored-by: Eddú Meléndez <[email protected]>

Author: deejgregor

core/src/main/java/org/testcontainers/containers/GenericContainer.java

@@ -470,6 +470,11 @@ private void tryStart(Instant startedAt) {
                         }
                     );
 
+            String emulationWarning = checkForEmulation();
+            if (emulationWarning != null) {
+                logger().warn(emulationWarning);
+            }
+
             // Tell subclasses that we're starting
             containerIsStarting(containerInfo, reused);
 
@@ -960,6 +965,32 @@ protected void waitUntilContainerStarted() {
         }
     }
 
+    private String checkForEmulation() {
+        try {
+            DockerClient dockerClient = DockerClientFactory.instance().client();
+            String imageId = getContainerInfo().getImageId();
+            String imageArch = dockerClient.inspectImageCmd(imageId).exec().getArch();
+            String serverArch = dockerClient.versionCmd().exec().getArch();
+
+            if (!serverArch.equals(imageArch)) {
+                return (
+                    "The architecture '" +
+                    imageArch +
+                    "' for image '" +
+                    getDockerImageName() +
+                    "' (ID " +
+                    imageId +
+                    ") does not match the Docker server architecture '" +
+                    serverArch +
+                    "'. This will cause the container to execute much more slowly due to emulation and may lead to timeout failures."
+                );
+            }
+        } catch (Exception archCheckException) {
+            // ignore any exceptions since this is just used for a log message
+        }
+        return null;
+    }
+
     /**
      * {@inheritDoc}
      */

core/src/main/java/org/testcontainers/containers/startupcheck/IsRunningStartupCheckStrategy.java

@@ -30,8 +30,12 @@ public StartupStatus checkStartupState(DockerClient dockerClient, String contain
     private StartupStatus checkState(InspectContainerResponse.ContainerState state) {
         if (Boolean.TRUE.equals(state.getRunning())) {
             return StartupStatus.SUCCESSFUL;
-        } else if (!DockerStatus.isContainerExitCodeSuccess(state)) {
-            return StartupStatus.FAILED;
+        } else if (DockerStatus.isContainerStopped(state)) {
+            if (DockerStatus.isContainerExitCodeSuccess(state)) {
+                return StartupStatus.SUCCESSFUL;
+            } else {
+                return StartupStatus.FAILED;
+            }
         } else {
             return StartupStatus.NOT_YET_KNOWN;
         }

core/src/main/java/org/testcontainers/containers/wait/strategy/HostPortWaitStrategy.java

@@ -74,6 +74,7 @@ protected void waitUntilReady() {
                             .pollInSameThread()
                             .pollInterval(Duration.ofMillis(100))
                             .pollDelay(Duration.ZERO)
+                            .failFast("container is no longer running", () -> !waitStrategyTarget.isRunning())
                             .ignoreExceptions()
                             .forever()
                             .until(externalCheck);

core/src/test/java/org/testcontainers/containers/GenericContainerTest.java

@@ -1,5 +1,7 @@
 package org.testcontainers.containers;
 
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
 import com.github.dockerjava.api.DockerClient;
 import com.github.dockerjava.api.command.InspectContainerResponse;
 import com.github.dockerjava.api.command.InspectContainerResponse.ContainerState;
@@ -32,6 +34,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.assertj.core.api.Assertions.catchThrowable;
+import static org.assertj.core.api.Assumptions.assumeThat;
 
 public class GenericContainerTest {
 
@@ -180,6 +183,41 @@ public void shouldWaitUntilExposedPortIsMapped() {
         }
     }
 
+    @Test
+    public void testArchitectureCheck() {
+        assumeThat(DockerClientFactory.instance().client().versionCmd().exec().getArch()).isNotEqualTo("amd64");
+        // Choose an image that is *different* from the server architecture--this ensures we always get a warning.
+        final String image;
+        if (DockerClientFactory.instance().client().versionCmd().exec().getArch().equals("amd64")) {
+            // arm64 image
+            image = "testcontainers/sshd@sha256:f701fa4ae2cd25ad2b2ea2df1aad00980f67bacdd03958a2d7d52ee63d7fb3e8";
+        } else {
+            // amd64 image
+            image = "testcontainers/sshd@sha256:7879c6c99eeab01f1c6beb2c240d49a70430ef2d52f454765ec9707f547ef6f1";
+        }
+
+        try (GenericContainer container = new GenericContainer<>(image)) {
+            // Grab a copy of everything that is logged when we start the container
+            ch.qos.logback.classic.Logger logger = (ch.qos.logback.classic.Logger) container.logger();
+            ListAppender<ILoggingEvent> listAppender = new ListAppender<>();
+            listAppender.start();
+            logger.addAppender(listAppender);
+
+            container.start();
+
+            String regexMatch = "The architecture '\\S+' for image .*";
+            assertThat(listAppender.list)
+                .describedAs(
+                    "Received log list does not have a message matching '" +
+                    regexMatch +
+                    "': " +
+                    listAppender.list.toString()
+                )
+                .filteredOn(event -> event.getMessage().matches(regexMatch))
+                .isNotEmpty();
+        }
+    }
+
     static class NoopStartupCheckStrategy extends StartupCheckStrategy {
 
         @Override

core/src/test/java/org/testcontainers/containers/startupcheck/IsRunningStartupCheckStrategyTest.java

@@ -0,0 +1,37 @@
+package org.testcontainers.containers.startupcheck;
+
+import org.junit.Ignore;
+import org.junit.Test;
+import org.testcontainers.TestImages;
+import org.testcontainers.containers.GenericContainer;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+public class IsRunningStartupCheckStrategyTest {
+
+    @Test
+    public void testCommandQuickExitSuccess() {
+        try (GenericContainer container = new GenericContainer<>(TestImages.TINY_IMAGE).withCommand("/bin/true")) {
+            container.start(); // should start with no Exception
+        }
+    }
+
+    @Test
+    @Ignore("This test can fail to throw an AssertionError if the container doesn't fail quickly enough")
+    public void testCommandQuickExitFailure() {
+        try (GenericContainer container = new GenericContainer<>(TestImages.TINY_IMAGE).withCommand("/bin/false")) {
+            assertThatThrownBy(container::start)
+                .hasStackTraceContaining("Container startup failed")
+                .hasStackTraceContaining("Container did not start correctly");
+        }
+    }
+
+    @Test
+    public void testCommandStaysRunning() {
+        try (
+            GenericContainer container = new GenericContainer<>(TestImages.TINY_IMAGE).withCommand("/bin/sleep", "60")
+        ) {
+            container.start(); // should start with no Exception
+        }
+    }
+}

docs/features/startup_and_waits.md

@@ -116,7 +116,7 @@ Checks that the container is running and has been running for a defined minimum
 [Using minimum duration strategy](../examples/junit4/generic/src/test/java/org/testcontainers/containers/startupcheck/StartupCheckStrategyTest.java) inside_block:withMinimumDurationStrategy
 <!--/codeinclude-->
 
-### Other startup  strategies
+### Other startup strategies
 
 If none of these options meet your requirements, you can create your own subclass of 
 [`StartupCheckStrategy`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers