Home / Alt manpages / gtester-report(1)

  • gtester-report(1)
  • User command
  • linux

Turn a gtester XML Log into an HTML Report

Convert a GLib gtester XML log into a self-contained HTML report with gtester-report, then check the totals it produced match what you expect. Allow about ten minutes if the XML log already exists.

The route

Jump straight to the step you need, or tick off Done means at the end.

The command is deprecated, so use this for maintaining an older test setup or reading an existing archive, not for starting a new reporting system.

1. Confirm which installation will run

This guide uses the Ubuntu package installed on this machine, version 2.80.0-6ubuntu3.9. Pinning the path matters: this host also has a Homebrew copy earlier in PATH, reporting GLib utils version 2.86.4. Do not compare output from the two copies without checking which one ran.

$ command -v /usr/bin/gtester-report
/usr/bin/gtester-report
$ /usr/bin/gtester-report --version
gtester-report (GLib utils) version 2.80.0

Use the absolute path in the examples when you need the packaged version. Running a report needs no elevated privileges, just read access to the XML file and write access to the destination directory.

Checkpoint

If command -v gtester-report prints a different path, either use that installation consistently or keep the explicit /usr/bin/ prefix.

2. Check that the input is a gtester log

gtester-report accepts exactly one positional argument: an XML log generated by gtester. It does not run the tests and does not discover a log automatically. A log is normally created by passing -o to gtester:

$ gtester -o /path/to/project-tests.xml /path/to/project-tests
$ test -r /path/to/project-tests.xml && echo 'XML log is readable'
XML log is readable

Use the actual test binary and output path from your project. If the log was produced elsewhere, inspect it without modifying it:

$ file /path/to/project-tests.xml
/path/to/project-tests.xml: XML 1.0 document, ASCII text

The exact description from file can differ. The useful check is that the path names the XML log, not an HTML report or an unrelated configuration file.

3. Generate the HTML into a new file

Redirect standard output to a new destination. The deprecation warning goes to standard error while the HTML goes to standard output:

$ /usr/bin/gtester-report /path/to/project-tests.xml > /path/to/project-tests.html
Deprecated: Since GLib 2.62, gtester and gtester-report are deprecated. Port to TAP.

That warning is expected on current GLib releases. A successful command normally prints no progress or summary to the terminal, because the report itself is the standard output. Check the exit status and the start of the file:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ sed -n '1,18p' /path/to/project-tests.html
<html><head>
<title>GTester Unit Test Report</title>

The generated document contains its own HTML, CSS and JavaScript. It includes a package heading when the XML has package and version information, a table of test binaries, per-test rows, and totals. It is not a fragment to paste into another page without first checking how that page handles a complete document.

4. Read the result table correctly

Open the new file in a browser or inspect it with a text tool. The binary row shows the test program and accumulated duration; its percentage excludes skipped cases. Skipped test cases are omitted from the HTML detail rows, so a report can show fewer individual rows than the XML contained.

$ grep -E 'Package:|Totals:|Succeeded|Failed' /path/to/project-tests.html
<h3>Package: demo, version: 1.0</h3>
<td><strong>Totals:</strong> 1 Binaries, 1 Tests, 0 Failed, 1 Succeeded</td>

The wording and whitespace can vary with the installed GLib release, so treat this as a targeted check rather than a fixed parser format. For a failed test, the report adds a Details link containing the error text.

Checkpoint

A non-zero command status or a missing expected test result needs investigation. Do not call the report green merely because an HTML file was created.

5. Avoid overwriting a useful report

Shell redirection with > truncates an existing destination before gtester-report even starts. Use a temporary name, validate it, then replace the old report only once you are satisfied:

$ /usr/bin/gtester-report /path/to/project-tests.xml > /path/to/project-tests.html.new
$ test -s /path/to/project-tests.html.new
$ grep -q 'GTester Unit Test Report' /path/to/project-tests.html.new
$ mv -- /path/to/project-tests.html.new /path/to/project-tests.html

mv renames the destination within the same filesystem. If conversion fails or the checks do not match, leave the old report in place and remove the temporary file after inspecting it.

Destructive action

That removal only touches the new output, so verify the path before using rm:

$ rm -- /path/to/project-tests.html.new

If the old report has already been overwritten, recover it from your normal backup or version-control history. There is no undo operation in gtester-report.

6. Treat subunit output as an optional compatibility path

The --subunit option selects subunit output instead of HTML, but it requires the Python python-subunit package. It is not a way to make the deprecated XML format current, and it is not useful unless the next tool in your pipeline accepts subunit:

$ /usr/bin/gtester-report --subunit /path/to/project-tests.xml > project-tests.subunit
Usage: gtester-report [OPTIONS] <gtester-log.xml>
gtester-report: error: python-subunit is not installed.

Do not install a dependency just to silence this error without checking the receiving system. The ordinary HTML path has no subunit dependency.

7. Plan the replacement

GLib documents gtester-report as deprecated since GLib 2.62 and points new reporting towards TAP consumed by a test harness. Keep this utility at the edge of a legacy workflow, record the GLib version that generated each report, and plan a migration rather than building new automation around its HTML. The report is a presentation of the XML log, not a stronger test verdict.

Done means

  • Right binary confirmed. You checked the exact gtester-report executable and version.
  • Input verified. The input is one readable XML log produced by gtester.
  • Streams separated. The deprecation warning is kept separate from the generated HTML.
  • Totals checked. You checked the report's package, totals and skipped-test behaviour.
  • Safe replacement. A temporary output was validated before replacing any existing report.
  • Migration noted. You know new GLib test reporting should move towards TAP.