# Testcontainers — Throwaway Docker Dependencies for Integration Tests

> Language libraries that spin up real Postgres, Kafka, Redis, Selenium, and any Docker image for integration tests — then throw them away.

## Install

Save in your project root:

# Testcontainers — Throwaway Docker Dependencies for Integration Tests

## Quick Use
```java
// Java (JUnit 5)
@Testcontainers
class OrderRepoTest {
    @Container
    static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16-alpine");

    @Test void inserts() {
        var ds = DataSourceBuilder.create().url(pg.getJdbcUrl())
                  .username(pg.getUsername()).password(pg.getPassword()).build();
        // ... real SQL, real Postgres, fresh container per test class
    }
}
```
```go
// Go
redis, _ := testcontainers.GenericContainer(ctx, testcontainers.ContainerRequest{
    Image: "redis:7", ExposedPorts: []string{"6379/tcp"}, WaitingFor: wait.ForListeningPort("6379/tcp"),
})
defer redis.Terminate(ctx)
```

## Introduction
Testcontainers is a family of libraries (Java, Go, Python, .NET, Node, Rust) that drive Docker from inside test suites so you can point code at a real database or broker instead of a mock. It has become the industry standard for integration testing because "it's the real thing, it's disposable, and it's fast enough".

## What Testcontainers Does
- Starts any Docker image on demand and waits for it to become ready
- Exposes container ports on random host ports, returning dynamic JDBC URLs etc.
- Ships hardened modules for Postgres, MySQL, Kafka, RabbitMQ, Selenium, Localstack, Neo4j
- Cleans up containers automatically at test end via the Ryuk reaper
- Supports Docker, Podman, Colima, Rancher Desktop, and Testcontainers Cloud

## Architecture Overview
Each language binding is a thin client over the Docker Engine API. When a test requests a container, the library pulls the image, starts it with a unique label, and polls a wait-strategy (log line, TCP port, HTTP 200) before returning. A sidecar container called Ryuk watches for the test JVM/process to exit and removes labeled containers — guaranteeing cleanup even on crashes. Testcontainers Cloud optionally offloads container runtime to a remote daemon for CI speed.

## Self-Hosting & Configuration
- Requires a local Docker / Podman / Colima daemon reachable via `DOCKER_HOST`
- Configure at `~/.testcontainers.properties` (image substitutions, TC Cloud token)
- Images can be pulled from private registries; set `docker.auth.config`
- Use `@Container` lifecycle or `SharedContainer` patterns to reuse across tests
- In CI: remote Docker via `TESTCONTAINERS_HOST_OVERRIDE` or TC Cloud

## Key Features
- Real dependencies, not mocks — no drift between test and prod behavior
- Automatic port mapping and URL generation
- Ryuk guarantees cleanup even on panics/crashes
- Rich module catalogue (100+ official + community)
- Works identically in every major language stack

## Comparison with Similar Tools
- **Docker Compose** — manual up/down; not ephemeral per test
- **Embedded DBs (H2, SQLite)** — fast but different SQL dialect, drift risk
- **In-memory mocks (WireMock)** — great for HTTP APIs, not databases
- **LocalStack** — AWS-specific; Testcontainers has a `LocalStackContainer` module
- **Dev containers** — for workstation setup, not per-test teardown

## FAQ
**Q:** Does it work in GitHub Actions?
A: Yes. Docker is preinstalled on Linux runners; Mac/Windows runners need Colima or TC Cloud.

**Q:** Is it slow?
A: First run pulls images; subsequent runs reuse them. With reusable containers (`withReuse(true)`), startup is ~200 ms.

**Q:** Can I use my own image?
A: Yes. `new GenericContainer("my-registry/my-image:tag")` or an `ImageFromDockerfile` builder.

**Q:** What cleans containers after a crash?
A: Ryuk — a container that watches for the parent process label and terminates orphans.

## Sources
- https://github.com/testcontainers/testcontainers-java
- https://testcontainers.com

---
Source: https://tokrepo.com/en/workflows/12b8fc17-38f0-11f1-9bc6-00163e2b0d79
Author: AI Open Source