Skip to content
Skills Library
DevOps & cloud · Testing

testcontainers

/testcontainers

When the user wants to use Docker-backed real infrastructure (Postgres, Kafka, Redis, Mongo, S3, etc.) inside tests via the Testcontainers libraries. Use when the user mentions "Testcontainers," "@Testcontainers," "@Container," "PostgreSQLContainer," "GenericContainer," "Testcontainers Cloud," "Testcontainers Desktop," "Ryuk," "testcontainers-go," "testcontainers-python," or "Testcontainers for Node.js." For broader CI infra see ci-test-orchestration. For environment strategy see test-environment-management.

Licence
MIT
Last repository change
24.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

When the user wants to use Docker-backed real infrastructure (Postgres, Kafka, Redis, Mongo, S3, etc.) inside tests via the Testcontainers libraries. Use when the user mentions "Testcontainers," "@Testcontainers," "@Container," "PostgreSQLContainer," "GenericContainer," "Testcontainers Cloud," "Testcontainers Desktop," "Ryuk," "testcontainers-go," "testcontainers-python," or "Testcontainers for Node.js." For broader CI infra see ci-test-orchestration. For environment strategy see test-environment-management.

Triggers from the description

Testcontainers,@Testcontainers,@Container,PostgreSQLContainer,GenericContainer,Testcontainers Cloud,Testcontainers Desktop,Ryuk,
Original author description

When the user wants to use Docker-backed real infrastructure (Postgres, Kafka, Redis, Mongo, S3, etc.) inside tests via the Testcontainers libraries. Use when the user mentions "Testcontainers," "@Testcontainers," "@Container," "PostgreSQLContainer," "GenericContainer," "Testcontainers Cloud," "Testcontainers Desktop," "Ryuk," "testcontainers-go," "testcontainers-python," or "Testcontainers for Node.js." For broader CI infra see ci-test-orchestration. For environment strategy see test-environment-management.

How it works

  1. Initial Assessment
  2. Why Testcontainers
  3. A minimal example (JVM)
  4. Common modules
  5. Per-language patterns
  6. Performance considerations
  7. Ryuk (the cleanup daemon)
  8. CI patterns
  9. Wait strategies
  10. Network and exposed ports
Original SKILL.md headings · 316 lines, 1,512 words
SKILL.md preview
---
name: testcontainers
description: When the user wants to use Docker-backed real infrastructure (Postgres, Kafka, Redis, Mongo, S3, etc.) inside tests via the Testcontainers libraries. Use when the user mentions "Testcontainers," "@Testcontainers," "@Container," "PostgreSQLContainer," "GenericContainer," "Testcontainers Cloud," "Testcontainers Desktop," "Ryuk," "testcontainers-go," "testcontainers-python," or "Testcontainers for Node.js." For broader CI infra see ci-test-orchestration. For environment strategy see test-environment-management.
metadata:
  version: 1.0.0
---

# Testcontainers

You are an expert in Testcontainers — the family of libraries (originally Java, now JVM / .NET / Go / Python / Node / Rust) that lets tests spin up real Docker-backed infrastructure (databases, message queues, cache, etc.) per test class or per test method. Your goal is to help engineers replace fragile mocks / in-memory shims with real dependencies in tests while keeping the suite fast and reliable. Don't fabricate library APIs, container module names, or feature flags. When uncertain, point the reader to `testcontainers.com/` or the language-specific docs.

## Initial Assessment

Check `.agents/qa-context.md` (fallback: `.claude/qa-context.md`) before answering. Pay attention to:

- **Languages** — Testcontainers libraries exist for JVM, .NET, Go, Python, Node, Rust, Ruby. Quality and feature parity vary.
- **What needs to be real** — Postgres / MySQL / Mongo / Redis / Kafka / RabbitMQ / Elasticsearch / Localstack / S3 / etc. Pre-built modules exist for popular dependencies.
- **CI environment** — Docker-in-Docker / rootless / Podman / Testcontainers Cloud. The runtime matters.
- **Test scope** — integration tests (good fit), unit tests (overkill), full-system tests (Testcontainers can do it but it's a lot).
- **Existing mocks** — Testcontainers often replaces in-memory fakes that have drifted from production behavior.

If the file does not exist, ask: language, dependencies under test, CI environment, existing mock strategy.

---

## Why Testcontainers

- **Real dependency behavior** — actual Postgres query planner, actual Kafka rebalance, actual Redis eviction. Catches what in-memory fakes miss.
- **Per-test isolation** — each test class gets a fresh container; state doesn't leak.
- **Cross-language** — same conceptual model in Java, Go, Python, Node, etc.
- **Pre-built modules** — common dependencies (Postgres, Kafka, Localstack, Vault, …) have ready-made container classes.
- **Auto-cleanup via Ryuk** — orphaned containers get reaped, so test failures don't leave stale containers.

When *not* to use Testcontainers:

- Pure unit tests with no I/O — overkill.
- Production-style data volume — Testcontainers spins fresh; not for big-data perf testing.
- Slow CI runner without Docker — won't run.

---

## A minimal example (JVM)

```java
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
class OrderRepositoryIT {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16.4")
        .withDatabaseName("orders_test")
        .withUsername("qa")
        .withPassword("Pa$$w0rd-fake");

    @Test
    void inserts_and_reads() {
        String url = postgres.getJdbcUrl();
        // ... use url in a DataSource or Spring's @DynamicPropertySource
    }
}
```

The container starts before the class's tests, stops after. Spring Boot integrates via `@DynamicPropertySource` to inject the JDBC URL.

---

## Common modules

| Module | Class (JVM example) | Use |
|--------|---------------------|-----|
| Postgres | `PostgreSQLContainer` | RDBMS testing |
| MySQL | `MySQLContainer` | RDBMS testing |
| MongoDB | `MongoDBContainer` | Document store |
| Redis | `GenericContainer("redis:7")` | Cache / queue |
| Kafka | `KafkaContainer` / `KafkaContainer.Confluent` | Event streaming |
| RabbitMQ | `RabbitMQContainer` | Messaging |
| Elasticsearch | `ElasticsearchContainer` | Search |
| Localstack | `LocalStackContainer` | AWS services emulator (S3, SQS, SNS, DDB) |
| MinIO | `GenericContainer` with MinIO image | S3-compatible storage |
| Vault | `VaultContainer` | Secrets |

Verify exact class names against the language-specific Testcontainers docs.

---

## Per-language patterns

### Java (JUnit 5)

```java
@Testcontainers
class ServiceIT {
    @Container
    static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:16.4");

    @DynamicPropertySource
    static void registerProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", db::getJdbcUrl);
        registry.add("spring.datasource.username", db::getUsername);
        registry.add("spring.datasource.password", db::getPassword);
    }
}
```

`@Container static` = one container per class (shared across tests). `@Container` (non-static) = one container per test method (slower, fully isolated).

### Python (pytest)

```python
import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def postgres():
    with PostgresContainer("postgres:16.4") as pg:
        yield pg

def test_query(postgres):
    conn = psycopg.connect(postgres.get_connection_url())
    # ...
```

### Node / TS

```ts
import { PostgreSqlContainer } from '@testcontainers/postgresql';

let container: StartedPostgreSqlContainer;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:16.4').start();
});

afterAll(async () => {
  await container.stop();
});

test('query', async () => {
  const url = container.getConnectionUri();
  // ...
});
```

### Go

```go
import (
    "testing"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
)

func TestThing(t *testing.T) {
    ctx := context.Background()
    pg, err := postgres.Run(ctx, "postgres:16.4",
        postgres.WithDatabase("orders_test"),
        postgres.WithUsername("qa"),
        postgres.WithPassword("Pa$$w0rd-fake"),
    )
    if err != nil { t.Fatal(err) }
    t.Cleanup(func() { pg.Terminate(ctx) })
    // ...
}
```

---

## Performance considerations

Fresh containers add 1-10 seconds per startup. Strategies:

- **`@Container static`** (or `scope='session'` in pytest) — one container, many tests. Reset state via transactions or truncate-per-test (cross-reference test-data-management).
- **Reusable containers** (`.withReuse(true)`) — Testcontainers leaves the container running between test runs locally; the next run reuses it. **Local development only**, not CI.
- **Image pre-pulling** — pull images in a CI cache step, not in the test.
- **Light images** — `postgres:16.4-alpine` is smaller than `postgres:16.4`.
- **Parallel test isolation via DB-per-worker** — start one Postgres container shared across all tests, use `CREATE DATABASE test_<worker>` for per-worker isolation.

A 1000-test suite spinning a fresh Postgres per class is fine; per test is usually too slow.

---

## Ryuk (the cleanup daemon)

Testcontainers starts a small Ryuk container alongside your tests; it watches for parent process exit and reaps orphaned containers. This is why crashed tests don't leave stale containers.

Disabling Ryuk (`TESTCONTAINERS_RYUK_DISABLED=true`) is sometimes necessary in restricted CI environments (no privileged containers) — but then cleanup is your job.

---

## CI patterns

### Docker available

Most CI providers (GitHub Actions Linux runners, GitLab CI, CircleCI, Buildkite agents) have Docker installed and work with Testcontainers out of the box.

### Docker-in-Docker (DinD)

For runners that run jobs inside containers (some K8s-based CI), DinD is required. Set `DOCKER_HOST` so Testcontainers finds the daemon.

### Testcontainers Cloud

A managed Docker host for tests. Useful when:

- Local Docker Desktop is licensed (cost / restrictions).
- CI runners can't run Docker (sandboxed, security policy).
- You want to share container pre-pulls across the org.

Test code is unchanged; environment vars point to Testcontainers Cloud.

### Podman / rootless

Testcontainers supports Podman; some configuration required. Verify against current docs for your language binding.

---

## Wait strategies

Testcontainers starts a container, then waits for it to be "ready" before tests run. The default wait strategy depends on the module; you can override:

```java
new GenericContainer("kafka:7.5.0")
    .waitingFor(Wait.forLogMessage(".*started.*", 1))
    .withStartupTimeout(Duration.ofMinutes(2));
```

Common strategies:

- `Wait.forListeningPort()` — port open.
- `Wait.forLogMessage(regex, occurrences)` — log indicates ready.
- `Wait.forHttp(path).forStatusCode(200)` — HTTP endpoint healthy.
- `Wait.forHealthcheck()` — Docker healthcheck passes.

Wrong wait strategy → tests start before the container is actually ready → flake.

---

## Network and exposed ports

Testcontainers binds container ports to random host ports. Access via:

```java
String url = "jdbc:postgresql://" + container.getHost() + ":" + container.getMappedPort(5432) + "/db";
```

The container's `localhost` is NOT the host's localhost — your app under test running on the host can't talk to the container via `localhost:5432`. Always use `getHost()` + `getMappedPort()` (or the module's `getJdbcUrl()` / `getConnectionUrl()` helpers).

For container-to-container in tests (e.g., app container talks to Postgres container), use Testcontainers' network feature:

```java
Network network = Network.newNetwork();
PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16.4")
    .withNetwork(network)
    .withNetworkAliases("postgres");

GenericContainer<?> app = new GenericContainer<>("myapp:latest")
    .withNetwork(network)
    .withEnv("DATABASE_URL", "postgresql://qa:Pa$$w0rd-fake@postgres:5432/db");
```

---

## Custom images

`GenericContainer` works with any Docker image. For your own services:

```java
GenericContainer<?> app = new GenericContainer<>(DockerImageName.parse("myorg/myapp:abc123"))
    .withExposedPorts(8080)
    .withEnv("CONFIG", "...")
    .waitingFor(Wait.forHttp("/health"));
```

For images built per-test-run, use `ImageFromDockerfile`:

```java
GenericContainer<?> app = new GenericContainer<>(new ImageFromDockerfile()
    .withFileFromPath(".", Path.of("./src/main/docker")));
```

---

## Common Pitfalls

- **`:latest` image tags** — silent version drift. Always pin.
- **Per-test container when per-class would do** — multiplies test time.
- **Forgetting wait strategy** — race between container start and test connection.
- **Sharing a container across parallel test runs without partitioning** — collisions.
- **Using `localhost` in connection strings** — won't work for container-to-container; use `getHost()`.
- **Not enabling Ryuk in CI** — orphaned containers pile up.
- **Trying to test things Testcontainers doesn't suit** — production-scale data, multi-day soak.
- **Resource exhaustion in CI** — 10 containers per test × 100 tests in parallel = your CI box is dead. Bound concurrency.
- **Mixing in-memory fakes and real containers** — pick one; mixing creates surprising bug surface.
- **Trusting startup logs as ready-state** — use proper wait strategies, not arbitrary sleeps.

---

## Task-Specific Questions

When helping with Testcontainers, ask:

1. Language and Testcontainers library version?
2. Which dependencies need to be real (Postgres / Kafka / Redis / S3 / custom service)?
3. Test scope — class-scoped, method-scoped, session-scoped?
4. CI runtime — Docker / DinD / Podman / Testcontainers Cloud?
5. Existing fake / mock approach being replaced?
6. Performance budget for the test suite?
7. Image registry — public Docker Hub, internal mirror?

---

## Related Skills

- **test-data-management** — Testcontainers + transactional rollback is the canonical fast-and-clean integration test setup.
- **test-environment-management** — Testcontainers sits at the local + CI layer of the environment ladder.
- **ci-test-orchestration** — for parallelism + container resource management.
- **All language unit-test skills** (**jest-vitest** / **pytest** / **junit-testng** / **xunit-nunit** / **go-test** / **rspec**) — for the runners that drive Testcontainers.
- **supertest** / **pytest-api** / **rest-assured** — Testcontainers + these is the canonical full integration test setup.
- **flaky-test-management** — wait strategies are a common flake source.
- **wiremock** — for mocking external HTTP services Testcontainers can't easily virtualize.
Files in this package (2)
  • SKILL.md 12 KB
  • evals/evals.json 7 KB

Versions

RepositoryScoreLicence
This page · aks-builds/quality-skills100MIT
TerminalSkills/skills100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
testland/qa100MIT
Tyler-R-Kendrick/agent-skills100MIT

Database snapshot: 13.11.2026 · package version 4dd74bab56db (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100testcontainers-integration-testing-configuration
    Guides configuring Testcontainers to spin up real dependency containers (Postgres, Kafka, Redis, and similar) for integration tests instead of mocks or hand-maintained shared test environments — container lifecycle management (per-test vs. shared/singleton containers), wait…
  • 100testcontainers-integration-testing
    Use this skill when spinning up real, ephemeral Docker database, Kafka, and Redis instances during automated integration testing.
  • 90cmk:testcontainers
    Use when the user asks to "use testcontainers for tests", "start a database container in tests", "testcontainers-rs", "container startup is flaky in CI", or needs to start and share a throwaway service container (Postgres, Redis, MinIO, or similar) from Rust test code via the `testcontainers` crate.
  • 100testcontainers-python
    testcontainers-python specialist. Covers all container modules (PostgreSQL, MySQL, MongoDB, Redis, Kafka, RabbitMQ, MinIO, Elasticsearch, LocalStack), GenericContainer, wait strategies, Docker Compose, networks, pytest fixtures, and CI/CD integration. USE WHEN: user mentions…
  • 100messaging-testing-kafka
    Kafka integration testing with @EmbeddedKafka, Testcontainers, and Mock APIs. Covers Java/Spring, Node.js, and Python testing approaches. USE WHEN: user mentions "kafka test", "embedded kafka", "@EmbeddedKafka", "KafkaContainer", "MockConsumer", "MockProducer", "kafka…
  • 100integration-test-setup
    Set up integration tests for an ASP.NET Core app using WebApplicationFactory and Testcontainers. Use this skill whenever the user wants integration tests, end-to-end API tests, tests that hit a real database, WebApplicationFactory setup, Testcontainers, test fixtures with a real…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.