JarCastingcosy-test
Bringing up Docker Compose environments for system, integration and performance testing, with support for ScalaTest, JUnit 4, JUnit 5, TestNG and Gatling.
Why do I need this?
Imagine you need to test a complex system that requires having a lot of components working and simulating a realistic scenario. Probably, you would just use a docker-compose file to start your environment and then do your tests. That seems easy... But:
- How would you know that the environment is already up and running for testing?
- What if you need to test a lot of those environments concurrently?
- Would you be capable of managing all the container mapped ports without conflicts?
That is where cosy-test can make your life easier.
What is cosy-test and how it helps you?
It is a simple framework that allows integration with several testing frameworks. With cosy-test it is possible to simply use docker compose files and define environment variables in order to start docker environments, run tests and bring environments down without pains and restrictions.
Main features:
- Brings the environments up before the tests and tears them down afterwards.
- Start tests just after all health checks are passing.
- Can be configured to dump container logs for debugging purposes.
- Containers can be kept running on failure, success or both.
- Control your system through environment variables.
- Ports exposed by containers are mapped to the host machine and are made available to the tests. This approach is especially handy on MacOS (as opposed to reaching the containers by their IP addresses).
Requirements
In order for cosy-test to work, it is necessary to have Docker and Docker Compose installed. There are no version restrictions, however we recommend using:
- Docker >= 18.02.0 (older versions have problems during containers start up and/or tear down)
- Docker Compose >= 1.17.1
Usage
SBT
libraryDependencies += "com.feedzai" %% "cosy-test" % "0.0.3"
Maven
<dependency>
<groupId>com.feedzai</groupId>
<artifactId>cosy-test_2.12</artifactId>
<version>0.0.3</version>
</dependency>
Example — ScalaTest
class IntegrationSpec extends FlatSpec with DockerComposeTestSuite with MustMatchers {
def dockerSetup = Some(
DockerComposeSetup(
"scalatest", // Setup name
Seq(Paths.get("src", "test", "resources", "docker-compose-scalatest.yml")), // Docker compose files
Paths.get("").toAbsolutePath, // Docker compose working directory
Map.empty // Environment variables. Example: Map("CONTAINER_EXPOSED_PORT" -> "80")
)
)
behavior of "Scala Test"
it must "Retrieve all services" in {
val expectedServices = Set("container1", "container2", "container3")
dockerSetup.foreach { setup =>
setup.getServices().toSet mustEqual expectedServices
}
}
}
Example — JUnit 4
public class IntegrationSpec {
private static final DockerComposeJavaSetup dockerSetup;
static {
dockerSetup = new DockerComposeJavaSetup(
"junit4test", // Setup name
Collections.singletonList(Paths.get("src", "test", "resources", "docker-compose-junit4.yml")), // Docker compose files
Paths.get("").toAbsolutePath(), // Docker compose working directory
new HashMap<>() // Environment variables. Example: envMap.put("CONTAINER_EXPOSED_PORT", "80")
);
}
@ClassRule
public static DockerComposeRule dockerComposeRule = new DockerComposeRule(SetupManager.builder(dockerSetup).build());
@Rule
public TestWatcher testWatcher = new TestWatcher() {
@Override
protected void failed(Throwable e, Description description) {
dockerComposeRule.setTestFailed(true);
}
};
@Test
public void fetchServices() {
Assert.assertThat(
dockerSetup.getServices(),
containsInAnyOrder("container1", "container2", "container3")
);
}
}
Example — JUnit 5
public class IntegrationSpec {
private static final DockerComposeJavaSetup dockerSetup;
static {
dockerSetup = new DockerComposeJavaSetup(
"junit5test", // Setup name
Collections.singletonList(Paths.get("src", "test", "resources", "docker-compose-junit5.yml")), // Docker compose files
Paths.get("").toAbsolutePath(), // Docker compose working directory
new HashMap<>() // Environment variables. Example: envMap.put("CONTAINER_EXPOSED_PORT", "80")
);
}
@RegisterExtension
static DockerComposeExtension extension = new DockerComposeExtension(SetupManager.builder(dockerSetup).build());
@Test
public void fetchServices() {
Assert.assertThat(
dockerSetup.getServices(),
containsInAnyOrder("container1", "container2", "container3")
);
}
}
Example — TestNG
public class IntegrationSpec extends DockerComposeAbstraction {
private final DockerComposeJavaSetup dockerSetup = new DockerComposeJavaSetup(
"testngtest", // Setup name
Collections.singletonList(Paths.get("src", "test", "resources", "docker-compose-testng.yml")), // Docker compose files
Paths.get("").toAbsolutePath(), // Docker compose working directory
new HashMap<>() // Environment variables. Example: envMap.put("CONTAINER_EXPOSED_PORT", "80")
);
IntegrationSpec() {
setupManager = SetupManager.builder(dockerSetup).build();
}
@Test
public void fetchServices() {
Assert.assertThat(
dockerSetup.getServices(),
containsInAnyOrder("container1", "container2", "container3")
);
}
}
Example — Gatling
class IntegrationSpec extends DockerComposeSimulation {
override def dockerSetup = Some(
DockerComposeSetup(
"gatling", // Setup name
Seq(Paths.get("src", "test", "resources", "docker-compose-gatling.yml")), // Docker compose files
Paths.get("").toAbsolutePath, // Docker compose working directory
Map.empty // Environment variables. Example: Map("CONTAINER_EXPOSED_PORT" -> "80")
)
)
beforeSimulation()
private val HttpProtocol: HttpProtocolBuilder = http
.baseURL("http://localhost:8086")
private val populationBuilder = {
val getAction = http("Gatling simulation").get("")
val s = scenario("Gatling simulation")
s.during(10.seconds)(feed(Iterator.empty).exec(getAction))
.inject(rampUsers(10).over(1.second))
.protocols(HttpProtocol)
}
setUp(populationBuilder)
}
Build, Test and Release
After cloning the repository you can simply build and run the tests, by executing the command:
sbt test
Since cosy-test uses sbt-dynver to release a new version it is just required to create a new tag like:
git tag v1.0.0
