Run GLib Tests with gtester Reproducibly

Use gtester to run a compiled GLib test program, select one test path, save an XML log, and rerun a randomised test with the exact same seed. This guide uses gtester 2.86.4 from libglib2.0-dev-bin 2.80.0-6ubuntu3.9 on the local system.

Allow about fifteen minutes. You need a compiled GLib test program and a shell. The examples use a binary called /tmp/gtester-guide-test; swap in the path to your own. Running tests is an ordinary user operation: skip sudo unless the test itself explicitly needs privileged access.

1. Confirm the installed command

Check the executable and its package before trusting any option details below. These only read local system information:

$ command -v gtester
/home/linuxbrew/.linuxbrew/bin/gtester
$ gtester --version
gtester version 2.86.4
$ dpkg-query -W -f='${Package} ${Version}\n' libglib2.0-dev-bin
libglib2.0-dev-bin 2.80.0-6ubuntu3.9

The installed help calls -v and --version version options, and shows the test program as the final argument after any gtester options:

$ gtester --help
Usage:
gtester [OPTIONS] testprogram...

Help Options:
  -k, --keep-going              Continue running after tests failed
  -p=TESTPATH                   Only start test cases matching TESTPATH
  -o=LOGFILE                    Write the test log to LOGFILE

2. Run the complete test binary

Pass the executable as the final argument to run every test case it registers:

$ gtester /tmp/gtester-guide-test
TEST: /tmp/gtester-guide-test...
PASS: /tmp/gtester-guide-test

Current GLib installations also print a deprecation warning: gtester and gtester-report have been deprecated since GLib 2.62, with a recommendation to port to TAP. That is a migration task for the build system, not evidence this run failed. A final PASS is the result that matters here.

When scripting the command, capture the status immediately:

$ gtester /tmp/gtester-guide-test
$ status=$?
$ printf 'gtester exit status: %s\n' "$status"
gtester exit status: 0

A non-zero status needs investigation. Keep the test program and its dependencies unchanged until you have recorded the failure output. The command itself does not repair a broken test, alter source files, or install anything.

3. List and select test paths

Use -l to ask the test binary for its available paths, which are registered by the GLib program and are normally slash-separated:

$ gtester -l /tmp/gtester-guide-test
/basics/answer
/basics/text

Use -p=TESTPATH to start only matching cases. Quote a path if it comes from a variable or contains shell metacharacters:

$ gtester -p=/basics/answer /tmp/gtester-guide-test
TEST: /tmp/gtester-guide-test...
PASS: /tmp/gtester-guide-test

• Match is exact. The GLib test framework performs the match, so the exact path matters: list paths and compare character by character if a selection runs nothing.
• Order matters on the command line. Put gtester options before the executable and the executable's own arguments after it, so they do not get confused with each other.

4. Make a run reproducible

GLib tests can use a random seed. Supply --seed=SEEDSTRING to pin the run to a particular seed:

$ gtester --seed=R02S62ec1ec19da76d63b7d9f34dc3f83261 /tmp/gtester-guide-test
TEST: /tmp/gtester-guide-test...
PASS: /tmp/gtester-guide-test

Use the seed printed in a failing run's diagnostics when you need to reproduce its ordering or random data. A seed only helps if the test inputs, binary, environment and dependencies are also comparable; it is not a substitute for recording the commit and build configuration.

• -m=quick is the default. It skips slow and performance tests and adds no extra repeats of non-deterministic tests.
• -m=slow or -m=thorough. Use either when the suite defines those categories and a longer run is acceptable.
• -m=no-undefined. Omits tests deliberately designed to provoke checks or assertion failures.
• Do not add --g-fatal-warnings casually. It makes warnings fatal and can turn an informative run into an abort.

5. Save an XML report when a tool requires it

Write the XML test log with -o=LOGFILE:

$ gtester -o=/tmp/gtester-guide-report.xml /tmp/gtester-guide-test
TEST: /tmp/gtester-guide-test...
PASS: /tmp/gtester-guide-test
$ head -8 /tmp/gtester-guide-report.xml
<?xml version="1.0"?>
<!-- Deprecated: Since GLib 2.62, gtester and gtester-report are deprecated. Port to TAP. -->
<gtester>
  <testbinary path="/tmp/gtester-guide-test">

The report holds testcase paths, durations and result attributes. Keep it as a build artefact, not a live database. The XML route exists for older tooling, but the manpage and current GLib documentation point new integrations towards TAP and the test harness supplied by the build system.

6. Keep failures useful

By default a failed test can stop the run. Add -k or --keep-going when you need the remaining cases to run and produce a fuller failure set:

$ gtester --keep-going /tmp/gtester-guide-test
TEST: /tmp/gtester-guide-test...
PASS: /tmp/gtester-guide-test

Use -q or --quiet to suppress per-test-binary output, then rely on the exit status and saved log. Use the long --verbose option when you need per-testcase success reported. Do not confuse that with -v, which prints version information and exits.

If the command cannot open the executable, check the path and execute permission without changing anything:

$ ls -l /tmp/gtester-guide-test
$ test -x /tmp/gtester-guide-test && echo executable
executable

If a selected path is missing, rerun gtester -l. If the program itself exits unsuccessfully, run it directly under the same environment only when that is safe, then compare the direct output with the harness output. Avoid changing test data while you diagnose.