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.8" % "test",
  "com.whisk" %% "docker-testkit-impl-spotify" % "0.9.8" % "test")

docker-java

libraryDependencies ++= Seq(
  "com.whisk" %% "docker-testkit-scalatest" % "0.9.8" % "test",
  "com.whisk" %% "docker-testkit-impl-docker-java" % "0.9.8" % "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

• Cassandra
• Elasticsearch
• Kafka
• Mongodb
• Neo4j
• Postgres

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)
• container-name optional (String)
• command optional (Array of Strings)
• entrypoint optional (Array of Strings)
• environmental-variables optional (Array of Strings)
• ready-checker optional structure
  • log-line optional (String)
  • http-response-code
    • code optional (Int - defaults to 200)
    • 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)
  • 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)
• memory optional (Long)
• memory-reservation optional (Long)

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