Docker integration testing kit with Scala
Set of utility classes to make integration testing with dockerised services in Scala easy.
You can read about reasoning behind it at Finely Distributed.
docker-it-scala can work with two underlying libraries to communicate to docker engine through REST API or unix socket. - Spotify's docker-client (used in Whisk) - docker-java
Note: there is no specific recommendation to use one of them, over the other, but we hear people using Spotify's one more often, so you might get better support for it.
There are separate artifacts available for these libraries:
Spotify's docker-client
libraryDependencies ++= Seq( "com.whisk" %% "docker-testkit-scalatest" % "0.9.9" % "test", "com.whisk" %% "docker-testkit-impl-spotify" % "0.9.9" % "test")
docker-java
libraryDependencies ++= Seq( "com.whisk" %% "docker-testkit-scalatest" % "0.9.9" % "test", "com.whisk" %% "docker-testkit-impl-docker-java" % "0.9.9" % "test")
You don't necessarily have to use
scalatestdependency as demonstrated above. You can create your custom bindings into your test environment, whether you use different initialisation technique or different framework. Have a look at this specific trait
If you need to have a custom environment setup, you need to override
dockerFactoryfield, providing
DockerClientinstance
import com.spotify.docker.client.{DefaultDockerClient, DockerClient} import com.whisk.docker.{DockerFactory, DockerKit}trait MyCustomDockerKitSpotify extends DockerKit {
private val client: DockerClient = DefaultDockerClient.fromEnv().build()
override implicit val dockerFactory: DockerFactory = new SpotifyDockerFactory(client) }
Check docker-client library project for configuration options.
You should be able to provide configuration purely through environment variables.
Examples:
export DOCKER_HOST=tcp://127.0.0.1:2375
export DOCKER_HOST=unix:///var/run/docker.sock
There are two ways to define a docker container.
Code based definitions and via
typesafe-config.
import com.whisk.docker.{DockerContainer, DockerKit, DockerReadyChecker}trait DockerMongodbService extends DockerKit {
val DefaultMongodbPort = 27017
val mongodbContainer = DockerContainer("mongo:3.0.6") .withPorts(DefaultMongodbPort -> None) .withReadyChecker(DockerReadyChecker.LogLineContains("waiting for connections on port")) .withCommand("mongod", "--nojournal", "--smallfiles", "--syncdelay", "0")
abstract override def dockerContainers: List[DockerContainer] = mongodbContainer :: super.dockerContainers }
You can check usage example
docker-testkit-configenables you to use a typesafe config to define your docker containers. Just put an
application.conffile in your classpath.
The container definitions are nested in the structure of name
docker
docker { ... ... }
See application.conf for more examples.
Usage in code
trait DockerMongodbService extends DockerKitConfig {val mongodbContainer = configureDockerContainer("docker.mongodb")
abstract override def dockerContainers: List[DockerContainer] = mongodbContainer :: super.dockerContainers }
docker.cassandra
docker.elasticsearch
docker.kafka
docker.mongo
docker.neo4j
docker.postgres
image-namerequired (String)
environmental-variablesoptional (Array of Strings)
ready-checkeroptional structure
log-lineoptional (String)
http-response-code
codeoptional (Int - defaults to
200)
portrequired (Int)
pathoptional (String - defaults to
/)
withinoptional (Int)
loopedoptional structure
attemptsrequired (Int)
delayrequired (Int)
port-mapsoptional structure (list of structures)
SOME_MAPPING_NAME
internalrequired (Int)
externaloptional (Int)
volume-mapsoptional structure (list of structures)
containerrequired (String)
hostrequired (String)
rwoptional (Boolean - default:false)
There are two testkits available -- one for
scalatestand one for
specs2.
Both set up the necessary docker containers and check that they are ready BEFORE any test is run, and doesn't close the container until ALL the tests are run.
class MyMongoSpec extends FlatSpec with Matchers with DockerMongodbService { ... }
class AllAtOnceSpec extends FlatSpec with Matchers with BeforeAndAfterAll with GivenWhenThen with ScalaFutures with DockerElasticsearchService with DockerCassandraService with DockerNeo4jService with DockerMongodbService {implicit val pc = PatienceConfig(Span(20, Seconds), Span(1, Second))
"all containers" should "be ready at the same time" in { dockerContainers.map(.image).foreach(println) dockerContainers.forall(.isReady().futureValue) shouldBe true } }
Examples can be found in the specs2 module's tests