Container Structure Test

Visit Website

Introduction

Container Structure Test validates the structure of a container image. A YAML config lists checks of four kinds: command tests that run a command in the image and assert on output and exit code, file existence tests, file content tests, and metadata tests for environment variables, entrypoint, exposed ports, labels and user.

It runs against images through Docker or other drivers and fits naturally after the image build step in CI. Typical uses are confirming that a binary is on the path, that a config file contains the right setting, or that the image runs as a non-root user.

In the quality loop it is an integration gate for images, alongside linters such as Hadolint and scanners such as Trivy.

The source code is at GoogleContainerTools/container-structure-test on GitHub under the Apache-2.0 licence, with about 2,500 stars; the most recent commit was on 15 April 2026.

Features

1. Command tests: Run commands and assert output.
2. File existence: Check paths and permissions.
3. File content: Match expected content with regex.
4. Metadata tests: Entrypoint, env, ports, labels, user.
5. Drivers: Docker and other runtimes.
6. JUnit output: For CI reporting.

Pros

1. Focused: Simple checks that are easy to read.
2. Free to use: Open source under the Apache-2.0 licence, so the core tool costs nothing to use.
3. Actively maintained: The repository had commits as recent as 15 April 2026.

Cons

1. Slow release cadence: Releases are infrequent.
2. Image only: Does not test running services together.
3. YAML-limited: No complex logic.

Usage and Links (Example)

schemaVersion: 2.0.0
commandTests:
  - name: app runs
    command: /app/server
    args: ["--version"]
    expectedOutput: ["v\\d+"]
metadataTest:
  user: "10001"

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

Resources:

• Container Structure Test website

Pricing

Container Structure Test is free and open source under the Apache-2.0 licence.

Recommended for?

1. Teams publishing base images that need guarantees about contents.
2. CI pipelines checking images before push.

Conclusion

Container Structure Test is a small, dependable gate for image contents and metadata.

Add it right after the build step.

On CheckOps, Container Structure Test is filed under the Integration testing and Release & CI gates stages. Related tools listed here include Goss, Hadolint, Trivy, Dockle, Terratest and Test Kitchen. Which one fits best depends mostly on your stack, your team’s size and skills, and whether you prefer to run tools yourself or pay for a managed service. This page reflects the official website, documentation and repository as they stood on 11 November 2026.