Container Inspection

Chain of Commands

The command in line 13 states the program to be executed, to which the test tool immediately passes all the parameters that follow args. In YAML format, a list comprises comma-separated elements inside square brackets. Listing 1 calls the rpm -q mysql-community-server-minimal command.

The output returned by this command must match the text entered after expectedOutput (line 15), which is the condition for passing the test. As with all other text comparisons, the test tool interprets the term between the quotation marks as a regular expression. For a successful test in Listing 1, the name of the identified package must start with mysql-community-server.

In addition to command and expectedOutput are setup and teardown (not used in this example), which specify commands that precede and follow the test, respectively. They can be used, for example, to create a virtual environment in a Python container and then fetch the Django framework with the pip package manager:

setup: [["virtualenv", "/env"], ["pip", "install", "django"]]

You need to encapsulate each command in a separate YAML list and save separately in the list each parameter to be passed in. In the example, the test tool would first run virtualenv /env and then pip install django.

Face Check

The checks on the filesystem are grouped below fileExistenceTests (lines 17-28). The example in Listing 1 tests whether the MySQL client and the database configuration file exist, where path is the file the tool is to examine. Both tests are considered to have passed if the file exists (shouldExist: true). The configuration file must also have the access rights listed after permissions.

The section below fileContentTests (lines 30-35) groups all the tests for which the tool needs to inspect a text file. The file to be inspected again follows path. The test is passed if the file contains the text listed after expectedContents. CST again interprets this as a regular expression. In Listing 1, the tool searches the database configuration file for a line containing datadir=/var/lib/mysql\n and ensures that the MySQL server stores its data below /var/lib/mysql. The \n stands for a line break, as usual.

The final checks, grouped below metadataTest, take a close look at the configuration of the container itself. Although developers can use the other sections shown earlier to store any number of tests in line with the schema, each test is only allowed once under metadataTest. The env parameter first checks whether the specified environment variables are set in the container; key is followed by the environment variable again, and its required value follows value. Listing 1 tests for a PATH environment variable with the specified paths in the container.

The exposedPorts entry then ensures that the listed ports are open. Similarly, volumes tests whether the specified volume exists, entrypoint checks the entry point, and cmd checks the command called automatically when the container is started (CMD in the Docker configuration file).

Container Inspection

Once all the tests are set up, it's time to pull the Docker image to be examined onto your hard drive. For example, to check out the official MySQL Docker image, mysql/mysql-server, from Docker Hub, you must run the command:

docker pull mysql/mysql-server

You then feed the name of the container image to be examined and the file containing the tests to be executed to the executable container-structure-test tool (Figure 1). In the following example, CST would run the tests from the mysql-tests.yaml configuration file against the mysql/mysql-server Docker image:

container-structure-test test --image mysql/mysql-server --config mysql-tests.yaml

Figure 1: The /test volume is not available, but all other tests were successful. The tool always executes all the tests, even if one fails.

To run the tests, container-structure-test starts the container. However, this is not always desirable (e.g., as part of a continuous integration process). In such cases, you can run container-structure-test directly against the image:

container-structure-test test --driver tar --image mysql/mysql-server --config mysql-tests.yaml

The --driver tar parameter ensures that container-structure-test packages the container image in a TAR archive and then executes the tests directly in the archive. Of course, this approach means that the CST tool can only perform the file-based tests and examine the container itself; it does not execute any commands (Figure 2).

Figure 2: If the test tool is not allowed to start the container, packing the container into a TAR archive not only slows the tests considerably, it also prevents commands being executed.