Testcontainers logo

Testcontainers

Open Source

Library for running throwaway Docker containers in tests — real databases, browsers, and services on demand.

Visit websiteGitHub

Pricing

Free / Open source

Type

Automation

Languages

Java, JavaScript, TypeScript, Python, Go, C#, Ruby

// VERDICT

Reach for Testcontainers when you want integration tests against real dependencies (a real DB/queue) spun up and torn down per test, not mocks or shared environments. Skip it when Docker isn't available in CI, or unit tests with mocks are enough.

Best for

Spinning up real dependencies (databases, queues, browsers, services) as throwaway Docker containers from within your test code - giving integration tests real backends without shared environments.

Avoid when

You can't run Docker in your test/CI environment, pure unit tests with mocks suffice, or your dependencies aren't containerisable.

CI/CD fit

Library in your test code · needs Docker in CI · per-test real dependencies

Languages

Java · JavaScript · TypeScript · Python · Go · C# · Ruby

Team fit

Integration-test authors · Dev/QA wanting real backends · Teams avoiding shared test DBs

Setup

Easy

Maintenance

Low

Learning

Intermediate

Licence

Free / Open source

// BEST FOR

  • Real databases/queues/services as throwaway containers in tests
  • Reliable integration tests without shared environments
  • Per-test isolation and clean state
  • Avoiding mocks where a real dependency is better
  • Many language bindings (Java, JS, Python, Go, ...)
  • Reproducible integration tests in CI

// AVOID WHEN

  • You can't run Docker in your test/CI environment
  • Pure unit tests with mocks suffice
  • Your dependencies aren't containerisable
  • Container startup time is prohibitive per test
  • A persistent shared test environment is required
  • Minimal tooling is the goal

// QUICK START

# add the Testcontainers library for your language; in test setup:
// new PostgreSQLContainer(...).start()  -> run integration tests -> auto-stop
# (requires Docker available in CI)

// ALTERNATIVES TO CONSIDER

ToolChoose it when
DockerYou want to manage containers/compose yourself, not from test code.
DbUnitYou want database state setup/verification for JVM integration tests.
KubernetesYou need full multi-service orchestrated environments.

// FEATURES

  • Throwaway databases (Postgres, MySQL, Mongo, others) per test
  • Browser containers (Selenium, Playwright) for E2E setups
  • Custom Docker images via the GenericContainer API
  • Wait strategies for ports, log lines, and HTTP health
  • Compose support for multi-service test stacks

// PROS

  • Real services in tests — no mocks needed
  • Multi-language libraries with consistent API
  • Cleanly disposes of containers after tests run
  • Backed by Docker (via the AtomicJar acquisition) — strong long-term outlook

// CONS

  • Requires Docker on the test runner
  • Slower than mocks — startup adds seconds per test class
  • Resource use on CI agents can be heavy without tuning

// EXAMPLE QA WORKFLOW

  1. Add the Testcontainers library

  2. Declare needed containers in test setup

  3. Start real dependencies per test/suite

  4. Run integration tests against them

  5. Auto-stop/tear down after

  6. Ensure Docker is available in CI

// RELATED QA.CODES RESOURCES

Cheat sheets