Playtika / Testcontainers Spring Boot

= Data services library

https://codecov.io/gh/Playtika/testcontainers-spring-boot[image:https://codecov.io/gh/testcontainers/testcontainers-spring-boot/branch/master/graph/badge.svg[codecov]] https://www.codacy.com/app/PlaytikaCodacy/testcontainers-spring-boot?utm_source=github.com&utm_medium=referral&utm_content=testcontainers/testcontainers-spring-boot&utm_campaign=Badge_Grade[image:https://api.codacy.com/project/badge/Grade/add0d68eb8e040a1833a8f457189af7b[Codacy Badge]] 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 <<how-to-use, How to use>> below.

[[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

=== Disables 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 |=== |Setting name | Default value |Description

|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.

|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 a|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"

|===

== 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-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-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-keycloak/README.adoc[embedded-keycloak]

=== 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]

== How to contribute

=== Flow

• There are 2 branches in project: master and develop
• 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 merge develop into master and remove snapshot + publish artifacts into public maven repo

=== 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:[email protected][[email protected]] ** mailto:[email protected][[email protected]] ** mailto:[email protected][[email protected]]