Awesome Open Source
Awesome Open Source

= Data services library[image:[codecov]][image:[Codacy Badge]][image:[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, How to use>> below.

[[how-to-use]] == How to use

.[Install Docker] on your machine . Make sure you have[Spring Boot and Spring Cloud] in classpath of your tests. In case if you need to[pick version]. + .pom.xml [source,xml]

... 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] 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/ [source,properties]


./src/test/resources/ [source,properties]


== In-depth guides, how-tos and samples

== Common configuration options === Shutdown of embedded containers on spring application shutdown immediately ./src/test/resources/ [source,properties]

embedded.containers.forceShutdown=true //default is false

NOTE: Otherwise, it will be shutdown with delay, see

=== Disables all embedded containers

./src/test/resources/ [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).[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

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
java (30,394
docker (2,740
redis (907
mongodb (776
spring-boot (728
kafka (397
rabbitmq (243
oracle (115
dynamodb (99
neo4j (96
mariadb (91
vault (75
keycloak (33
minio (19
couchbase (15

Find Open Source By Browsing 7,000 Topics Across 59 Categories