Run GLib Unit Tests with gtester and Keep Results Reproducible

You will finish with a repeatable way to run a GLib test executable, select one test path, save an XML log, and rerun randomised tests with the 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; replace it with the path to your own test executable. Running tests is an ordinary user operation. Do not use sudo unless the test itself explicitly needs privileged access.

1. Confirm the installed command

Check the executable and its package before relying on option details. These commands 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. It also shows that the test program is 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

Checkpoint: if command -v finds a different installation than expected, stop and check its version and help. Do not mix examples from a different GLib build without checking the local command.

2. Run the complete test binary

Pass the executable as the final argument. This runs the test cases registered by the program:

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

Output also includes a deprecation warning on current GLib installations: gtester and gtester-report have been deprecated since GLib 2.62, and the warning recommends porting to TAP. Treat that as a migration task for the build system, not as evidence that this particular run failed. A final PASS is the useful result here.

Capture the status immediately when scripting the command:

$ 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 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. The paths are registered by the GLib program and are normally slash-separated:

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

Use -p=TESTPATH when you want 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

The match is performed by the GLib test framework, so the exact path matters. If a selection appears to run nothing, first list the paths and compare them character by character. A common distraction is confusing the test program's own options with gtester options; put gtester options before the executable and the executable's arguments after it.

Checkpoint: use -s=TESTPATH to skip matching paths when you need the complement of a selection. Record both the include or skip expression and the binary path in CI logs so another reader can reproduce the same scope.

4. Make a run reproducible

GLib tests can use a random seed. Supply --seed=SEEDSTRING to make the run use 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 mode. It avoids slow and performance tests and does not add extra repeats of non-deterministic tests. Use -m=slow or -m=thorough when the test suite defines those categories and a longer run is acceptable. Use -m=no-undefined to omit tests deliberately designed to provoke checks or assertion failures. Do not add --g-fatal-warnings casually: it makes warnings fatal and can turn an otherwise 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 contains testcase paths, durations and result attributes. Keep it as a build artefact rather than treating it as 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.

Warning: choose a new report path or check the destination before running. -o writes the log, and a shell redirection or another tool can overwrite an existing report. If you are replacing a report used by a release job, copy the old file first and verify the new one before deleting the backup.

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 execute 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 success reported per testcase. Do not confuse that option 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 under the same environment without gtester only when that is safe, then compare the direct program output with the harness output. Avoid changing test data during diagnosis.