Testcontainers Fundamentals

<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <scope>test</scope>
</dependency>

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.Network;
import org.testcontainers.containers.output.Slf4jLogConsumer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.images.builder.Transferable;
import org.testcontainers.utility.DockerImageName;
import org.testcontainers.utility.MountableFile;

Network network = Network.newNetwork();

GenericContainer<?> nginx = new GenericContainer<>(DockerImageName.parse("nginx:1.29"))
        .withExposedPorts(80)                                   // container port; host port is random
        .withEnv("NGINX_ENTRYPOINT_QUIET_LOGS", "1")
        .withCopyFileToContainer(MountableFile.forClasspathResource("static/index.html"),
                "/usr/share/nginx/html/index.html")
        .withNetwork(network)
        .withNetworkAliases("web")                              // other containers on `network` reach it as web:80
        .withLogConsumer(new Slf4jLogConsumer(org.slf4j.LoggerFactory.getLogger("nginx")))
        .waitingFor(Wait.forHttp("/").forStatusCode(200));

nginx.start();
String url = "http://" + nginx.getHost() + ":" + nginx.getMappedPort(80) + "/";
var result = nginx.execInContainer("nginx", "-v");          // run a command inside, get exit code and output
nginx.stop();

import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;

@Testcontainers
class OrderRepositoryIT {

    @Container   // static: started once before all tests of the class, stopped after them
    static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:18.1");

    @Test
    void connects() throws Exception {
        try (var connection = java.sql.DriverManager.getConnection(
                postgres.getJdbcUrl(), postgres.getUsername(), postgres.getPassword())) {
            org.assertj.core.api.Assertions.assertThat(connection.isValid(2)).isTrue();
        }
    }
}

import java.io.File;
import org.testcontainers.containers.ComposeContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

ComposeContainer environment = new ComposeContainer(
        DockerImageName.parse("docker:29.8.1-cli"),                  // runs `docker compose` inside this image
        new File("../compose.yaml"))
    .withCopyFilesInContainer("wiremock")                           // copy only compose.yaml and ./wiremock
    .withExposedService("postgres", 5432, Wait.forHealthcheck())
    .withExposedService("kafka", 9092, Wait.forHealthcheck())
    .withStartupTimeout(java.time.Duration.ofMinutes(3));

environment.start();
String host = environment.getServiceHost("postgres", 5432);
int port = environment.getServicePort("postgres", 5432);

# ~/.testcontainers.properties -- on developer machines only
testcontainers.reuse.enable=true

static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:18.1").withReuse(true);
static { postgres.start(); }       // manual start; no @Container, which would stop it

# ~/.testcontainers.properties or TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX
hub.image.name.prefix=registry.example.com/dockerhub-mirror/