How to Run Integration Tests With Docker Compose in CI

Docker Compose brings up the app plus its dependencies, so integration tests run against a realistic stack.

Run docker compose up -d, wait for services to become healthy, run the test command, and always tear the stack down. Capturing docker compose logs on failure makes debugging far easier.

Steps

• Start the stack detached with docker compose up -d.
• Wait on health checks, then run the test suite.
• Dump logs on failure and run docker compose down -v to clean up.

Workflow

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker compose up -d --wait
      - run: docker compose run --rm tests
      - if: failure()
        run: docker compose logs
      - if: always()
        run: docker compose down -v

Gotchas

• --wait blocks until services with health checks report healthy; without health checks it returns immediately.
• Use if: always() for teardown so a failed test still releases volumes and containers.

Related guides