JUnit 5 extension

modules/junit-jupiter/README.md

@@ -0,0 +1,132 @@
+# TestContainers JUnit Jupiter module
+
+While Testcontainers is tightly coupled with the JUnit 4.x rule API, this module provides
+an API that is based on the [JUnit Jupiter](https://junit.org/junit5/) extension model.
+
+The extension supports two modes:
+
+- containers that are restarted for every test method
+- containers that are shared between all methods of a test class
+
+## Examples
+
+To use the Testcontainers extension annotate your test class with `@Testcontainers`.
+
+### Restarted containers
+
+To define a restarted container, define an instance field inside your test class and annotate it with
+the `@Container` annotation.
+
+```java
+@Testcontainers
+class SomeTest {
+
+    @Container
+    private MySQLContainer mySQLContainer = new MySQLContainer();
+
+    @Test
+    void someTestMethod() {
+        String url = mySQLContainer.getJdbcUrl();
+
+        // create a connection and run test as normal
+    }
+
+    @Nested
+    class NestedTests {
+
+        @Container
+        private final PostgreSQLContainer postgreSQLContainer = new PostgreSQLContainer();
+
+        void nestedTestMethod() {
+            // top level container is restarted for nested methods
+            String mySqlUrl = mySQLContainer.getJdbcUrl();
+
+            // nested containers are only available inside their nested class
+            String postgresUrl = postgreSQLContainer.getJdbcUrl();
+        }
+    }
+}
+```
+
+### Shared containers
+
+Shared containers are defined as static fields in a top level test class and have to be annotated with `@Container`.
+Note that shared containers can't be declared inside nested test classes.
+This is because nested test classes have to be defined non-static and can't therefore have static fields.
+
+```java
+@Testcontainers
+class SomeTest {
+
+    @Container
+    private static final MySQLContainer MY_SQL_CONTAINER = new MySQLContainer();
+
+    @Test
+    void someTestMethod() {
+        String url = MY_SQL_CONTAINER.getJdbcUrl();
+
+        // create a connection and run test as normal
+    }
+}
+```
+
+### Singleton containers
+
+Sometimes it might be useful to define a container that is only started once for several test classes.
+There is no special support for this use case provided by the Testcontainers extension.
+Instead this can be implemented using the following pattern:
+
+```java
+abstract class AbstractContainerBaseTest {
+
+    static final MySQLContainer MY_SQL_CONTAINER;
+
+    static {
+        MY_SQL_CONTAINER = new MySQLContainer();
+        MY_SQL_CONTAINER.start();
+    }
+}
+
+class FirstTest extends AbstractContainerBaseTest {
+
+    @Test
+    void someTestMethod() {
+        String url = MY_SQL_CONTAINER.getJdbcUrl();
+
+        // create a connection and run test as normal
+    }
+}
+```
+
+The singleton container is started only once when the base class is loaded.
+The container can then be used by all inheriting test classes.
+At the end of the test suite the [Ryuk container](https://github.com/testcontainers/moby-ryuk)
+that is started by Testcontainers core will take care of stopping the singleton container.
+
+## Dependency information
+
+Replace `VERSION` with the [latest version available on Maven Central](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.testcontainers%22) or use the Testcontainers BOM.
+
+### Maven
+
+```
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>junit-jupiter</artifactId>
+    <version>VERSION</version>
+</dependency>
+```
+
+### Gradle
+
+```
+compile group: 'org.testcontainers', name: 'junit-jupiter', version: 'VERSION'
+```
+
+## Limitations
+
+Since this module has a dependency onto JUnit Jupiter and on Testcontainers core, which
+has a dependency onto JUnit 4.x, projects using this module will end up with both, JUnit Jupiter
+and JUnit 4.x in the test classpath.
+
+This extension has only be tested with sequential test execution. Using it with parallel test execution is unsupported and may have unintended side effects.

modules/junit-jupiter/build.gradle

@@ -0,0 +1,22 @@
+description = "Testcontainers :: JUnit Jupiter Extension"
+
+dependencies {
+    compile project(':testcontainers')
+    compile 'org.junit.jupiter:junit-jupiter-api:5.3.1'
+
+    testCompile project(':mysql')
+    testCompile project(':postgresql')
+    testCompile 'com.zaxxer:HikariCP:2.6.1'
+    testCompile 'redis.clients:jedis:2.8.0'
+
+    testRuntime 'org.postgresql:postgresql:42.0.0'
+    testRuntime 'mysql:mysql-connector-java:6.0.6'
+    testRuntime 'org.junit.jupiter:junit-jupiter-engine:5.3.1'
+}
+
+test {
+    useJUnitPlatform()
+    testLogging {
+        events "passed", "skipped", "failed"
+    }
+}

modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/Container.java

@@ -0,0 +1,17 @@
+package org.testcontainers.junit.jupiter;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * The {@code @Container} annotation is used in conjunction with the {@link Testcontainers} annotation
+ * to mark containers that should be managed by the Testcontainers extension.
+ *
+ * @see Testcontainers
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Container {
+}

modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/Testcontainers.java

@@ -0,0 +1,57 @@
+package org.testcontainers.junit.jupiter;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code @Testcontainers} is a JUnit Jupiter extension to activate automatic
+ * startup and stop of containers used in a test case.
+ *
+ * <p>The test containers extension finds all fields of type
+ * {@link org.testcontainers.lifecycle.Startable} that are annotated with
+ * {@link Container} and calls their container lifecycle methods. Containers
+ * declared as static fields will be shared between test methods. They will be
+ * started only once before any test method is executed and stopped after the
+ * last test method has executed. Containers declared as instance fields will
+ * be started and stopped for every test method.</p>
+ *
+ * <p><strong>Note:</strong> This extension has only be tested with sequential
+ * test execution. Using it with parallel test execution is unsupported and
+ * may have unintended side effects.</p>
+ *
+ * <p>Example:</p>
+ *
+ * <pre>
+ * &#64;Testcontainers
+ * class MyTestcontainersTests {
+ *
+ *     // will be shared between test methods
+ *     &#64;Container
+ *     private static final MySQLContainer MY_SQL_CONTAINER = new MySQLContainer();
+ *
+ *     // will be started before and stopped after each test method
+ *     &#64;Container
+ *     private PostgreSQLContainer postgresqlContainer = new PostgreSQLContainer()
+ *             .withDatabaseName("foo")
+ *             .withUsername("foo")
+ *             .withPassword("secret");
+ *
+ *     &#64;Test
+ *     void test() {
+ *         assertTrue(MY_SQL_CONTAINER.isRunning());
+ *         assertTrue(postgresqlContainer.isRunning());
+ *     }
+ * }
+ * </pre>
+ *
+ * @see Container
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@ExtendWith(TestcontainersExtension.class)
+public @interface Testcontainers {
+}

modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/TestcontainersExtension.java

@@ -0,0 +1,125 @@
+package org.testcontainers.junit.jupiter;
+
+import org.junit.jupiter.api.extension.BeforeEachCallback;
+import org.junit.jupiter.api.extension.ExtensionConfigurationException;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.ExtensionContext.Namespace;
+import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
+import org.junit.jupiter.api.extension.TestInstancePostProcessor;
+import org.junit.platform.commons.support.AnnotationSupport;
+import org.junit.platform.commons.util.Preconditions;
+import org.junit.platform.commons.util.ReflectionUtils;
+import org.testcontainers.lifecycle.Startable;
+
+import java.lang.reflect.Field;
+import java.util.LinkedHashSet;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+class TestcontainersExtension implements TestInstancePostProcessor, BeforeEachCallback {
+
+    private static final Namespace NAMESPACE = Namespace.create(TestcontainersExtension.class);
+
+    private static final String TEST_INSTANCE = "testInstance";
+
+    @Override
+    public void postProcessTestInstance(final Object testInstance, final ExtensionContext context) {
+        ExtensionContext.Store store = context.getStore(NAMESPACE);
+        store.put(TEST_INSTANCE, testInstance);
+
+        findSharedContainers(testInstance)
+            .forEach(adapter -> store.getOrComputeIfAbsent(adapter.key, k -> adapter.start()));
+    }
+
+    @Override
+    public void beforeEach(final ExtensionContext context) {
+        collectParentTestInstances(context)
+            .parallelStream()
+            .flatMap(this::findRestartContainers)
+            .forEach(adapter -> context.getStore(NAMESPACE)
+                .getOrComputeIfAbsent(adapter.key, k -> adapter.start()));
+    }
+
+    private Set<Object> collectParentTestInstances(final ExtensionContext context) {
+        Set<Object> testInstances = new LinkedHashSet<>();
+        Optional<ExtensionContext> current = Optional.of(context);
+        while(current.isPresent()) {
+            ExtensionContext ctx = current.get();
+            Object testInstance = ctx.getStore(NAMESPACE).remove(TEST_INSTANCE);
+            if (testInstance != null) {
+                testInstances.add(testInstance);
+            }
+            current = ctx.getParent();
+        }
+        return testInstances;
+    }
+
+    private Stream<StoreAdapter> findSharedContainers(Object testInstance) {
+        return ReflectionUtils.findFields(
+                testInstance.getClass(),
+                isSharedContainer(),
+                ReflectionUtils.HierarchyTraversalMode.TOP_DOWN)
+            .stream()
+            .map(f -> getContainerInstance(testInstance, f));
+    }
+
+    private Predicate<Field> isSharedContainer() {
+        return isContainer().and(ReflectionUtils::isStatic);
+    }
+
+    private Stream<StoreAdapter> findRestartContainers(Object testInstance) {
+        return ReflectionUtils.findFields(
+                testInstance.getClass(),
+                isRestartContainer(),
+                ReflectionUtils.HierarchyTraversalMode.TOP_DOWN)
+            .stream()
+            .map(f -> getContainerInstance(testInstance, f));
+    }
+
+    private Predicate<Field> isRestartContainer() {
+        return isContainer().and(ReflectionUtils::isNotStatic);
+    }
+
+    private static Predicate<Field> isContainer() {
+        return field -> Startable.class.isAssignableFrom(field.getType()) && AnnotationSupport.isAnnotated(field, Container.class);
+    }
+
+    private static StoreAdapter getContainerInstance(final Object testInstance, final Field field) {
+        try {
+            field.setAccessible(true);
+            Startable containerInstance = Preconditions.notNull((Startable) field.get(testInstance), "Container " + field.getName() + " needs to be initialized");
+            return new StoreAdapter(field.getDeclaringClass(), field.getName(), containerInstance);
+        } catch (IllegalAccessException e) {
+            throw new ExtensionConfigurationException("Can not access container defined in field " + field.getName());
+        }
+    }
+
+    /**
+     * An adapter for {@link Startable} that implement {@link CloseableResource}
+     * thereby letting the JUnit automatically stop containers once the current
+     * {@link ExtensionContext} is closed.
+     */
+    private static class StoreAdapter implements CloseableResource {
+
+        private String key;
+
+        private Startable container;
+
+        private StoreAdapter(Class<?> declaringClass, String fieldName, Startable container) {
+            this.key = declaringClass.getName() + "." + fieldName;
+            this.container = container;
+        }
+
+        private StoreAdapter start() {
+            container.start();
+            return this;
+        }
+
+        @Override
+        public void close() {
+            container.stop();
+        }
+    }
+}