Scroll to navigation

GNOME-DESKTOP-TESTING-RUNNER(1) General Commands Manual 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

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.

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

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

Write the output of each test to a file DIR/NAME.txt.

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.

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.

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

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.

Output a status message every few seconds if a test takes a significant time to run.

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

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

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

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,
    Test Anything
  Protocol