isabella232 / infobip-testcontainers-spring-boot-starter

Infobip TestContainers Spring Boot Starter provides Spring Boot starters that ease the use of Testcontainers in test and local development scenarios.

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
  • MSSQL
    • Tests
    • Local development
    • Docker image
  • PostgreSQL
    • Tests
    • Local development
    • Docker image
  • Redis
    • Tests
    • Local development
    • Docker image
  • Kafka
    • Automatic topic creation
    • Tests
    • Local development
    • Docker image version
  • RabbitMQ
    • Tests
    • Local development
    • Docker image
  • ClickHouse
    • Tests
    • Local development
    • Docker image version

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.

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

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:10

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: rabbitmq:latest

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.