# testcontainers-spring-boot **Repository Path**: mirrors_Playtika/testcontainers-spring-boot ## Basic Information - **Project Name**: testcontainers-spring-boot - **Description**: Container auto-configurations for Spring Boot based integration tests - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2022-01-05 - **Last Updated**: 2026-03-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README = Testcontainers Spring Boot https://codecov.io/gh/PlaytikaOSS/testcontainers-spring-boot[image:https://codecov.io/gh/PlaytikaOSS/testcontainers-spring-boot/graph/badge.svg?token=9E0VBFIB5B[codecov]] https://maven-badges.herokuapp.com/maven-central/com.playtika.testcontainers/testcontainers-spring-boot[image:https://maven-badges.herokuapp.com/maven-central/com.playtika.testcontainers/testcontainers-spring-boot/badge.svg[Maven Central]] If you develop services using Spring Boot and maybe Spring Cloud and you do https://testing.googleblog.com/2010/12/test-sizes.html[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. https://www.docker.com/[Docker] and https://www.testcontainers.org/[TestContainers] are used to bootstrap stateful service using Spring Cloud https://cloud.spring.io/spring-cloud-static/spring-cloud.html#_the_bootstrap_application_context[bootstrap phase]. Usage of Spring Cloud in your production code is optional, but __you will need it in tests__. See <> below. == Versions compatibility |=== | Spring Boot | Test Containers Spring Boot |2.5.X, 2.6.X, 2.7.X |2.X.X |3.0.X, 3.1.X |3.0.X |3.2.X, 3.3.X, 3.4.X, 3.5.X |3.1.X |=== [[how-to-use]] == How to use . https://docs.docker.com/install/[Install Docker] on your machine . Make sure you have http://projects.spring.io/spring-cloud/#quick-start[Spring Boot and Spring Cloud] in classpath of your tests. In case if you need to https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-bootstrap[pick version]. + .pom.xml [source,xml] ---- ... org.springframework.cloud spring-cloud-starter-bootstrap [pick version] ... ---- + 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. . If you do not use Spring Cloud - make it work for tests only: + .pom.xml [source,xml] ---- ... org.springframework.boot spring-boot-starter [pick version] org.springframework.cloud spring-cloud-starter-bootstrap [pick version] test ... ---- . Add data service library: + .pom.xml [source,xml] ---- ... com.playtika.testcontainers embedded-kafka [pick version] test ... ---- . Use produced properties in your configuration. + Example: + ./src/test/resources/application.properties [source,properties] ---- spring.kafka.bootstrap-servers=${embedded.kafka.brokerList} ---- + ./src/test/resources/bootstrap.properties [source,properties] ---- embedded.kafka.topicsToCreate=some_topic ---- == In-depth guides, how-tos and samples - https://martinfowler.com/articles/microservice-testing/[Testing Strategies in a Microservice Architecture] - https://dzone.com/articles/advanced-functional-testing-in-spring-boot-by-usin[Functional Testing in Spring Boot Using Docker in Tests] - https://github.com/tdanylchuk/functional-tests-best-practices[Functional tests best practices sample repo] - https://medium.com/@isadounikau/microservices-integration-testing-spring-boot-404b6f8617d1[Spring Boot Microservices Integration Testing] - https://mydeveloperplanet.com/2020/05/05/easy-integration-testing-with-testcontainers[Easy Integration Testing With Testcontainers] - https://dev.to/sivalabs/springboot-integration-testing-using-testcontainers-starter-13h2[SpringBoot Integration Testing using TestContainers Starter] - https://alexromanov.github.io/2019/04/02/spring-boot-docker-containers/[Easy way to test Spring Boot microservices] == Common configuration options === Shutdown of embedded containers on spring application shutdown immediately ./src/test/resources/application.properties [source,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 [source,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 [cols="a,a,a"] |=== |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: https://github.com/testcontainers/testcontainers-java/pull/2555 and https://github.com/testcontainers/testcontainers-java/pull/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}.attachContainerLog |false |Attach embedded container output log. |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}.label |null |key-value map of additional labels to the container. Where key is name of label and value is actual value of label. |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: [source,yaml] ---- 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: [source,yaml] ---- 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. |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 https://docs.docker.com/storage/tmpfs/[TmpFs mount docs]. For example, for MariaDb: [source,yaml] ---- embedded: mariadb: tmp-fs: mounts: - folder: /var/lib/mysql options: rw ---- |=== == Supported services === link:embedded-mariadb/README.adoc[embedded-mariadb] === link:embedded-couchbase/README.adoc[embedded-couchbase] === link:embedded-kafka/README.adoc[embedded-kafka] === link:embedded-native-kafka/README.adoc[embedded-native-kafka] === link:embedded-rabbitmq/README.adoc[embedded-rabbitmq] === link:embedded-aerospike/README.adoc[embedded-aerospike] === link:embedded-memsql/README.adoc[embedded-memsql] === link:embedded-redis/README.adoc[embedded-redis] === link:embedded-neo4j/README.adoc[embedded-neo4j] === link:embedded-postgresql/README.adoc[embedded-postgresql] === link:embedded-elasticsearch/README.adoc[embedded-elasticsearch] === link:embedded-opensearch/README.adoc[embedded-opensearch] === link:embedded-dynamodb/README.adoc[embedded-dynamodb] === link:embedded-voltdb/README.adoc[embedded-voltdb] === link:embedded-minio/README.adoc[embedded-minio] === link:embedded-mongodb/README.adoc[embedded-mongodb] === link:embedded-google-pubsub/README.adoc[embedded-google-pubsub] === link:embedded-google-storage/README.adoc[embedded-google-storage] === link:embedded-keycloak/README.adoc[embedded-keycloak] === link:embedded-keydb/README.adoc[embedded-keydb] === link:embedded-influxdb/README.adoc[embedded-influxdb] === link:embedded-vault/README.adoc[embedded-vault] === link:embedded-oracle-xe/README.adoc[embedded-oracle-xe] === link:embedded-mysql/README.adoc[embedded-mysql] === link:embedded-localstack/README.adoc[embedded-localstack] === link:embedded-cassandra/README.adoc[embedded-cassandra] === link:embedded-clickhouse/README.adoc[embedded-clickhouse] === link:embedded-pulsar/README.adoc[embedded-pulsar] === link:embedded-vertica/README.adoc[embedded-vertica] === link:embedded-prometheus/README.adoc[embedded-prometheus] === link:embedded-grafana/README.adoc[embedded-grafana] === link:embedded-consul/README.adoc[embedded-consul] === link:embedded-artifactory/README.adoc[embedded-artifactory] === link:embedded-azurite/README.adoc[embedded-azurite] === link:embedded-toxiproxy/README.adoc[embedded-toxiproxy] === link:embedded-nats/README.adoc[embedded-nats] === link:embedded-k3s/README.adoc[embedded-k3s] === link:embedded-mockserver/README.adoc[embedded-mockserver] === link:embedded-solr/README.adoc[embedded-solr] === link:embedded-cockroachdb/README.adoc[embedded-cockroachdb] === link:embedded-git/README.adoc[embedded-git] === link:embedded-wiremock/README.adoc[embedded-wiremock] === link:embedded-mailhog/README.adoc[embedded-mailhog] === link:embedded-spicedb/README.adoc[embedded-spicedb] == 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). https://spring.io/blog/2018/03/07/testing-auto-configurations-with-spring-boot-2-0[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 //* Release build is done using https://github.com/aleksandr-m/gitflow-maven-plugin[gitflow-maven-plugin] * Release is done per each major change, critical bug * Release can be done by contributor request * Contacts to start release: ** mailto:sstus@playtika.com[sstus@playtika.com] ** mailto:iyova@playtika.com[iyova@playtika.com] ** mailto:admitrov@playtika.com[admitrov@playtika.com] ** mailto:rkvasnytskyi@playtika.com[rkvasnytskyi@playtika.com]