README.md

Infobip Testcontainers Spring Boot Starter

Library containing Spring Boot starters which manage lifecycle (start/stop) of testcontainers.

Usual use cases include:

• tests (container is started during test spring context initialization and stopped during context destruction)
• local development (e.g. to remove manual setup of local DB)

Contents

• Changelog
• Usage
  • General
  • Reusable
  • MSSQL
    • Tests
    • Local development
    • Docker image version
    • Initialization script
  • MySQL
    • Tests
    • Local development
    • Docker image version
    • Initialization script
  • PostgreSQL
    • Tests
    • Local development
    • Docker image version
    • Initialization script
  • Redis
    • Tests
    • Local development
    • Docker image version
  • Kafka
    • Automatic topic creation
    • Tests
    • Local development
    • Docker image version
  • RabbitMQ
    • Tests
    • Local development
    • Docker image version
  • ClickHouse
    • Tests
    • Local development
    • Docker image version
    • Initialization script

Changelog

For changes check the changelog.

Usage

General

This library tries to reuse existing Spring Boot configuration classes and enhance their behaviour by performing some extra steps around them. Generally, in cases where port placeholders are used (<port>), the library will make sure that the appropriate Docker container is started on a randomly selected open port and that the selected value will be used by the configuration in the runtime. You can use a concrete value instead of the placeholder - in that case the library will attempt to start the container on the specified port.

Reusable

If reuse is enabled this project automatically marks all created containers for reuse.

MSSQL

Disclaimer: by using this testcontainer you accept the EULA for mssql docker image as required here.

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-mssql-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-mssql-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

jTDS:

spring:
  datasource:
    url: jdbc:jtds:sqlserver://<host>:<port>/FooBarDb

Microsoft driver:

spring:
  datasource:
    url: jdbc:sqlserver://<host>:<port>;database=FooBarDb

Logical database is automatically created. Container IP address is resolved based on running host, meaning on local machine <host> will resolve to localhost while inside Docker placeholder will resolve to containerIp. When <port> placeholder is used, container will be mapped on random port and automatically substituted.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-mssql-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-mssql-testcontainers-spring-boot-starter.version}</version>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

jTDS:

spring:
  datasource:
    url: jdbc:jtds:sqlserver://<host>:<port>/FooBarDb_test_${user.name}

Microsoft driver:

spring:
  datasource:
    url: jdbc:sqlserver://<host>:<port>;database=FooBarDb_test_${user.name}

Docker image:

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.mssql.docker.image: mcr.microsoft.com/mssql/server:2017-CU12

Initialization script

To add an SQL script with which the container will be initialized with add the following property (e.g. in yaml):

testcontainers.mssql.init-script: db/init-script.sql

MySQL

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-mysql-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-mysql-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Configuration:

spring:
  datasource:
    url: jdbc:mysql://<host>:<port>/FooBarDb
    username: test
    password: test

Logical database is automatically created. Container IP address is resolved based on running host, meaning on local machine <host> will resolve to localhost while inside Docker placeholder will resolve to containerIp. When <port> placeholder is used, container will be mapped on random port and automatically substituted.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-mysql-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-mysql-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

spring:
  datasource:
    url: jdbc:mysql://<host>:<port>/FooBarDb_test_${user.name}
    username: test
    password: test

Docker image:

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.mysql.docker.image: mysql:5.7.34

Initialization script

To add an SQL script with which the container will be initialized with add the following property (e.g. in yaml):

testcontainers.mysql.init-script: db/init-script.sql

PostgreSQL

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-postgresql-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-postgresql-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Configuration:

spring:
  datasource:
    url: jdbc:postgresql://<host>:<port>/FooBarDb
    username: test
    password: test

Logical database is automatically created. Container IP address is resolved based on running host, meaning on local machine <host> will resolve to localhost while inside Docker placeholder will resolve to containerIp. When <port> placeholder is used, container will be mapped on random port and automatically substituted.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-postgresql-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-postgresql-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

spring:
  datasource:
    url: jdbc:postgresql://<host>:<port>/FooBarDb_test_${user.name}
    username: test
    password: test

Docker image:

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.postgresql.docker.image: postgres:15

Initialization script

To add an SQL script with which the container will be initialized with add the following property (e.g. in yaml):

testcontainers.postgresql.init-script: db/init-script.sql

Redis

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-redis-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-redis-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Configuration:

spring:
  redis:
    url: redis://<host>:<port>

Container IP address is resolved based on running host, meaning on local machine <host> will resolve to localhost while inside Docker placeholder will resolve to containerIp. When <port> placeholder is used, container will be mapped on random port and automatically substituted.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-redis-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-redis-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

spring:
  redis:
    url: redis://<host>:<port>

Docker image:

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.redis.docker.image: redis:5.0.7-alpine

Kafka

Automatic topic creation

Format: <topicName>:<numPartitions>:<replicationFactor>

testcontainers.kafka.topics: test-topic:1:1, test-topic-2:1:1

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-kafka-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-kafka-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Configuration:

spring:
  kafka:
    bootstrap-servers: <host>:<port>

Logical database is automatically created. Container IP address is resolved based on running host, meaning on local machine <host> will resolve to localhost while inside Docker placeholder will resolve to containerIp. When <port> placeholder is used, container will be mapped on random port and automatically substituted.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-kafka-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-kafka-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

spring:
  kafka:
    bootstrap-servers: <host>:<port>

Docker image:

To change the docker image version used simply add the following property (e.g. in yaml):

testcontainers.kafka.docker.image.version: 2.1.0

RabbitMq

Tests:

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-rabbitmq-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-rabbitmq-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Test Configuration:

To configure RabbitMq in tests you need to create it's configuration for example:

@Configuration
@Profile({"test", "development"})
public class RabbitConfigTestEnv {

    @Bean
    public Queue testQueue() {
        return QueueBuilder.durable("test.queue").build();
    }

    @Bean
    public TopicExchange testExchange() {
        return new TopicExchange("test.exchange");
    }

    @Bean
    public Binding bindToTestExchange() {
        return bind(testQueue()).to(testExchange()).with("test.key.#");
    }
}

This class should live inside test files and there you can create queues, exchanges and key routing bindings or receivers. In this example method:

• testQueue creates queue with name test.queue
• testExchange creates exchange with name test.exchange
• bindToTestExchange tells Rabbit to send any message sent to test exchange, with key of value test.key.# to our test queue

Important: Queues are declared in Rabbit only after some message is sent to the queue. If you log into docker and try to find queue, it won't be listed if no message was sent to it.

Local Development:

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-rabbitmq-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-rabbitmq-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

Docker image:

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.rabbit.docker.image: rabbitmq:3.6.14-alpine

ClickHouse

Tests

Include the dependency:

<dependency>
	<groupId>com.infobip</groupId>
	<artifactId>infobip-clickhouse-testcontainers-spring-boot-starter</artifactId>
	<version>${infobip-clickhouse-testcontainers-spring-boot-starter.version}</version>
	<scope>test</scope>
</dependency>

Local development

Add the following profile:

<profiles>
    <profile>
        <id>development</id>
        <dependencies>
            <dependency>
                <groupId>com.infobip</groupId>
                <artifactId>infobip-clickhouse-testcontainers-spring-boot-starter</artifactId>
                <version>${infobip-clickhouse-testcontainers-spring-boot-starter.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Before starting the application locally, activate development profile:

and update your local configuration (e.g. application-development.yaml):

spring:
  datasource:
    jdbc-url: <host>:<port>

In case your datasource configuration is different from default one you can provide custom configuration property path

testcontainers.clickhouse.custom-path: "spring.datasource.clickhouse"

in this case your configuration would look like this

spring:
  datasource:
      clickhouse:
        jdbc-url: <host>:<port>

Docker image version

To change the docker image used simply add the following property (e.g. in yaml):

testcontainers.clickhouse.docker.image: clickhouse:latest

Initialization script

To add an SQL script with which the container will be initialized with add the following property (e.g. in yaml):

testcontainers.clickhouse.init-script: db/init-script.sql

Contributing

If you have an idea for a new feature or want to report a bug please use the issue tracker.

Pull requests are welcome!

License

This library is licensed under the Apache License, Version 2.0.