Proof-of-Concept for using TestContainers

This repository is a small proof-of-concept for using Testcontainers within your JUnit tests. The PoC is based on JUnit 5 and contains the following examples:

• simple MySQL Database
• SimpleWebServer based on the example provided by Baeldung
• a Docker Compose example for running Wordpress with MySQL from test

Overall Impression

• When you have mastered all problems (see Troubleshooting) using Testcontainers is quite easy.
• Debugging is a pain because of mismatched sources with byte-code: See testcontainers/testcontainers-java#762, where you will also find possible workarounds.
• Failure messages not always helpful: When first starting this little PoC I stumbled across a lot of exceptions (see below). The error messages did not help me. Instead I had to go through various trial-and-error approaches to reduce the scope of the errors. Starting from a working example like provided by Baeldung was a good approach to isolate the root-causes of my problems.

Troubleshooting

Could not find a valid Docker environment.

When first starting a test on Windows I got the following error messages from org.testcontainers.dockerclient.DockerClientProviderStrategy:

Could not find a valid Docker environment. Please check configuration. Attempted configurations were:
    NpipeSocketClientProviderStrategy: failed with exception InvalidConfigurationException (ping failed). Root cause TimeoutException (null)
    WindowsClientProviderStrategy: failed with exception TimeoutException (Timeout waiting for result with exception). Root cause ConnectException (Connection refused: connect)
    DockerMachineClientProviderStrategy: failed with exception InvalidConfigurationException (Exception when executing docker-machine status )
As no valid configuration was found, execution cannot continue

Problem (in this case) was, that Docker Desktop was not running after an update. Thus, ensure Docker Desktop is installed and running.

ClassNotFoundException: com.mysql.jdbc.Driver

When doing the first MySQL test, it took a considerable amount of time until it failed miserably. Reason was, that even though we were not using MySQL classes directly (at that point in time), org.testcontainers.containers.JdbcDatabaseContainer relies on the availability of the JDBC driver. Unfortunately, it does not fail immediately but only after several retries.

IllegalStateException: Mapped port can only be obtained after the container is started

If you happen to see this, check if you have annotated your test class with @Testcontainers.

Docker Compose and IllegalStateException: Container did not start correctly.

At least on Windows you may stumble across an exception like this using Docker Compose:

org.testcontainers.containers.ContainerLaunchException: Container startup failed
  ...
Caused by: org.rnorth.ducttape.RetryCountExceededException: Retry limit hit with exception
  ...
Caused by: org.testcontainers.containers.ContainerLaunchException: Could not create/start container
  ...
Caused by: java.lang.IllegalStateException: Container did not start correctly.
  at org.testcontainers.containers.GenericContainer.tryStart(GenericContainer.java:260)

To fix this issue configure your DockerComposeContainer with:

class MyTest {
  @Container
  private static final DockerComposeContainer COMPOSE_CONTAINER =
          new DockerComposeContainer(new File("..."))
                    .withLocalCompose(true)
                    /* ... */
          ;
  /* ... */
}

ContainerLaunchException: Aborting attempt to link to container...

This affects Docker Compose: If you see this exception, you should check your specified docker service names. A service named "myservice" has to be referenced in docker setup with "myservice_1". Note, that the name may not be the same as when you start the Docker Compose file directory. So, for example while the service name for simpleWebServer in simplewebserver.docker-compose.yml is testcontainers_simpleWebServer_1, it has to be referenced as simpleWebServer_1 within Testcontainers' set-up.

Docker Compose and Service Name

If you are using Docker Compose, it is important to know, that the service names will be generated by the service name within the YAML file with _1 attached. This is what you have to provide to access the services from within your tests. As possible alternative specify container_name: within your YAML file. This is discouraged by Docker as well as by Testcontainers developers, though.

References

• testcontainers/testcontainers-java: Testcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.
• Docker Desktop | Docker
• Quickstart: Compose and WordPress | Docker Documentation
• Docker Test Containers in Java Tests | Baeldung