whisklabs / docker-it-scala

Docker integration testing kit with Scala

docker-it-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.

Setup

docker-it-scala works with Spotify's docker-client to communicate to docker engine through REST API or unix socket.

• Spotify's docker-client (used in Whisk)

libraryDependencies ++= Seq(
  "com.whisk" %% "docker-testkit-scalatest" % "0.11.0" % "test"

Configuration

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

Sample Services

• Elasticsearch
• Mongodb
• MySQL
• Postgres
• Clickhouse
• Multi container test

Defining Containers

There are two ways to define a docker container.

Code based definitions and via typesafe-config.

Code based definitions

import com.whisk.docker.testkit.scalatest.DockerTestKitForAll
import org.scalatest.Suite

trait DockerMongodbService extends DockerTestKitForAll {
  self: Suite =>

  val DefaultMongodbPort = 27017

  val mongodbContainer = ContainerSpec("mongo:3.4.8")
    .withExposedPorts(DefaultMongodbPort)
    .withReadyChecker(DockerReadyChecker.LogLineContains("waiting for connections on port"))
    .toContainer

  override val managedContainers: ManagedContainers = mongodbContainer.toManagedContainer
}

You can check usage example

Container Paths

• Elasticsearch => docker.elasticsearch
• Mongodb => docker.mongo
• Neo4j => docker.mysql
• Postgres => docker.postgres
• Clickhouse => docker.clickhouse

Fields

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

Testkit

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.

Using in ScalaTest:

class MyMongoSpec extends FlatSpec with Matchers with DockerMongodbService {
  ...
}

With Multiple containers:

class MultiContainerTest
  extends AnyFunSuite
    with DockerElasticsearchService
    with DockerMongodbService {

  override val managedContainers: ContainerGroup =
    ContainerGroup.of(elasticsearchContainer, mongodbContainer)

  test("both containers should be ready") {
    assert(
      elasticsearchContainer.state().isInstanceOf[ContainerState.Ready],
      "elasticsearch container is ready"
    )
    assert(elasticsearchContainer.mappedPortOpt(9200).nonEmpty, "elasticsearch port is exposed")

    assert(mongodbContainer.state().isInstanceOf[ContainerState.Ready], "mongodb is ready")
    assert(mongodbContainer.mappedPortOpt(27017).nonEmpty, "port 2017 is exposed")
  }
}