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 scalatest
dependency 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 custom setup for you environment, you need to override dockerFactory
field, providing DockerClient
instance
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-config
enables you to use a typesafe config to
define your docker containers. Just put an application.conf
file 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
}
- Cassandra =>
docker.cassandra
- Elasticsearch =>
docker.elasticsearch
- Kafka =>
docker.kafka
- Mongodb =>
docker.mongo
- Neo4j =>
docker.neo4j
- Postgres =>
docker.postgres
image-name
required (String)environmental-variables
optional (Array of Strings)ready-checker
optional structurelog-line
optional (String)http-response-code
code
optional (Int - defaults to200
)port
required (Int)path
optional (String - defaults to/
)within
optional (Int)looped
optional structureattempts
required (Int)delay
required (Int)
port-maps
optional structure (list of structures)SOME_MAPPING_NAME
internal
required (Int)external
optional (Int)
volume-maps
optional structure (list of structures)container
required (String)host
required (String)rw
optional (Boolean - default:false)
There are two testkits available -- one for scalatest
and 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