This document introduces TestContainers, an open source tool for running Docker containers as part of integration tests. It discusses why integration testing is important for reproducibility, isolation, and realism. TestContainers allows setting up Docker containers programmatically and automatically cleaning them up after tests complete. It supports starting individual containers, Docker Compose environments, and custom container types. Examples are given for testing services that depend on databases, caches, and external APIs using TestContainers without complex test environment configuration. The document also describes how to use TestContainers to test Java agents by modifying bytecode at runtime within a container during tests.

1. TestContainers
Integration testing without the hassle
@antonarhipov

3. Why integration testing?

9. 1. # of tests per time unit

10. 1. # of tests per time unit
2. Complex setup

12. 1. Reproducible environment

13. 1. Reproducible environment
2. Both for development and CI

14. 1. Reproducible environment
2. Both for development and CI
3. Isolated

15. 1. Reproducible environment
2. Both for development and CI
3. Isolated
4. As real as possible

16. 1. Reproducible environment
2. Both for development and CI
3. Isolated
4. As real as possible
5. Cross-platform

17. 1. Reproducible environment
2. Both for development and CI
3. Isolated
4. As real as possible
5. Cross-platform
6. Easy to set up, use & maintain

19. Docker Compose FTW!
redis:
image: redis
ports:
- "6379:6379"
postgres:
image: postgres
ports:
- "5432:5432"
elasticsearch:
image: elasticsearch:5.0.0
ports:
- "9200:9200"

24. TestContainers to the rescue!

25. How does it work?
https://github.com/docker-java/docker-java
Docker environment discovery
Will start docker machine if it’s not started yet
Containers cleanup on JVM shutdown

26. GenericContainer redis =
new GenericContainer("redis:3.0.6")
.withExposedPorts(6379);

27. GenericContainer redis =
new GenericContainer("redis:3.0.6")
.withExposedPorts(6379);
PostgreSQLContainer postgreSQLContainer =
new PostgreSQLContainer("postgres:9.6.2")
.withUsername(POSTGRES_USERNAME)
.withPassword(POSTGRES_PASSWORD);

28. TestContainers
https://github.com/testcontainers/testcontainers-java

29. Docker Compose? - Yes!
public static DockerComposeContainer env =
new DockerComposeContainer(
new File("src/test/resources/compose-test.yml"))
.withExposedService("redis_1", REDIS_PORT);

30. Docker Compose? - Yes!
public static DockerComposeContainer env =
new DockerComposeContainer(
new File("src/test/resources/compose-test.yml"))
.withExposedService("redis_1", REDIS_PORT);
String url = env.getServiceHost("redis_1", REDIS_PORT);
Integer port = env.getServicePort("redis_1", REDIS_PORT);
Jedis jedis = new Jedis(url, port);

31. Microservices!11
REST service
Java, Spring Boot
Redis & PostgreSQL
Calls some other micro-services

32. @RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = DemoApplication.class,
webEnvironment = WebEnvironment.RANDOM_PORT)
@ContextConfiguration(initializers = AbstractIntegrationTest.Initializer.class)
public abstract class AbstractIntegrationTest {
@ClassRule
public static PostgreSQLContainer postgreSql = new PostgreSQLContainer();
@ClassRule
public static GenericContainer redis = new GenericContainer("redis:3.0.6")
.withExposedPorts(6379);
@ClassRule
public static MockServerContainer mockServer = new MockServerContainer();

33. @RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = DemoApplication.class,
webEnvironment = WebEnvironment.RANDOM_PORT)
@ContextConfiguration(initializers = AbstractIntegrationTest.Initializer.class)
public abstract class AbstractIntegrationTest {
@ClassRule
public static PostgreSQLContainer postgreSql = new PostgreSQLContainer();
@ClassRule
public static GenericContainer redis = new GenericContainer("redis:3.0.6")
.withExposedPorts(6379);
@ClassRule
public static MockServerContainer mockServer = new MockServerContainer();
Still using all the
Spring goodies!

34. @RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = DemoApplication.class,
webEnvironment = WebEnvironment.RANDOM_PORT)
@ContextConfiguration(initializers = AbstractIntegrationTest.Initializer.class)
public abstract class AbstractIntegrationTest {
@ClassRule
public static PostgreSQLContainer postgreSql = new PostgreSQLContainer();
@ClassRule
public static GenericContainer redis = new GenericContainer("redis:3.0.6")
.withExposedPorts(6379);
@ClassRule
public static MockServerContainer mockServer = new MockServerContainer();
External
dependencies

36. public class MockServerContainer<SELF extends MockServerContainer<SELF>>
extends GenericContainer<SELF> {
public MockServerContainer() {
super("jamesdbloom/mockserver:latest");
addExposedPorts(8080);
}
private MockServerClient client;
@Override
protected void containerIsStarted(InspectContainerResponse containerInfo) {
super.containerIsStarted(containerInfo);
client = new MockServerClient(getContainerIpAddress(),
getMappedPort(getExposedPorts().get(0)));
}
}

37. public class MockServerContainer<SELF extends MockServerContainer<SELF>>
extends GenericContainer<SELF> {
public MockServerContainer() {
super("jamesdbloom/mockserver:latest");
addExposedPorts(8080);
}
private MockServerClient client;
@Override
protected void containerIsStarted(InspectContainerResponse containerInfo) {
super.containerIsStarted(containerInfo);
client = new MockServerClient(getContainerIpAddress(),
getMappedPort(getExposedPorts().get(0)));
}
}

38. MockServerClient client = …
client.when(
HttpRequest.request("/analytics/issues/" +
project.projectId + "/app").withMethod("GET"),
Times.unlimited())
.respond(singleIssueResponse());

41. How to test Java agents?

42. public static void premain(String args, Instrumentation instrumentation) {
instrumentation.addTransformer(new ClassFileTransformer() {
@Override
public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
ProtectionDomain protectionDomain, byte[] classfileBuffer)
throws IllegalClassFormatException {
if ("spark/webserver/JettyHandler".equals(className)) {
try {
ClassPool cp = new ClassPool();
cp.appendClassPath(new LoaderClassPath(loader));
CtClass ct = cp.makeClass(new ByteArrayInputStream(classfileBuffer));
CtMethod ctMethod = ct.getDeclaredMethod("doHandle");
ctMethod.insertBefore("{ $4.setHeader("X-My-Super-Header", "header value"); }");
return ct.toBytecode();
} catch (Throwable e) {
e.printStackTrace();
}
}
return classfileBuffer;
}
});
}

43. public static void premain(String args, Instrumentation instrumentation) {
instrumentation.addTransformer(new ClassFileTransformer() {
@Override
public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
ProtectionDomain protectionDomain, byte[] classfileBuffer)
throws IllegalClassFormatException {
if ("spark/webserver/JettyHandler".equals(className)) {
try {
ClassPool cp = new ClassPool();
cp.appendClassPath(new LoaderClassPath(loader));
CtClass ct = cp.makeClass(new ByteArrayInputStream(classfileBuffer));
CtMethod ctMethod = ct.getDeclaredMethod("doHandle");
ctMethod.insertBefore("{ $4.setHeader("X-My-Super-Header", "header value"); }");
return ct.toBytecode();
} catch (Throwable e) {
e.printStackTrace();
}
}
return classfileBuffer;
}
});
}

44. public static void premain(String args, Instrumentation instrumentation) {
instrumentation.addTransformer(new ClassFileTransformer() {
@Override
public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
ProtectionDomain protectionDomain, byte[] classfileBuffer)
throws IllegalClassFormatException {
if ("spark/webserver/JettyHandler".equals(className)) {
try {
ClassPool cp = new ClassPool();
cp.appendClassPath(new LoaderClassPath(loader));
CtClass ct = cp.makeClass(new ByteArrayInputStream(classfileBuffer));
CtMethod ctMethod = ct.getDeclaredMethod("doHandle");
ctMethod.insertBefore("{ $4.setHeader("X-My-Super-Header", "header value"); }");
return ct.toBytecode();
} catch (Throwable e) {
e.printStackTrace();
}
}
return classfileBuffer;
}
});
}

45. public class AgentTest {
@ClassRule
public static BasicTestApp app = new BasicTestApp();
@Test
public void testIt() throws Exception {
Response response = app.getClient().getHello();
System.out.println("Got response:n" + response);
assertThat(response.headers().get("X-My-Super-Header"))
.isNotNull()
.hasSize(1)
.containsExactly("header value");
}
}

46. public class AgentTest {
@ClassRule
public static BasicTestApp app = new BasicTestApp();
@Test
public void testIt() throws Exception {
Response response = app.getClient().getHello();
System.out.println("Got response:n" + response);
assertThat(response.headers().get("X-My-Super-Header"))
.isNotNull()
.hasSize(1)
.containsExactly("header value");
}
}
A custom
container

47. public class AgentTest {
@ClassRule
public static BasicTestApp app = new BasicTestApp();
@Test
public void testIt() throws Exception {
Response response = app.getClient().getHello();
System.out.println("Got response:n" + response);
assertThat(response.headers().get("X-My-Super-Header"))
.isNotNull()
.hasSize(1)
.containsExactly("header value");
}
}
Verify, if the
new behaviour is
there

48. https://github.com/bsideup/javaagent-boilerplate

49. https://www.testcontainers.org
https://twitter.com/testcontainers
https://github.com/testcontainers
https://testcontainers.slack.com

50. anton@zeroturnaround.com
@antonarhipov
slideshare.net/arhan