Skip to content
Tutorials Center
My learning

Topics

Lesson 82 of 111 ยท Registries and CI/CD

Testing Images and Integration Tests with Containers

Test the image you ship, not only the code: container-structure-test checks, smoke tests with Compose in CI, and the Testcontainers idea of throwaway dependencies.

Unit tests tell you the code works. They do not tell you that the image works. An image can fail in ways no unit test sees: a missing file because of a wrong COPY path, a binary that runs as root, a CMD that points at a script that is not executable, a port the app never opens. These bugs only appear when you start the real image, and by then it is usually in production.

This lesson shows three layers of image testing, from cheap to thorough: structure tests that inspect an image without running your app, smoke tests that start it and make one real request, and integration tests that start throwaway dependencies such as a database. The commands and files are read-only examples written from the documented behavior of the tools. This page cannot run a Docker daemon, so adapt them to your tool versions and check the output on your own machine.

Where image tests fit

The CI pipeline lesson put unit tests in a test stage. Image tests come after the build and before the push, because they need the finished image:

flowchart LR
  A["Unit tests<br/>(test stage)"] --> B["Build image"]
  B --> C["Structure tests<br/>(no container runs)"]
  C --> D["Smoke test<br/>(start + 1 request)"]
  D --> E["Integration tests<br/>(with dependencies)"]
  E --> F["Push to registry"]

Each step is slower and more realistic than the one before it. A failure at any step stops the pipeline before the push.

Layer 1: ask the image questions

Some checks need no running application at all. You can read the image's configuration with docker inspect and fail the job when it is wrong. This is plain shell, so it works in any CI system:

Terminal
#!/usr/bin/env bash
set -euo pipefail
IMAGE="$1"

user=$(docker inspect --format '{{.Config.User}}' "$IMAGE")
if [ -z "$user" ] || [ "$user" = "root" ] || [ "$user" = "0" ]; then
  echo "FAIL: image runs as root" >&2
  exit 1
fi

ports=$(docker inspect --format '{{json .Config.ExposedPorts}}' "$IMAGE")
case "$ports" in
  *8080/tcp*) ;;
  *) echo "FAIL: port 8080 is not exposed" >&2; exit 1 ;;
esac

echo "OK: user=$user ports=$ports"

The --format option takes a Go template; see Listing and Inspecting for the syntax. These checks are instant, they never start your app, and they protect rules you care about (non-root, expected port, a HEALTHCHECK present) from silent regressions. See Non-root Users and Capabilities for why the first one matters.

container-structure-test

Writing one shell script per rule gets repetitive. container-structure-test is a small open-source tool that reads a YAML file of expectations and checks them against an image. It can verify four kinds of things:

Test type What it checks
commandTests Runs a command in a container and checks exit code and output
fileExistenceTests A file or directory exists (or must not exist), with an optional permission
fileContentTests A file contains (or does not contain) certain text
metadataTest Image metadata: env, exposedPorts, entrypoint, cmd, workdir, user and similar

A test file for the Node.js image from the CI lesson could look like this:

YAML
schemaVersion: "2.0.0"

metadataTest:
  user: "node"
  workdir: "/app"
  exposedPorts: ["3000"]
  env:
    - key: NODE_ENV
      value: production
  cmd: ["node", "src/server.js"]

fileExistenceTests:
  - name: server entry point exists
    path: /app/src/server.js
    shouldExist: true
  - name: test files were not shipped
    path: /app/test
    shouldExist: false
  - name: no package-lock leaks dev tooling
    path: /app/node_modules/.bin/eslint
    shouldExist: false

commandTests:
  - name: runtime is the expected major version
    command: node
    args: ["--version"]
    expectedOutput: ["v24\\..*"]
  - name: app code loads without starting a server
    command: node
    args: ["-e", "require('/app/src/config.js'); console.log('config ok')"]
    expectedOutput: ["config ok"]

You run it with the tool's test command, passing the image and the config file (the exact flag names depend on your version, so check container-structure-test test --help):

CONSOLE
$ container-structure-test test --image app:ci --config structure-test.yaml

The tool prints one line per test and exits non-zero when any test fails, which is what CI needs. The most valuable tests are the negative ones, such as "the test directory does not exist". They catch the classic mistake of a COPY . . that drags source tests, .env files or private keys into the image. A good .dockerignore prevents it, and a structure test proves it did.

Test what you decided on purpose: the user, the working directory, the entrypoint, the files that must not exist, and the version of the language runtime. Do not test every layer. A suite that breaks on every harmless rebuild gets deleted.

Layer 2: the smoke test

A smoke test answers one question: does the image start and respond? It runs the real container, waits until it is healthy, makes one request and removes everything. If the image has a health check, the wait is easy:

Terminal
#!/usr/bin/env bash
set -euo pipefail
IMAGE="$1"

cid=$(docker run -d -p 127.0.0.1:0:8080 "$IMAGE")
trap 'docker logs "$cid" || true; docker rm -f "$cid" >/dev/null' EXIT

for i in $(seq 1 30); do
  status=$(docker inspect --format '{{.State.Health.Status}}' "$cid")
  [ "$status" = "healthy" ] && break
  sleep 1
done
[ "$status" = "healthy" ] || { echo "FAIL: not healthy after 30s" >&2; exit 1; }

port=$(docker port "$cid" 8080/tcp | head -n1 | sed 's/.*://')
curl --fail --silent "http://127.0.0.1:$port/health"
echo
echo "smoke test passed"

Three details make this script reliable in CI:

  • -p 127.0.0.1:0:8080 lets Docker pick a free host port, so two jobs on the same runner never collide. You then read the real port with docker port.
  • The trap runs on success and failure. It prints the container logs (so a failed job explains itself) and removes the container, so the runner stays clean.
  • curl --fail turns an HTTP 4xx or 5xx response into a non-zero exit code.

If the image has no HEALTHCHECK, replace the loop with a retry on curl. Never use a fixed sleep 10 and hope: it is too slow on a good day and too short on a bad one.

Layer 3: integration tests with Compose

Most real services need a database or a cache. For an integration test you start the image together with its dependencies, run a test container against them, and throw everything away. Compose does this well, using health-based startup ordering:

YAML
services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: test-only
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 3s
      retries: 15

  app:
    image: ${IMAGE:?set IMAGE to the image under test}
    environment:
      DATABASE_URL: postgres://postgres:test-only@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy

  tests:
    image: curlimages/curl:8.11.1
    depends_on:
      - app
    command: ["--fail", "--silent", "--retry", "20", "--retry-connrefused", "--retry-delay", "1", "http://app:8080/health"]
CONSOLE
$ IMAGE=app:ci docker compose -f compose.test.yaml up \
    --abort-on-container-exit --exit-code-from tests
$ docker compose -f compose.test.yaml down --volumes

--exit-code-from tests makes the whole command return the exit code of the tests service, so a failing check fails the job. down --volumes removes the networks and the database volume. The password test-only is a throwaway value for a database that lives for thirty seconds; real secrets never belong in a test file (see Secrets Management).

Note that the test container reaches the app by its service name, app, over the Compose network, not through a published port. Container Communication explains why that works.

The Testcontainers idea

Compose files describe the environment outside the test. A second approach describes it inside the test code. The Testcontainers libraries (available for Java, Go, Python, Node.js, .NET, Rust and others) let a test start containers from code, wait until they are ready, read their random ports, and remove them when the test ends:

Python
import psycopg
from testcontainers.postgres import PostgresContainer

def test_orders_table_round_trip():
    with PostgresContainer("postgres:17-alpine") as pg:
        with psycopg.connect(pg.get_connection_url(driver=None)) as conn:
            conn.execute("create table orders (id int primary key, total int)")
            conn.execute("insert into orders values (1, 250)")
            row = conn.execute("select total from orders where id = 1").fetchone()
    assert row == (250,)

The ideas matter more than the library:

  • Real dependencies, not mocks. The test talks to a real PostgreSQL, so SQL dialect mistakes, constraints and migrations are actually exercised.
  • Every test run gets a fresh instance on a random port, so tests do not depend on a shared, slowly rotting "test database".
  • Cleanup is automatic, even when the test crashes, because the library also starts a small helper container that removes leftovers.

The library needs access to a Docker daemon. On a CI runner that is the host daemon; if your tests themselves run inside a container, you need to mount the socket or use a remote daemon, with the security trade-offs described in Docker in Docker.

Putting it into a pipeline

A GitHub Actions job that applies all three layers might look like this (read-only; adapt versions and action names to your setup):

YAML
jobs:
  image-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build the image (loaded locally, not pushed)
        run: docker build --target runtime -t app:ci .
      - name: Structure checks
        run: ./ci/check-image.sh app:ci
      - name: Smoke test
        run: ./ci/smoke-test.sh app:ci
      - name: Integration test
        run: |
          IMAGE=app:ci docker compose -f compose.test.yaml up \
            --abort-on-container-exit --exit-code-from tests
      - name: Cleanup
        if: always()
        run: docker compose -f compose.test.yaml down --volumes

The push step comes in a later job that needs: image-tests, so a registry only ever receives images that passed. Test the image by the tag you built, then promote that same image, as described in Docker in CI. Rebuilding for the push would test one artifact and ship another.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What kind of bug does an image test catch that a unit test usually cannot?

    Unit tests run your code in a development environment. Problems in how the image is assembled (paths, permissions, user, ports) only show up when you inspect or run the finished image.
  2. 2. Why is a negative file test, such as "/app/test must not exist", valuable?

    A careless COPY . . can ship files you never intended to publish. A test that asserts they are absent turns that mistake into a failed pipeline.
  3. 3. In a smoke-test script, why use -p 127.0.0.1:0:8080 instead of a fixed host port?

    Host port 0 lets Docker choose any free port. You then read the real one with docker port. Fixed ports cause random failures when two jobs run at the same time.
  4. 4. What does --exit-code-from tests do in docker compose up?

    Without it, compose up can exit with success even when your test container failed. With it, the job's result is the test container's result.
  5. 5. What is the main idea behind Testcontainers?

    Real dependencies on random ports, created fresh and cleaned up automatically, give realistic tests without a shared test environment.

Summary

  • Image tests check what unit tests cannot: how the image is assembled and whether it starts.
  • Cheap first: read configuration with docker inspect or a container-structure-test YAML (metadata, files that must and must not exist, command output).
  • A smoke test runs the real image, waits for healthy instead of sleeping, makes one request with curl --fail, and always cleans up and prints logs on failure.
  • Integration tests start the image with real dependencies using a Compose file; --abort-on-container-exit --exit-code-from turns the result into the job's exit code.
  • Testcontainers moves the same idea into test code: throwaway real dependencies on random ports, cleaned up automatically.
  • Test the exact image you built, then promote that same image; push only after every test passed.

Next: Containerizing a Node.js App