docker-compose-test

Overview

Docker Compose is "a tool for defining and running multi-container applications" - services, networks, and volumes declared "in a single YAML configuration file" and managed "with a single command" (compose-overview).

For tests, Compose is the right choice when:

• The SUT needs two or more real backing services that have to see each other (app → db → cache → queue) - the topology is the artifact.
• The same definition must run locally and in CI without imperative drift.
• A team wants per-job isolation in CI without booking dedicated ports / databases.

When the test process only needs one dependency wired into a single test, testcontainers is the lighter option - it lives inside the test process and doesn't need a separate docker compose up step.

When to use

• The SUT has 2+ runtime dependencies and the team already runs them via Docker locally.
• A CI pipeline needs to spin up the same topology per-job, not share one test database across PRs.
• An end-to-end test suite (Playwright, Cypress, native E2E) needs a full stack reachable on a network.

Step 1 - Author compose.test.yaml

Compose's default file lookup is compose.yaml or docker-compose.yaml in the working directory or any parent (compose-cli); using the explicit compose.test.yaml filename + -f flag keeps test topology separate from local-dev topology.

# compose.test.yaml
name: orders-tests

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: test
      POSTGRES_DB: orders_test
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d orders_test"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 5s

  cache:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 2s
      timeout: 3s
      retries: 30

  app:
    build:
      context: .
      target: test
    environment:
      DATABASE_URL: postgres://postgres:test@db:5432/orders_test
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 10s

  e2e:
    image: mcr.microsoft.com/playwright:v1.50.0-noble
    working_dir: /work
    volumes:
      - .:/work
    environment:
      BASE_URL: http://app:3000
    depends_on:
      app:
        condition: service_healthy
    command: npx playwright test

The name: top-level key sets the project name (which Compose normally derives from the working directory) - important for CI isolation, see Step 4.

Step 2 - Healthchecks are load-bearing

Per compose-services, depends_on accepts three conditions:

service_started is almost never what a test wants. Postgres "started" doesn't mean "accepting connections". Always pair a real dependency with a healthcheck and a service_healthy gate.

The healthcheck syntax per compose-services:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

For tests, use shorter intervals (2s vs the 1m30s default) and more retries so the gate trips quickly when the service is up but waits long enough for cold starts.

Step 3 - Migrations as one-shot dependencies

Database migrations belong in their own service that the app depends_on with service_completed_successfully:

services:
  db:
    image: postgres:15
    healthcheck: { test: ["CMD-SHELL", "pg_isready"], interval: 2s, retries: 30 }

  migrate:
    image: orders-app:test
    command: npm run db:migrate
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://postgres:test@db:5432/orders_test

  app:
    image: orders-app:test
    depends_on:
      db: { condition: service_healthy }
      migrate: { condition: service_completed_successfully }
    environment:
      DATABASE_URL: postgres://postgres:test@db:5432/orders_test

The chain - db healthy → migrate runs → migrate exits 0 → app starts - ensures the app never connects to an unmigrated database.

Step 4 - Per-job isolation in CI

Per compose-cli, the project name controls the namespace of every resource Compose creates (containers, networks, volumes). Two parallel jobs that use the same project name fight each other.

Set the project name from a unique-per-job value:

# .github/workflows/integration.yml
jobs:
  e2e:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    env:
      COMPOSE_PROJECT_NAME: orders-${{ github.run_id }}-${{ matrix.shard }}
    steps:
      - uses: actions/checkout@v5
      - name: Compose up
        run: docker compose -f compose.test.yaml up --build --wait --wait-timeout 180
      - name: Run tests
        run: docker compose -f compose.test.yaml run --rm e2e
      - name: Compose down
        if: always()
        run: docker compose -f compose.test.yaml down --volumes --remove-orphans

Per compose-cli, -p / --project-name resolution order is: flag > COMPOSE_PROJECT_NAME env var > top-level name: > directory basename. Using the env var keeps the YAML clean while overriding the in-file name: per CI job.

"Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit." (compose-cli)

Step 5 - Gate the test step on readiness

Per [compose-up][up], two flags pair for "block until everything is healthy":

Two valid CI shapes:

Shape A - up --wait then run the test service

docker compose -f compose.test.yaml up --build --wait --wait-timeout 180
docker compose -f compose.test.yaml run --rm e2e
EXIT=$?
docker compose -f compose.test.yaml down --volumes --remove-orphans
exit $EXIT

The up --wait step blocks until every service is healthy or the 180s budget elapses. The run step executes the test container; its exit code is the build verdict.

Shape B - up --abort-on-container-exit --exit-code-from <test-service>

docker compose -f compose.test.yaml up \
  --build \
  --abort-on-container-exit \
  --exit-code-from e2e

Compose returns the test container's exit code as its own. Cleaner when the test runs as a Compose service rather than via run.

Step 6 - Tear down deterministically

Per compose-cli, down "Stop[s] and remove[s] containers, networks". For tests, two flags matter:

docker compose -f compose.test.yaml down --volumes --remove-orphans

Always run down in an if: always() step (GitHub Actions) or trap-on-EXIT (shell) - leaked containers consume CI runner disk and poison the next run.

Step 7 - Profiles for selective enablement

When the test compose file has services that aren't always needed (seeded fixtures, a debugging admin UI, a heavyweight observability stack), gate them behind a profile per compose-cli:

services:
  db: { image: postgres:15, healthcheck: { ... } }

  pgadmin:
    image: dpage/pgadmin4
    profiles: [debug]
    ports: ["5050:80"]
    depends_on: { db: { condition: service_healthy } }

Run with the profile when needed:

docker compose -f compose.test.yaml --profile debug up
# or via env:
COMPOSE_PROFILES=debug docker compose -f compose.test.yaml up

Per compose-cli: "Specify a profile to enable" - multiple profiles via repeating --profile or comma-separated COMPOSE_PROFILES.

Anti-patterns

Limitations

• Compose is not a scheduler. It runs on one Docker daemon. For multi-host or k8s-shaped tests, use the orchestrator's native test primitive (kind, k3d, helm test) instead.
• No native parallelism within one project. Compose runs services in topological order; "parallel" tests come from running multiple Compose projects per CI matrix shard.
• Healthcheck images need the probe binary. Minimal/distroless images often don't ship curl / pg_isready - either switch to a slim variant or use a TCP probe via nc / wget.
• Per-test reset is coarse. The Compose stack is per-suite; for per-test DB reset, layer db-snapshot-restore on top.

References

• compose-overview - overview, "tool for defining and running multi-container applications".
• compose-cli - docker compose subcommand list, -f, --project-name, --profile, project-name resolution rules.
• [compose-up][up] - up flags: --wait, --wait-timeout, --abort-on-container-exit, --exit-code-from, --build.
• compose-svc - services schema: healthcheck, depends_on conditions (service_started / service_healthy / service_completed_successfully).
• testcontainers - alternative when the topology is one container per test, expressed in test code.
• db-snapshot-restore - per-test isolation layered on top of a Compose-managed database.