Docker for Testing: Containers for Reliable QA Runs

A payment API passed every laptop run but failed in CI because one developer had PostgreSQL 16, the runner still used PostgreSQL 14, and both reused databases with different migration histories. Nobody could reproduce the same state twice. Docker helps only when the team treats images, data, networking, and readiness as test inputs. Wrapping an unreliable setup in containers merely makes the uncertainty portable.

Define the environment contract before the Dockerfile

Start with the system boundary. A service-level test might need the application, PostgreSQL, and a fake payment provider. It probably does not need the production proxy, monitoring stack, or every neighboring service. Each extra container adds startup time and another failure mode.

Write down the contract that makes a run reproducible:

• exact image versions or immutable digests
• required environment variables and safe defaults
• exposed service ports and internal DNS names
• database schema and seed ownership
• a readiness condition for every dependency
• artifact locations and cleanup behavior

Containers isolate processes and filesystems, not all sources of variation. CPU architecture, available memory, Docker Engine behavior, external APIs, and floating image tags can still change results. Record those assumptions in the repository beside the tests.

Build a test image with deliberate layers

A test image should contain the runtime and dependencies needed to execute checks, but it should not contain secrets or stale reports. Copy dependency manifests before application code so Docker can reuse the expensive installation layer.

FROM node:22-bookworm-slim AS dependencies
WORKDIR /workspace
COPY package.json package-lock.json ./
RUN npm ci

FROM dependencies AS test
COPY . .
ENV CI=true
CMD ["npm", "test"]

Add a .dockerignore so local build output does not invalidate the cache or leak into the image:

node_modules
test-results
playwright-report
.git
.env*

Pin the major runtime intentionally and let an update process move it. latest makes a previously green commit dependent on when it is rebuilt. For stricter supply-chain control, pin a digest and use an automated dependency update to propose changes.

Keep production and test targets related but purposeful. The test target may include compilers, test runners, and coverage tools that should not ship. The production target should copy only the built application and runtime dependencies. Build both in CI. This catches a common gap where tests pass in a rich image but the minimal release image lacks a required file, certificate, or native library.

Run the image exactly as CI will run it:

docker build --target test -t checkout-tests:local .
docker run --rm checkout-tests:local

If tests need the source mounted for fast local iteration, keep that as a developer override. The CI proof should use the files copied into the image, which verifies that the build context is complete.

Compose an isolated integration stack

Docker Compose is useful when a test crosses process boundaries. The following stack gives the test runner an internal hostname, a private database, a health check, and an explicit exit code.

services:
  db:
    image: postgres:16.4-alpine
    environment:
      POSTGRES_DB: checkout_test
      POSTGRES_USER: tester
      POSTGRES_PASSWORD: tester
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U tester -d checkout_test"]
      interval: 2s
      timeout: 3s
      retries: 20
    tmpfs:
      - /var/lib/postgresql/data

  api:
    build:
      context: .
      target: test
    command: ["npm", "run", "start:test"]
    environment:
      DATABASE_URL: postgresql://tester:tester@db:5432/checkout_test
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "node", "scripts/healthcheck.mjs"]
      interval: 2s
      timeout: 3s
      retries: 30

  tests:
    build:
      context: .
      target: test
    command: ["npm", "run", "test:integration"]
    environment:
      BASE_URL: http://api:3000
    depends_on:
      api:
        condition: service_healthy

Inside the Compose network, tests call http://api:3000, not localhost. localhost refers to the test container itself. A temporary filesystem makes database state disposable and avoids accidental dependence on yesterday's volume.

Use a unique project name per concurrent run:

docker compose -p "checkout-${CI_PIPELINE_ID:-local}" up \
  --build --abort-on-container-exit --exit-code-from tests
docker compose -p "checkout-${CI_PIPELINE_ID:-local}" down --volumes --remove-orphans

The first command returns the test container's status. The second removes data even after failure and prevents parallel jobs from sharing networks or container names.

Make readiness observable, not time based

depends_on without a health condition controls startup order, not application readiness. A fixed sleep 10 may waste nine seconds on a fast runner and still fail on a loaded one. Poll a meaningful condition with a bounded timeout.

A database health check proves that the server accepts connections. An API readiness endpoint should prove that required migrations and internal initialization have completed. Keep liveness and readiness separate: a process can be alive while unable to serve tests.

When startup fails, preserve evidence before teardown:

mkdir -p test-results/containers
docker compose ps --all > test-results/containers/compose-ps.txt
docker compose logs --no-color > test-results/containers/compose.log

Verify the failure path deliberately. Break the database password and confirm the API becomes unhealthy, Compose returns nonzero, and logs explain the rejected connection. A health check that always returns success is worse than no check because it creates false confidence.

Control test data and database lifecycle

Choose one owner for schema migration. If both the API entrypoint and the test setup race to migrate, intermittent locks follow. A robust sequence is database ready, migrate once, seed minimum reference data, start application, execute tests.

Prefer creating scenario data through an API or a small test-data helper. Large SQL snapshots couple tests to internal columns and become difficult to update. Use SQL only when the database boundary itself is under test or when setup through public interfaces is prohibitively slow.

Each test should create unique business identifiers and clean up through a supported path. At suite level, a disposable database often makes cleanup simpler: start from an empty instance and destroy it after the run. Do not mount a named local volume in CI unless persistence is the behavior being tested.

To prove isolation, run the same stack twice with different project names and enable concurrency. Search both logs for unique run IDs. If records or ports cross between runs, the environment contract is incomplete.

Run browser checks without hiding the browser boundary

For UI testing, use a maintained browser image compatible with the framework version. A browser container adds shared-memory and resource constraints that can expose real CI issues. It also adds moving parts, so keep most behavioral coverage at API or component level.

Capture screenshots, traces, and videos on a host-mounted results directory rather than baking them into the image:

docker run --rm \
  --network "checkout-${CI_PIPELINE_ID:-local}_default" \
  -e BASE_URL=http://api:3000 \
  -v "$PWD/test-results:/workspace/test-results" \
  checkout-e2e:local npm run test:e2e

Avoid --network host as a convenience. It behaves differently across operating systems and weakens isolation. Also avoid assuming the host can reach an unexposed Compose port. Decide explicitly whether checks execute inside the network or through a published user-facing port.

When a browser crashes, compare container memory limits, shared-memory allocation, and trace output before classifying the test as flaky. Retrying without diagnosis can mask a resource problem.

Fit containers into CI without rebuilding everything

Build the application artifact once, tag it with the commit identifier, and test that same artifact at each relevant stage. Rebuilding for integration and deployment risks testing different bytes from those released.

Authenticate to registries through the CI secret store. Never place credentials in ARG, committed .env files, image layers, or Compose files. Redact environment output from logs because test tokens often have meaningful privileges.

Cache dependency and image layers where the CI platform supports it, but do not cache mutable test data. Cache misses should affect speed, not correctness. Always publish test reports and container logs on failure, and run cleanup in an unconditional final step.

A useful pipeline gate checks three independent outcomes: image build succeeded, the integration runner exited cleanly, and a machine-readable test report exists. A zero exit caused by “no tests found” should fail validation rather than silently pass.

Review reliability with destructive checks

Before calling the environment reproducible, challenge it:

1. Run from a clean clone with no local images or volumes.
2. Run two stacks concurrently.
3. Stop a dependency mid-test and inspect the diagnostic output.
4. Rebuild with the cache disabled and compare behavior.
5. Execute on the same CPU architecture and limits used by CI.
6. Confirm teardown occurs after both pass and failure.

Review image age, base-image vulnerabilities, health checks, and resource usage as maintenance work. Remove services no test observes. If a container exists only because production has one, it is adding cost without coverage.

Docker testing succeeds when a failed commit can be reproduced from the repository and its approved inputs, without relying on a particular laptop. The strongest signal is not that every component runs in a container. It is that the team can explain the environment, isolate each run, retrieve evidence, and release the exact artifact that passed.