9.3.5.3 Testing Compose Profiles

A focused guide to Testing Compose Profiles, connecting core concepts with practical Docker and container operations.

Testing Compose profiles group together services specifically needed for running an application's automated test suite — test runners, test-specific data seeding, isolated test databases — tagged with a profile so they're activated specifically in a testing context without affecting ordinary development or production usage.

Tagging Test-Specific Services

A testing-oriented profile groups together everything specifically needed to run the test suite.

services:
  api:
    build: .
  test-runner:
    build: .
    command: npm test
    profiles:
      - testing
    depends_on:
      - test-db
  test-db:
    image: postgres:16
    profiles:
      - testing
    environment:
      - POSTGRES_DB=test_db

Both test-runner and test-db only start when the testing profile is explicitly activated, keeping them out of an ordinary development or production startup.

Running Tests Through This Profile

A CI pipeline (or a developer running tests locally) explicitly activates this profile to bring up everything the test suite needs.

docker compose --profile testing up --abort-on-container-exit test-runner

The --abort-on-container-exit flag stops the whole Compose application once test-runner exits, appropriate for a CI context where the test run's completion should end the entire process.

Why an Isolated Test Database Matters

Using a separate, test-specific database service (rather than reusing the application's normal development database) avoids tests inadvertently affecting data outside the dedicated test context.

services:
  test-db:
    image: postgres:16
    profiles:
      - testing

Cleaning Up After a Test Run

Tearing down the testing-specific services and their data after a test run keeps the environment clean for the next run.

docker compose --profile testing down -v

Why Testing Compose Profiles Matter

Cleanly separating test-specific infrastructure through a dedicated profile keeps automated testing well-isolated and repeatable, without cluttering ordinary development or production usage with services that exist purely to support the test suite.