junit5-docker

JUnit5-Docker is a JUnit5 extension that start docker containers before running tests and stop them afterwards. This is the documentation for the version 1.0.0-RC5.

The last released version can be found at https://faustxvi.github.io/junit5-docker/current and the documentation of the under developpment version can be found at https://faustxvi.github.io/junit5-docker/snapshot

Dependency ———-

To use JUnit5-Docker, you first need to declare it as a dependency. Add these lines to your pom.xml if you are using maven.

 <dependency> <groupId>com.github.faustxvi</groupId> <artifactId>junit5-docker</artifactId> <version>1.0.0-RC5</version> <scope>test</scope> </dependency> 

Usage —–

The entrypoint is the @Docker annotation. Please refer to the Javadoc for more details.

The container is started before each test method is called; and stopped afterward.

This mean that the container is already started when the @BeforeEach methods are called and destroyed after the @AfterEach methods.

By default, you are guaranteed that a new container is created for each tests.

Simple Example

Given that you have a test like : 

@Docker(image = "faustxvi/simple-two-ports", ports = @Port(exposed = 8801, inner = 8080)) public class MyAwesomeTest { @Test void checkMyCode() { // Add your test content here } @Test void checkMyCodeWithAnotherContainer() { // Add your test content here } } 

When you run your tests : * a new container `faustxvi/simple-two-ports` is started before running each tests using the version `latest` * the port `8801` is bound to the container's port `8080` so you can exchange through this port * this container is stopped and removed after usage 

Real life exemple

Given that you have a test like : 

 @Docker(image = "mysql", ports = @Port(exposed = 8801, inner = 3306), environments = { @Environment(key = "MYSQL_ROOT_PASSWORD", value = "root"), @Environment(key = "MYSQL_DATABASE", value = "testdb"), @Environment(key = "MYSQL_USER", value = "testuser"), @Environment(key = "MYSQL_PASSWORD", value = "s3cr3t"), }, waitFor = @WaitFor("mysqld: ready for connections")) public class MyAwesomeTest { @Test void checkMyCode() { // Add your test content here } @Test void checkMyCodeWithAnotherContainer() { // Add your test content here } } 

When you run your tests : * the container is started with the given environment variables * the tests are started only after the string `mysqld: ready for connections` is found in the container's logs 

Keep the container for all tests of a class

The container is started once for the whole class and before any test method is called; and stopped afterward.

This mean that the container is already started when the @BeforeEach and @BeforeAll methods are called and destroyed after the @AfterEach and @AfterAll methods.

Be aware that the container is not restarted between tests so changing the state of the container in one test may affect other tests.

Given that you have a test like : 

@Docker(image = "faustxvi/simple-two-ports", ports = @Port(exposed = 8801, inner = 8080), newForEachCase = false) public class MyAwesomeTest { @Test void checkMyCode() { // Add your test content here } @Test void checkMyCodeWithTheSameContainer() { // Add your test content here } } 

When you run your tests : * the container `faustxvi/simple-two-ports` is started before running your tests using the version `latest` * the container is stopped and removed after your tests