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

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

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 the plugin for a specific project.
2. Configure the environment provider. You can use DockerComposeEnvProvider or implement a custom one.
3. Optional. Enable automated management during the testing phase. Details

A predefined DockerComposeEnvProvider uses docker compose to manage 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

integrationEnvStart - create the environment.
integrationEnvStop - terminate the environment.

Configuration example

The following setting controls the automated lifecycle management:

Test / testOptions := integrationEnvTestOpts.value

The plugin uses Setup and Cleanup hooks to manage the environment.
Depending on the termination strategy, such as UponTestCompletion or Never, the plugin behaves differently.

The strategy is determined by sbt insideCI command: if insideCI is true the UponTestCompletion strategy is selected, otherwise Never is used.
It can also be configured explicitly:

integrationEnvTerminationStrategy := TerminationStrategy.UponTestCompletion

Termination strategies:

Configuration example

An external docker network is useful when running an SBT build in a docker container within dind.
In this case, you should use a shared network across all components: the SBT container and docker-compose.