/testcontainers-spring-boot

Container auto-configurations for Spring Boot based integration tests

Primary LanguageJavaMIT LicenseMIT

Testcontainers Spring Boot

codecov Maven Central

If you develop services using Spring Boot and maybe Spring Cloud and you do medium sized tests during build process, then this set of Spring Boot auto-configurations might be handy. By adding module into classpath, you will get stateful service, like Couchbase or Kafka, auto-started and available for connection from your application service w/o wiring any additional code. Docker and TestContainers are used to bootstrap stateful service using Spring Cloud bootstrap phase. Usage of Spring Cloud in your production code is optional, but you will need it in tests. See How to use below.

How to use

  1. Install Docker on your machine

  2. Make sure you have Spring Boot and Spring Cloud in classpath of your tests. In case if you need to pick version.

    pom.xml
    <project>
...
      <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-bootstrap</artifactId>
            <!-- https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-bootstrap -->
            <version>[pick version]</version>
        </dependency>
...
</project>
    Note
    		 testcontainers-spring-boot project migrated to Spring Boot 2.4 in 2.0.0 version. Please note, that in order to use this project with Spring Boot 2.4, you need to use spring-cloud-starter-bootstrap dependency. For earlier Spring Boot (prior to 2.4) users — you need to use spring-cloud-starter dependency instead.

  3. If you do not use Spring Cloud - make it work for tests only:

    pom.xml
    <project>
...
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter -->
            <version>[pick version]</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-bootstrap</artifactId>
            <!-- https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-bootstrap -->
            <version>[pick version]</version>
            <scope>test</scope>
        </dependency>
...
</project>

  4. Add data service library:

    pom.xml
    <project>
...
        <dependency>
            <groupId>com.playtika.testcontainers</groupId>
            <artifactId>embedded-kafka</artifactId>
            <!-- https://mvnrepository.com/artifact/com.playtika.testcontainers/ -->
            <version>[pick version]</version>
            <scope>test</scope>
        </dependency>
...
</project>

  5. Use produced properties in your configuration.

    Example:

    /src/test/resources/application.properties
    spring.kafka.bootstrap-servers=${embedded.kafka.brokerList}
    /src/test/resources/bootstrap.properties
    embedded.kafka.topicsToCreate=some_topic

In-depth guides, how-tos and samples

Common configuration options

Shutdown of embedded containers on spring application shutdown immediately

/src/test/resources/application.properties
embedded.containers.forceShutdown=true #default is false
Note
 Otherwise, it will be shutdown with delay, see https://github.com/testcontainers/moby-ryuk

Disable all embedded containers

/src/test/resources/bootstrap.properties
embedded.containers.enabled=true #default is true
Note
 If you setup, for example embedded.kafka.enabled + embedded.containers.enabled, result will be same as using AND between two booleans.
Note
 embedded.kafka.enabled=false will cause DockerNotPresentException if you don’t have docker installed. But embedded.containers.enabled=false won’t cause any exceptions in this case.
Setting1 Setting2 Outcome

embedded.containers.enabled=false

embedded.memsql.enabled=true

Memsql will not start

embedded.containers.enabled=true

embedded.memsql.enabled=false

Memsql will not start

embedded.containers.enabled=true

embedded.memsql.enabled=true

Memsql will start

embedded.containers.enabled is missing

embedded.memsql.enabled is missing

Memsql will start

Other specific container related properties

Setting name Default value Description

embedded.{module-name}.dockerImage

Depends on module

Full Docker image name for container setup. Most of the modules have default value already setup.

embedded.{module-name}.dockerImageVersion

N/A

Use this property if you want to override only Docker image’s version.

embedded.{module-name}.waitTimeoutInSeconds

60

Waiting time for a container to start in seconds

embedded.{module-name}.enabled

true

Enables a container to be started on startup

embedded.{module-name}.reuseContainer

false

Enables a reuse container Testcontainers feature. For more info please refer to: testcontainers/testcontainers-java#2555 and testcontainers/testcontainers-java#1781.

embedded.{module-name}.command

null

List of keywords which combines into command for container startup. Some modules ship container’s commands by default, so resetting this value may lead to incorrect work of container.

embedded.{module-name}.env

null

key-value map of additional environment variables. Where key is name of variable and value is actual value of it.

embedded.{module-name}.filesToInclude

empty list

List of files to include objects. Each object should have two parameters:

  • classpathResource (path to local file)

  • containerPath (path in a container to where file needs to be copied)

Example:

embedded.redis.filesToInclude:
  classpathResource: "/my_local_file.txt"
  containerPath: "/etc/path_in_container.txt"

embedded.{module-name}.mountVolumes

empty list

List of mount volumes to persist between container restarts. Each object should have three parameters:

  • hostPath (path to local file/directory)

  • containerPath (path in container to mount file/directory onto)

  • mode (access mode default READ_ONLY, or READ_WRITE)

Example:

embedded.postgresql.mountVolumes:
  hostPath: "pgdata"
  containerPath: "/var/lib/postgresql/data"
  mode: READ_WRITE

embedded.{module-name}.capabilities

empty list. NET_ADMIN is set for Aerospike, Couchbase, Elasticsearch, Kafka, Mariadb, Memsql, Minio, Mongodb, Mysql, Neo4j, Redis containers. NOTE: NET_ADMIN is needed for the NetworkTestOperations to work.

The Linux capabilities that should be enabled. You can disable all capabilities by providing empty value for this property. See: https://man7.org/linux/man-pages/man7/capabilities.7.html. Available values can be taken from com.github.dockerjava.api.model.Capability class.

embedded.{module-name}.tmpFs.mounts

empty list

A list of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. Check TmpFs mount docs.

For example, for MariaDb:

embedded:
  mariadb:
    tmp-fs:
      mounts:
        - folder: /var/lib/mysql
          options: rw

Supported services

How to contribute

Flow

  • You need to fork project and create branch from develop

  • You do not need to update project version in pom.xml files, this will be done by release job

  • Once finished - create pull request to develop from your fork, pass review and wait for merge

  • On release, ci job will update to next release version + publish artifacts to the Maven Central

Checklist for contributing new module

  • Naming/formatting patterns match existing code

  • Test for success scenario

  • Test for negative scenario (autoconfiguration is disabled via properties). How to test autoconfiguration

  • Add new module to testcontainers-spring-boot-bom

  • Module provides documentation in README.adoc and this documentation is included in parent README.adoc (see an example in already existing modules). Documentation should include:

    • maven module declaration

    • consumed properties

    • produced properties

    • notes (if applicable)

    • example of usage

Release