GNOME-DESK...ING-RUNNER(1)

💖 GNOME-DESK...ING-RUNNER(1) 💖

okay bestie, sit down, we're learning gnome-desktop-testing-runner (also known as ginsttest-runner) from the General Commands Manual, and honestly? it's giving infrastructure icon. no cap.

✨ 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

three whole ways to summon it, pick your fighter 💅

🦋 DESCRIPTION 🦋

so gnome-desktop-testing-runner, aka ginsttest-runner, runs "as-installed" tests. periodt.

these tests get discovered through metadata living in files named installed-tests/**/*.test, and their whole vibe is checking that a library or program is functioning correctly and that it got installed correctly by a system integrator — like an OS distributor or a system administrator. so it's not just "does this code work", it's "did the person who shipped it to you actually ship it right" 👑

tests in this format are typically provided by GNOME-related libraries, but the concept, the format and the tools are not GNOME-specific and can be used by any software. inclusive queen behavior fr fr 🌈

💅 OPTIONS 💅

• --dir=DIR, -d DIR — look for test metadata in the installed-tests subdirectory of DIR, instead of using $XDG_DATA_DIRS. if you repeat it, each DIR gets searched in order. ✨
• --first-root — stop after a directory that contains installed-tests has been encountered. like, we found it, we're done, bye 💅
• --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). it's giving window shopping 🛍️
• --log-directory=DIR, -L DIR — write the output of each test to a file DIR/NAME.txt. receipts, bestie 📝
• --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 is for marking 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. iykyk 😭
• --parallel=PROC, -p PROC — run up to PROC tests in parallel. 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. multitasking queen 🔥
• --quiet — don't output test results, just log them to the systemd Journal if supported. silent but deadly 🤫
• --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. crime scene preservation, love that for us 🔍
• --status=yes|no|auto — output a status message every few seconds if a test takes a significant time to run. "are we there yet" mode 🎀
• --tap — 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). robots can read this one 🤖
• --timeout=SECONDS, -t SECONDS — if a test takes longer than SECONDS seconds to run, terminate it. default is 5 minutes (300 seconds). clock is ticking bestie ⏰
• PREFIX [PREFIX...] — only list or run tests that match one of these prefixes, relative to the installed-tests directory. filter, serve, slay 🌟

👑 EXIT STATUS 👑

1. 0 — all tests were successful, or --list or --log-msgid was successful 🥳
2. 1 — an error occurred during options parsing, setup or testing 😬
3. 2 — the tests were run, and at least one failed 💀

🌈 ENVIRONMENT 🌈

• XDG_DATA_DIRS — used to discover tests if --dir, -d is not specified. she's the fallback bestie 🫶

🍓 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. the lil safety marker, iconic 🌸

⭐ 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/

look at that backslash continuation. ate and left no crumbs 🔥

🎀 SEE ALSO 🎀

• GNOME Goal: Installed Tests
• Test Anything Protocol

okay and that's the whole page bestie, no notes 💜 this was GNOME-DESK...ING-RUNNER(1) from the General Commands Manual — the title up top and down at the bottom both say exactly GNOME-DESK...ING-RUNNER(1), and yeah, we mentioned it twice because the original page does too. consistency, queen 👑✨🦋