Integration tests with testcontainers

This library defines docker containers for integration tests. Its implementation is based on the testcontainers.org library.

Container types:

• MySQL
  • Initializing database with sql scripts
• Cassandra
  • Initializing database with cql scripts
• Elasticsearch
• Kafka
  • Schema registry for AVRO message
  • Kafka-Connect Container

Versions

Prerequisites

Using this library requires a Docker configuration beforehand so that the docker containers can be running:

• Docker version should be at least 1.6.0
• Docker environment should have more than 2GB free disk space
• File should be mountable
• Expose daemon on tcp://localhost:2375 without TLS

MySQL

Add the Maven dependency

<dependency>
    <groupId>com.github.ydespreaux.testcontainers</groupId>
    <artifactId>testcontainers-mysql</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

Using Junit 5 (version 1.2.1)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.11.1</version>
    <scope>test</scope>
</dependency>

Quick Start

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer();
}

By default the MySQL image used is 'mysql: 5.7.22'. The URL of the image and the version are configurable. Below is an example to use version 5.7.21 of the image.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer("5.7.21");
}

When the docker container has started, the following properties are initialized in the spring boot context:

The withRegisterSpringbootProperties (boolean) method is used to initialize or not the spring boot context of the properties above. The following example does not update the spring boot properties:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer("5.7.21")
        .withRegisterSpringbootProperties(false);
}

The name of the spring boot properties can be changed using the following methods:

Setting up the MySQL database:

Initialization of the schema of the database:

Running a sql script:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer("5.7.21")
        .withMySqlInit("mysql-init/mysql-init.sql");
}

The mysql-init.sql file (found in the mysql-init directory) will be executed after the container starts.

Running a set of sql scripts:

Example to run 2 sql scripts:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer("5.7.21")
        .withMySqlInit("mysql-init/mysql-init-1.sql")
        .withMySqlInit("mysql-init/mysql-init-2.sql");
}

Example to run all the sql scripts contained in the 'mysql-init' directory:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final MySQLContainer mySqlContainer = new MySQLContainer("5.7.21")
        .withMySqlInitDirectory("mysql-init");
}

Sample with Junit 5 (version 1.2.1)

@Testcontainers
public class ITMySQLTest {

    @Container
    public static final MySQLContainer mySqlContainer = new MySQLContainer();
}

Cassandra

Add the Maven dependency

<dependency>
    <groupId>com.github.ydespreaux.testcontainers</groupId>
    <artifactId>testcontainers-cassandra</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

Using Junit 5 (version 1.2.1)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.11.1</version>
    <scope>test</scope>
</dependency>

Quick Start

@RunWith(SpringJUnit4ClassRunner.class)
public class ITCassandraTest {

    @ClassRule
    public static final CassandraContainer mySqlContainer = new CassandraContainer();
}

By default the image cassandra used is 'cassandra: 3.11'. The URL of the image and the version is configurable. Below is an example to use version 3 of the image.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITCassandraTest {

    @ClassRule
    public static final CassandraContainer mySqlContainer = new CassandraContainer("3");
}

When the docker container has started, the following properties are initialized in the spring boot context:

The withRegisterSpringbootProperties (boolean) method is used to initialize or not the spring boot context of the properties above.

The name of the spring boot properties can be changed using the following methods:

Initialization of the schema of the database:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITMySQLTest {

    @ClassRule
    public static final CassandraContainer cassandraContainer = new CassandraContainer()
        .withCqlScriptDirectory("db-schema");

}

The withCqlScriptDirectory (...) method takes a parameter from the directory path. The set of scripts cql will be executed after the start of the container.

Sample with Junit 5 (version 1.2.1)

@Testcontainers
public class ITCassandraTest {

    @Container
    public static final CassandraContainer mySqlContainer = new CassandraContainer();
}

Elasticsearch

Add the Maven dependency

<dependency>
    <groupId>com.github.ydespreaux.testcontainers</groupId>
    <artifactId>testcontainers-elasticsearch</artifactId>
    <version>1.1.0</version>
    <scope>test</scope>
</dependency>

Using Junit 5 (version 1.2.1)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.11.1</version>
    <scope>test</scope>
</dependency>

Quick Start

@RunWith(SpringJUnit4ClassRunner.class)
public class ITElasticsearchTest {

    @ClassRule
    public static final ElasticsearchContainer elasticContainer = new ElasticsearchContainer();
}

By default, the elasticsearch image used is 'elasticsearch / elasticsearch: 5.6.8'. The URL of the image and the version is configurable. Below is an example to use version 6.4.2 of the image.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITElasticsearchTest {

    @ClassRule
    public static final ElasticsearchContainer elasticContainer = new ElasticsearchContainer(Versions.ELASTICSEARCH_VERSION);
}

Note that security is disabled.

When the docker container has started, the following properties are initialized in the spring boot context:

The withRegisterSpringbootProperties (boolean) method is used to initialize or not the spring boot context of the properties above.

The name of the spring boot properties can be changed using the following methods:

Initialization script (since 1.1.0)

An initialization script file can be provided using the fileInitScript parameter, in which case it will be executed against the local Elasticsearch cluster. The file extension defines the file format: json for JSON format, anything else for custom format.

JSON format

The provided JSON file should contain a list of requests to be sent, one by one, to the Elasticsearch cluster. Each request definition has three properties:

• the name (in uppercase) of the request method to be used for the current request (one of PUT, POST, DELETE)
• the path part of the URL (should not start with slash)
• the payload

The payload should not be defined for DELETE requests. Some Elasticsearch requests do not require a payload (eg. POST index/_refresh), in which case define the payload as {}

Example:

To send a POST request to http://localhost:9200/test_index/test_type/_mapping, followed by a DELETE request to http://localhost:9200/test_index/test_type/1:

[
    {
        "method": "POST",
        "path": "test_index/test_type/_mapping",
        "payload": {
            "test_type": {
                "properties": {
                    "name": {
                        "type": "keyword"
                    },
                    "lastModified": {
                        "type": "date"
                    }
                }
            }
        }
    },
    {
        "method": "DELETE",
        "path": "test_index/test_type/1"
    }
]

Custom format

Each line defines a request to be sent to the Elasticsearch cluster, and it has three parts separated by colon ':'

• the name (in uppercase) of the request method to be used for the current request (one of PUT, POST, DELETE)
• the path part of the URL (should not start with slash)
• the JSON to send to Elasticsearch as payload (it should be empty for DELETE requests)

Note: Empty lines are ignored, as well as lines starting with the '#' sign.

Examples :

To send a POST request to http://localhost:9200/test_index/test_type/_mapping:

POST:test_index/test_type/_mapping:{ "test_type" : { "properties" : { "name" : { "type" : "keyword" }, "lastModified" : { "type" : "date" } } } }

To send a DELETE request to http://localhost:9200/test_index/test_type/1 without content; note the colon at the end, for there is no JSON data in case of a DELETE.

DELETE:test_index/test_type/1:

Sample with Junit 5 (version 1.2.1)

@Testcontainers
public class ITElasticsearchTest {

    @Container
    public static final ElasticsearchContainer elasticContainer = new ElasticsearchContainer();
}

Kafka

Add the Maven dependency

<dependency>
    <groupId>com.github.ydespreaux.testcontainers</groupId>
    <artifactId>testcontainers-kafka</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

Using Junit 5 (version 1.2.1)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.11.1</version>
    <scope>test</scope>
</dependency>

Container Kafka

Quick Start

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaContainer kafkaContainer = new ConfluentKafkaContainer();
}

By default the Kafka image used is 'confluentinc / cp-kafka: 3.3.1'.

The version is configurable. Below is an example to use version 4.0.0 of the image.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer("4.0.0");
}

Activate schema registry.

By default, the registry schema is not active. Below is an example to activate the registry schema.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer().withSchemaRegistry(true);
}

Configuration

When the docker container has started, the following properties are initialized in the spring boot context:

The withRegisterSpringbootProperties (boolean) method is used to initialize or not the spring boot context of the properties above.

The name of the spring boot properties can be changed using the following methods:

Access to urls

Topics configuration

Added the withTopic method to create a topic with the name of the topic, the number of partitions and the type of topic compacted or not.

Example:

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer()
        .withTopic("topic1-non-compact", 3, false)
        .withTopic("topic2-compact", 3, true);
}

Sécurité SSL (version 1.2.0).

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    public static final Certificates kafkaServerCertificates = new Certificates("secrets/kafka.server.keystore.jks", "0123456789", "secrets/kafka.truststore.jks", "0123456789");
    public static final Certificates kafkaClientCertificates = new Certificates("secrets/kafka.client.keystore.jks", "0123456789", "secrets/kafka.truststore.jks", "0123456789");

    @ClassRule
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer()
        .withKafkaServerCertificates(kafkaServerCertificates)
        .withKafkaClientCertificates(kafkaClientCertificates)
        .withTopic("TOPIC_1", 1, true)
        .withAcls(new AclsOperation[]{AclsOperation.READ, AclsOperation.WRITE}, "TOPIC_1", "my-group");
}    

When the docker container has started, the properties corresponding to the SSL configuration are initialized in the context of spring boot:

If the client certificate is not initialized when the container is launched, the spring boot properties related to the SSL configuration will not be initialized.

The name of the spring boot properties can be changed using the following methods:

Sample with Junit 5 (version 1.2.1)

@Testcontainers
public class ITKafkaTest {

    @Container
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer("4.0.0");
}

Container Kafka Connect

Quick Start

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaConnectContainer kafkaContainer = new ConfluentKafkaConnectContainer();
}

By default the Kafka connect image used is 'confluentinc / cp-kafka-connect: 4.1.0'. Compatibility of Kafka messages is fixed with version 0.11.0 by default.

The version is configurable. Below is an example to use version 4.0.0 of the image.

@RunWith(SpringJUnit4ClassRunner.class)
public class ITKafkaTest {

    @ClassRule
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer("4.0.0");
}

Configuration

When the docker container has started, the following properties are initialized in the spring boot context:

The withRegisterSpringbootProperties (boolean) method is used to initialize or not the spring boot context of the properties above.

The name of the spring boot properties can be changed using the following methods:

Initialization method of the worker:

In the case of an Avro converter, the registry schema is automatically configured if it has been activated.

Herder initialization method in standalone mode:

Herder initialization method in distributed mode:

Access to urls

Sample with Junit 5 (version 1.2.1)

@Testcontainers
public class ITKafkaTest {

    @Container
    public static final ConfluentKafkaContainer mySqlContainer = new ConfluentKafkaContainer("4.0.0");
}