Running Docker containers in CI for integration testing

Testing Against Real Dependencies in CI

Unit tests mock dependencies. Integration tests need real ones. GitHub Actions supports service containers — Docker containers that start alongside your job and are available via localhost or service name.

Using GitHub Actions Service Containers

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
        env:
          DATABASE_URL: postgresql://postgres:testpass@localhost:5432/testdb

The service container is health-checked before your test step runs — no race conditions. The database is destroyed after the job completes. This pattern gives you clean, isolated integration test environments on every CI run without any external infrastructure.