ContainerStructureTest

---

title: container-structure-test type: tool created: 2026-05-26 last_updated: 2026-05-26 related: ["radar/tools/Hadolint", "radar/techniques/ContinuousIntegration"] sources: ["https://github.com/GoogleContainerTools/container-structure-test"] radar_quadrant: Tools radar_ring: Assess radar_position: inner

container-structure-test

Google's open-source tool for validating the structure of Docker container images. Tests run against a built image and verify properties that functional tests cannot easily cover: file existence and permissions, expected commands and their exit codes, metadata fields, and environment variables.

What It Tests

Tests are declared in YAML and grouped into four categories:

• Command tests — run a command inside the container and assert exit code and output (e.g. nginx -t exits 0, python --version contains 3.11)
• File existence tests — assert that specific paths exist or do not exist in the image filesystem
• File content tests — assert that file contents match a pattern or string
• Metadata tests — validate image labels, exposed ports, entrypoint, working directory, environment variables, and running user

CI Integration

Tests run as a single binary invocation against a local or remote image tag:

container-structure-test test --image myapp:latest --config structure-test.yaml

The binary is statically compiled and has no runtime dependencies. It integrates naturally into any CI pipeline that builds Docker images, running after the build step and before push.

Radar Assessment

container-structure-test sits in the Assess ring of the Tools quadrant, at inner position. First studied via GitHub (2024-09-23). The tool fills a gap in Docker CI workflows: image builds succeed but structural regressions — wrong user, missing config file, broken entrypoint — go undetected until runtime. Tests are declarative and fast. The complementary tool hadolint (see radar/tools/Hadolint) lints the Dockerfile before build; container-structure-test validates the result after. Together they form a complete image quality gate. Remaining gate before Trial is a working CI pipeline with structure tests catching at least one real regression.