Need help with docker-it-scala?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

424 Stars 89 Forks MIT License 294 Commits 32 Opened issues


Docker integration testing kit with Scala

Services available


Need anything else?

Contributors list


Build Status Maven Central Join the chat at

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


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

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

Overriding execution environment

If you need to have a custom environment setup, you need to override

field, providing
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.


export DOCKER_HOST=tcp://
export DOCKER_HOST=unix:///var/run/docker.sock

Sample Services

Defining Containers

There are two ways to define a docker container.

Code based definitions and via


Code based definitions

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

Typesafe Configuration

enables you to use a typesafe config to define your docker containers. Just put an
file in your classpath.

The container definitions are nested in the structure of name

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 }

Container Paths

  • Cassandra =>
  • Elasticsearch =>
  • Kafka =>
  • Mongodb =>
  • Neo4j =>
  • Postgres =>


  • image-name
    required (String)
  • environmental-variables
    optional (Array of Strings)
  • ready-checker
    optional structure
    • log-line
      optional (String)
    • http-response-code
    • code
      optional (Int - defaults to
    • port
      required (Int)
    • path
      optional (String - defaults to
    • within
      optional (Int)
    • looped
      optional structure
      • attempts
        required (Int)
      • delay
        required (Int)
  • port-maps
    optional structure (list of structures)
    • 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

and one for

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.

Using in ScalaTest:

class MyMongoSpec extends FlatSpec with Matchers with DockerMongodbService {

With Multiple containers:

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.forall(.isReady().futureValue) shouldBe true } }

Using in Specs2

Examples can be found in the specs2 module's tests

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.