View on
Guido Flohr > Test-Unit-GTestRunner > gtestrunner


Annotate this POD

View/Report Bugs


gtestrunner - GTk+ based frontend to Perl unit testing


    gtestrunner Tests/ Tests/
    gtestrunner Tests::MySuite Tests::OtherSuite


The program gtestrunner provides a comfortable and intuitive graphical user interface for running Perl unit tests.

If you don't know what unit tests or test driven development are, please start reading the documentation for Test::Unit(3pm), or search the internet for "JUnit" and "test driven development".

The sources for Test-Unit-GTestRunner contain a directory "Suites" with several dummy testsuites and test cases. They can serve as an example for you, and allow you to see gtestrunner in action. Change to the source directory and try

    gtestrunner Suites/


    gtestrunner Suites::TS_TopLevel

In fact, gtestrunner supports every way of test suite loading, that the underlying framework Test::Unit(3pm) supports. If you don't pass an argument to the script, you can load a test suite from within the user interface.

The program gtestrunner is actually a script wrapper around Test::Unit::GTestRunner(3pm).


The graphical user interface to gtestrunner follows the usual scheme of an application window and shouldn't contain any surprises to you.

The GUI mainly consists of a drop down menu, a toolbar, a progress bar, and a tabbed summary window. The tabbed summary window provides two different views, a flat lists of failures and a tree view of all tests, with indicators for success and failure for the individual test cases.

In either view you can select individual parts of your test suite. In case of test failures, you will see the corresponding error message in the lower window. You can also click the "Selected" button next to the "Run" button in the toolbar in order to re-run the corresponding tests.


The toolbar features five buttons:


A file selection dialog allows you to load a different test suite. Please make sure that the selected test suite compiles in the current working directory.

You can select multiple suites here.


Runs the entire test suite.


Read the label as "(Run) Selected". Run only the currently selected part of the test suite. In the failures view, you can only select individual tests. In the tree view you can select arbitrary parts of your test suite.


Recompiles the entire test suite, so that changes to the structure get visible in the tree view of the tests.

Refresh suites before every run

If checked, the test suite will be recompiled before it is run. If you don't recompile a suite, and tests have been removed or added, the display gets garbled. You may see error messages associated with the wrong test.


Tries to terminate the currently running test suite.


Yes, exactly! No, no confirmation dialog. I knew you would appreciate that.


The menu bar provides no more functionality than the toolbar. Please see the description of the corresponding toolbar buttons.


The program is a classical "dumb" frontend. It has no knowledge about unit test suites or their structure. The test suites passed as a command-line argument are fed into a subprocess, that loads these suites, and returns its structure to the parent process. Loading the test suite blocks, and the frontend does not repsonsive during this time.

Unless you have unchecked the option "Refresh suite before every run", this subprocess is also started before any test run, so that changes in the structure of the test suite are visible in the tree view of the frontend. Depending on the complexity of the suite, that may significantly increase the start up time for the test.

Every test run spawns a new Perl interpreter as another child process. The child interpreter is invoked with a -I argument (see perl(1)) for each member of the @INC array, so that the child process searches the same directories as the parent process.

You should keep this in mind, when you do changes to your test suites. It is generally safe to add or remove tests, test cases or test suites between runs, but only if you reload the suite before every run.


Copyright (C) 2004-2006, Guido Flohr <>, all rights reserved. See the source code for details.

This software is contributed to the Perl community by Imperia (


If the environment variable "GFC" is set, gtestrunner will use the Gtk+ FileChooser dialog instead of the Gtk+ FileSelection dialog.

The package is internationalized with libintl-perl, hence the environment variables "LANGUAGE", "LANG", "LC_MESSAGES", and "LC_ALL" will influence the language in which the GUI and messages are presented.


Test::Unit::GTestRunner(3pm), Test::Unit::GTestRunner::Worker(3pm), Test::Unit::GTestRunner::Lister(3pm), Test::Unit::TestRunner(3pm), Test::Unit(3pm), Locale::Messages(3pm), perl(1)

syntax highlighting: