How to Run Integration Tests with Docker Compose in GitHub Actions

Docker Compose brings up your full stack (app, database, queue) so integration tests hit real dependencies.

Run docker compose up -d, wait for services to report healthy, run the tests against the running stack, and tear it down. Compose handles networking between services by name.

Steps

• Run docker compose up -d --wait so the step blocks until services are healthy.
• Run the integration test command against the running stack.
• Always run docker compose down -v to clean up, even on failure.

Workflow

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker compose up -d --wait
      - run: npm ci && npm run test:integration
      - name: Tear down
        if: always()
        run: docker compose down -v

Gotchas

• --wait needs healthcheck defined on each service, or it returns before they are ready.
• Use down -v to drop volumes so the next run starts from a clean state.

Related guides