22.3 Running the Test Suite

After a successful configure and make run, it is a good idea to run the test suite. It can help catch issues with the setup or environment, or bugs in Guix itself—and really, reporting test failures is a good way to help improve the software. To run the test suite, type:

make check

Test cases can run in parallel: you can use the -j option of GNU make to speed things up. The first run may take a few minutes on a recent machine; subsequent runs will be faster because the store that is created for test purposes will already have various things in cache.

It is also possible to run a subset of the tests by defining the TESTS makefile variable as in this example:

make check TESTS="tests/store.scm tests/cpio.scm"

By default, tests results are displayed at a file level. In order to see the details of every individual test cases, it is possible to define the SCM_LOG_DRIVER_FLAGS makefile variable as in this example:

make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"

The underlying SRFI 64 custom Automake test driver used for the ’check’ test suite (located at build-aux/test-driver.scm) also allows selecting which test cases to run at a finer level, via its --select and --exclude options. Here’s an example, to run all the test cases from the tests/packages.scm test file whose names start with “transaction-upgrade-entry”:

export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
make check TESTS="tests/packages.scm"

Those wishing to inspect the results of failed tests directly from the command line can add the --errors-only=yes option to the SCM_LOG_DRIVER_FLAGS makefile variable and set the VERBOSE Automake makefile variable, as in:

make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1

The --show-duration=yes option can be used to print the duration of the individual test cases, when used in combination with --brief=no:

make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"

See Parallel Test Harness in GNU Automake for more information about the Automake Parallel Test Harness.

Upon failure, please email bug-guix@gnu.org and attach the test-suite.log file. Please specify the Guix version being used as well as version numbers of the dependencies (see Requirements) in your message.

Guix also comes with a whole-system test suite that tests complete Guix System instances. It can only run on systems where Guix is already installed, using:

make check-system

or, again, by defining TESTS to select a subset of tests to run:

make check-system TESTS="basic mcron"

These system tests are defined in the (gnu tests …) modules. They work by running the operating systems under test with lightweight instrumentation in a virtual machine (VM). They can be computationally intensive or rather cheap, depending on whether substitutes are available for their dependencies (see Substitutes). Some of them require a lot of storage space to hold VM images.

If you encounter an error like:

Compiling Scheme modules...
ice-9/eval.scm:142:16: In procedure compile-top-call:
error: all-system-tests: unbound variable
hint: Did you forget `(use-modules (gnu tests))'?

there may be inconsistencies in the work tree from previous builds. To resolve this, try running make clean-go followed by make.

Again in case of test failures, please send bug-guix@gnu.org all the details.