Testcontainers skill for Claude Code

# Testcontainers setup by language

Read the section for the stack in use. APIs checked against the official docs for
Testcontainers for Java 2.0.x, Node.js (`testcontainers` + `@testcontainers/*` modules),
Python 4.x and Go (`testcontainers-go`). Confirm against the installed version when an
option name does not compile.

## Java (JUnit 5)

Dependencies (2.x artifacts use the `testcontainers-` prefix; 1.x used `postgresql`,
`junit-jupiter`):

```kotlin
testImplementation("org.testcontainers:testcontainers-junit-jupiter:2.0.5")
testImplementation("org.testcontainers:testcontainers-postgresql:2.0.5")
testRuntimeOnly("org.postgresql:postgresql")   // the module does not bring the driver
```

Singleton shared by every test class (2.x: `org.testcontainers.postgresql.PostgreSQLContainer`,
non-generic; 1.x: `org.testcontainers.containers.PostgreSQLContainer<?>`):

```java
import org.testcontainers.postgresql.PostgreSQLContainer;

public abstract class IntegrationTest {
  static final PostgreSQLContainer POSTGRES =
      new PostgreSQLContainer("postgres:17-alpine")
          .withCommand("postgres", "-c", "fsync=off", "-c", "synchronous_commit=off");

  static {
    POSTGRES.start();                 // stopped by Ryuk when the JVM exits
  }

  @BeforeAll
  static void migrate() {
    Flyway.configure()
        .dataSource(POSTGRES.getJdbcUrl(), POSTGRES.getUsername(), POSTGRES.getPassword())
        .load().migrate();            // idempotent: a no-op after the first class
  }
}
```

Spring Boot (3.1+): `@ServiceConnection` replaces `@DynamicPropertySource` wiring:

```java
@SpringBootTest
@Testcontainers
class OrderApiTest {
  @Container @ServiceConnection
  static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");
}
```

For a suite-wide singleton in Spring, put the container in a `@TestConfiguration` as a
`@Bean @ServiceConnection` and import that configuration everywhere, so the context cache
and the container agree.

Static `@Container` field: one container per class. Instance `@Container` field: one per
test method (avoid). The extension is documented as sequential-only.

Reuse (local only): `~/.testcontainers.properties` with `testcontainers.reuse.enable=true`,
then `.withReuse(true)` and do not call `stop()`.

## Node.js / TypeScript

```bash
npm install -D testcontainers @testcontainers/postgresql
```

Vitest global setup, one container per run, URL passed to workers with `provide`/`inject`:

```ts
// test/global-setup.ts
import type { TestProject } from "vitest/node";
import { PostgreSqlContainer, type StartedPostgreSqlContainer } from "@testcontainers/postgresql";
import { execSync } from "node:child_process";

let pg: StartedPostgreSqlContainer;

export async function setup(project: TestProject) {
  pg = await new PostgreSqlContainer("postgres:17-alpine")
    .withCommand(["postgres", "-c", "fsync=off", "-c", "synchronous_commit=off"])
    .start();
  const url = pg.getConnectionUri();
  execSync("npx prisma migrate deploy", { env: { ...process.env, DATABASE_URL: url }, stdio: "inherit" });
  project.provide("databaseUrl", url);
}

export async function teardown() {
  await pg?.stop();
}

declare module "vitest" {
  export interface ProvidedContext { databaseUrl: string }
}
```

```ts
// vitest.config.ts
export default defineConfig({ test: { globalSetup: ["./test/global-setup.ts"] } });
// in tests:  import { inject } from "vitest";  const url = inject("databaseUrl");
```

Per-worker database from a template: after migrating, rename the migrated database to
`app_template` (or migrate into a database created for that purpose), then in a
`setupFiles` hook run `CREATE DATABASE test_${process.env.VITEST_POOL_ID} TEMPLATE app_template`.

Module snapshot/restore (single process only, because the container object lives in the
process that started it):

```ts
await pg.snapshot();          // after migrations; close client connections first
await pg.restoreSnapshot();   // before each test
```

Generic container with wait strategy:

```ts
import { GenericContainer, Wait } from "testcontainers";

const redis = await new GenericContainer("redis:7-alpine")
  .withExposedPorts(6379)
  .withWaitStrategy(Wait.forLogMessage("Ready to accept connections"))
  .withStartupTimeout(120_000)
  .start();
const url = `redis://${redis.getHost()}:${redis.getMappedPort(6379)}`;
```

Other waits: `Wait.forHttp("/health", 8080)`, `Wait.forHealthCheck()`,
`Wait.forListeningPorts()`, `Wait.forLogMessage(text, times)`.

Reuse: `.withReuse()` plus `TESTCONTAINERS_REUSE_ENABLE=true` in the developer's shell.
Jest: same pattern in `globalSetup`, but pass the URL through `process.env` (Jest has no
`provide`), and stop the container in `globalTeardown` via a module-level handle or
`globalThis`.

## Python (pytest)

```bash
pip install "testcontainers[postgres]" pytest
```

```python
# conftest.py
import pytest, sqlalchemy
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def pg_url():
    with PostgresContainer("postgres:17-alpine", driver="psycopg") as pg:   # driver=None for a plain URL
        url = pg.get_connection_url()
        run_alembic_upgrade(url)          # alembic command.upgrade(cfg, "head")
        yield url

@pytest.fixture
def db(pg_url):
    engine = sqlalchemy.create_engine(pg_url)
    with engine.connect() as conn:
        trans = conn.begin()
        yield conn                         # transaction-per-test isolation
        trans.rollback()
```

pytest-xdist: each worker process runs its own session fixtures, so this starts one
container per worker. To share one container, start it in the controller (for example in
`pytest_configure` guarded by `not hasattr(config, "workerinput")`) and pass the URL to
workers, then create `test_{PYTEST_XDIST_WORKER}` databases from a template.

Module containers include their own readiness check. For generic `DockerContainer`
images, use the wait strategy API of the installed 4.x release (newer releases move
modules from the older `wait_for_logs` helper to wait strategy objects).

## Go

```bash
go get github.com/testcontainers/testcontainers-go/modules/postgres
```

```go
var connStr string

func TestMain(m *testing.M) {
    ctx := context.Background()
    ctr, err := postgres.Run(ctx, "postgres:17-alpine",
        postgres.WithDatabase("app"),
        postgres.WithUsername("app"),
        postgres.WithPassword("app"),
        postgres.BasicWaitStrategies(),
        postgres.WithSQLDriver("pgx"),   // driver used by Snapshot/Restore; match the one you import
    )
    if err != nil { log.Fatal(err) }
    connStr, err = ctr.ConnectionString(ctx, "sslmode=disable")
    if err != nil { log.Fatal(err) }
    if err := migrate(connStr); err != nil { log.Fatal(err) }
    if err := ctr.Snapshot(ctx); err != nil { log.Fatal(err) }
    shared = ctr

    code := m.Run()
    _ = testcontainers.TerminateContainer(ctr)
    os.Exit(code)
}

func resetDB(t *testing.T) {
    t.Cleanup(func() {
        if err := shared.Restore(context.Background()); err != nil { t.Fatal(err) }
    })
}
```

Inside a single test that owns a container, prefer `testcontainers.CleanupContainer(t, ctr)`
right after creation so cleanup runs even if later setup fails.

Generic container: `testcontainers.Run(ctx, "redis:7-alpine",
testcontainers.WithExposedPorts("6379/tcp"), testcontainers.WithWaitStrategy(wait.ForLog("Ready to accept connections")))`.
Reuse locally with `testcontainers.WithReuseByName("app-pg")`.

`Snapshot`/`Restore` serialize tests; for `t.Parallel()`, create one database per test
from a template instead.