sbt-integration-env

sbt-integration-env is an SBT plugin for environment management.
You can create and terminate the environment within SBT, or configure automated management during the execution of tests.

Quick Start

To use sbt-integration-env in an existing SBT project (1.3.+), add the following dependency to your plugins.sbt:

addSbtPlugin("io.github.irevive" % "sbt-integration-env" % "0.4.0")

Usage Guide

There are three steps to start using the plugin:

lazy val root = project
  .in(file("."))
  .enablePlugins(IntegrationEnvPlugin) // 1
  .settings(
    integrationEnvProvider := IntegrationEnv.DockerCompose.Provider( // 2
      composeProjectName = s"${name.value}-it-env", 
      dockerComposeFile = baseDirectory.value / "docker-compose.yml", 
      network = None
    ),
    Test / testOptions := integrationEnvTestOpts.value, // 3
    Test / fork := true
  )

1. Enable plugin for a specific project.
2. Configure environment provider. You can use DockerComposeEnvProvider or implement a custom one.
3. Optional. Enable automated management during the testing phase. Details

Environment provider

There is a predefined DockerComposeEnvProvider which uses docker-compose (or docker compose for a newer docker version) for manipulations with the environment.

IntegrationEnv.DockerCompose.Provider(
  composeProjectName = s"${name.value}-it-env", // 1
  dockerComposeFile = baseDirectory.value / "docker-compose.yml", // 2
  network = Some(s"${name.value}-it-network") // 3
)

1. Name of the docker-compose project. Details
2. Path to the docker-compose file.
3. External docker network. Details

Manual creation and termination

integrationEnvStart - create environment.
integrationEnvStop - terminate environment.

Automated creation and termination

Configuration example

Setting:

Test / testOptions := integrationEnvTestOpts.value

The plugin uses Setup and Cleanup hooks for manipulations. Based on the termination strategy (UponTestCompletion, OnSbtExit, Never) the plugin behaves differently.

The strategy is determined by SBT's insideCI command: if insideCI is true the UponTestCompletion strategy is selected, otherwise the Never is used.
It can be configured explicitly as well:

integrationEnvTerminationStrategy := TerminationStrategy.UponTestCompletion

Termination strategies:

1. UponTestCompletion
   Before tests: terminate if exist, then create new
   After tests: terminate

2. Never
   Before tests: create new if not exist
   After tests: do not terminate

External docker network

Configuration example

External docker network is useful when you are running SBT build in docker container within dind.
At this point, you should use a shared network across all components: SBT container and docker-compose.