GNOME-DESKTOP-TESTING-RUNNER(1)

NAME
gnome-desktop-testing-runner, ginsttest-runner - run "as-installed" tests

SYNOPSIS
gnome-desktop-testing-runner [--dir=DIR] [--first-root] [--list] [--log-directory=DIR] [--parallel=PROC] [--quiet] [--report-directory=DIR] [--status=yes|no|auto] [--tap] [--timeout=SECONDS] PREFIX [PREFIX...]

gnome-desktop-testing-runner --log-msgid=MSGID=MESSAGE

ginsttest-runner OPTIONS

DESCRIPTION

gnome-desktop-testing-runner, also known as ginsttest-runner, runs "as-installed" tests. These tests are discovered using metadata in files named installed-tests/**/*.test, and are intended to check that a library or program is functioning correctly and has been installed correctly by a system integrator such as an OS distributor or system administrator.

Tests in this format are typically provided by GNOME-related libraries, but the concept, format and tools are not GNOME-specific and can be used by any software.

OPTIONS

--dir=DIR, -d DIR
    Look for test metadata in the installed-tests subdirectory of DIR, instead of using $XDG_DATA_DIRS. If repeated, each DIR is searched in order.

--first-root
    Stop after a directory that contains installed-tests has been encountered.

--list, -l
    Don't run any tests. Instead, list what would have been run on standard output, one per line, in the format NAME (PATH).

--log-directory=DIR, -L DIR
    Write the output of each test to a file DIR/NAME.txt.

--log-msgid=MSGID=MESSAGE
    Don't run any tests. Instead, emit a log message to the systemd Journal with the unique machine-readable message ID MSGID and the human-readable message MESSAGE. This can be used to mark important points in the test log from a test written in a language where direct access to the Journal is awkward, such as shell script or JavaScript.

--parallel=PROC, -p PROC
    Run up to PROC tests in parallel. The default is 1, meaning do not run tests in parallel. If PROC is 0, detect the number of CPUs and run that many tests in parallel.

--quiet
    Don't output test results, just log them to the systemd Journal if supported.

--report-directory=DIR
    Run each test with DIR/NAME as its current working directory, and write its output to a file DIR/NAME/output.txt. If the test succeeds, the directory is deleted. If the test fails, the directory is kept for analysis, including any temporary files or logs that the test itself might have written there.

--status=yes|no|auto
    Output a status message every few seconds if a test takes a significant time to run.

--tap
    Output machine-readable test results on standard output, in the format specified by TAP (the Test Anything Protocol (https://testanything.org/) originally used by Perl's test suite).

--timeout=SECONDS, -t SECONDS
    If a test takes longer than SECONDS seconds to run, terminate it. The default is 5 minutes (300 seconds).

PREFIX [PREFIX...]
    Only list or run tests that match one of these prefixes, relative to the installed-tests directory.

EXIT STATUS

0   All tests were successful, or --list or --log-msgid was successful

1   An error occurred during options parsing, setup or testing

2   The tests were run, and least one failed

ENVIRONMENT

XDG_DATA_DIRS
    Used to discover tests if --dir, -d is not specified.

FILES

/usr/local/share/installed-tests/**/*.test
    Conventional location for metadata describing tests installed by locally-installed software.

/usr/share/installed-tests/**/*.test
    Conventional location for metadata describing tests installed by the operating system packages.

/usr/local/libexec/installed-tests/**, /usr/libexec/installed-tests/**
    Conventional location for test executables and the data files they require (although this is not required, and they can be installed in any convenient location).

./.testtmp
    Each test will be invoked in a temporary directory containing only this file. Tests can use this to avoid overwriting important files if run without using gnome-desktop-testing-runner.

EXAMPLE

To run the tests from the json-glib library:
    ginsttest-runner json-glib-1.0/

To run the tests from the dbus, glib and json-glib libraries, with up to one process per CPU, producing machine-readable output and storing results of any failed tests in a directory:
    ginsttest-runner \
        --parallel=0 \
        --report-directory=artifacts \
        --tap \
        dbus/ glib/ json-glib-1.0/

SEE ALSO
GNOME Goal: Installed Tests (https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests), Test Anything Protocol (https://testanything.org/)