apptainer-test

Run the test script of a container

$ apptainer test [container.sif]

$ apptainer test docker://[image:tag]

$ apptainer test --app [appname] [container.sif]

$ apptainer test --bind [/data]:[/mnt] [container.sif]

$ apptainer test --nv [container.sif]

apptainer test [options] container

apptainer test executes the test script defined in a container's %test section. This provides a standardized way for container authors to include validation checks that verify the container is functioning correctly.
Test scripts typically check that required software is installed, libraries are accessible, and the container can perform its intended function. The exit code of the test script determines pass (0) or fail (non-zero) status.
For containers using the Scientific Filesystem (SCIF), the --app flag runs the test section of a specific application within the container. This allows multi-app containers to have independent test suites.
Container authors define tests during build time. If no %test section exists, the command completes successfully without executing anything. This command is useful in CI/CD pipelines to validate container builds before deployment.

--app name

Run the test section of a specific SCIF app.

Bind mount a host path into the container.

Enable NVIDIA GPU support.

Enable AMD ROCm GPU support.

Use minimal /dev and empty other directories.

Full containment mode.

Clean environment before testing.

Run test with fake root privileges.

Set working directory inside container.

Display help for the test command.

Only runs tests if a %test section was defined during container build. Returns success even if no test exists (silent pass). Test scripts have the same environment constraints as the container runtime. Complex tests may require bind mounts or GPU flags to function properly.

The test subcommand has been part of Singularity/Apptainer since early versions, providing container authors a standardized way to validate their builds. It supports the reproducibility goals of scientific computing by ensuring containers meet expected functionality. Apptainer preserved this feature when the project forked from Singularity in 2021.

apptainer(1), apptainer-build(1), apptainer-run(1), apptainer-inspect(1)