GuiRunner for FIT-Tests

Introduction
First stepts
Configuration
Download
Test Drive
Changes
Miscellaneous

Introduction

screenshot

GuiRunner is a front end for running fit-tests. Its goals are to simplify the customer-side tasks: running existing tests, create new tests, manage existing ones. GuiRunner invokes other runners, interprets their output and presents a visualization of the results. So, GuiRunner can be used together with different fit-implementations: java, perl etc.
Beside that, GuiRunner can be also used as a command-line directory runner.

First steps

GuiRunner runs test, wich reside somewhere in your directory structure, starting at some point. Output files are generated somewhere below a defined output directory. The tests are run by a runner command, configured in the gui. GuiRunner stores these - and some further - information in a file called configuration, or "project".

So, how to start?
Create a new configuration, define the directory, where tests are stored. Define a directory, where the output should go to. Define a runner command, and: go!
You haven't used fit tests before? Start with a test drive!

How to use the gui?
All features are accessible via menu, toolbar, context menu or a double click. The appropriate actions are disabled, if its usage makes no sense in the current context.

Configuration-related actions

New Configuration: Creates a new configuration (configuration file). Default values are appropriate for java-based runners.
Open Configuration: Opens a previously created configuration (configuration file).
Edit Configuration: Opens a dialog box for editing the configuration entries. See below for information on all the fields.

Actions related to Executing tests

Run all: Executes all tests, i.e. runs the configured runner on each entry in the view
Run marked: Execute that tests, which are marked in the mark column of the view
Run current: Execute the test specified by the current row
View output file: Open the output file of the test in the current row. By default, the system-default html viewer is opened
View runner output: Shows the output of the respective runner command
Stop tests: The test execution will be stopped after the test being run completes.
Terminate tests: The current test will be aborted, i.e. the respective process gets killed. The test execution will be stopped.

Actions related to Test-Documents

Reload: Rescans the directory structure in order to find any new or deleted files, refered to the last directory scan.
Edit input file: Opens the current test file in a well-defined editor
New Test: Creates a new test, with some template-structure in it. Opens that newly created file in the well-defined editor.
Delete Test: Removes the test from the view an deletes the test file in the file system.
Rename/Move Test: Allows you to change the name of the test file (rename) or to move it to a different directory (below the input-directory!)

View can be sorted by clicking on the respective column header. Multi column sort is done by clicking on the respective column header while the CTRL-key is pressed.

Configuration

All necessary data is stored in a property file, called configuration. A configuration can be edited through the gui.
These are the entries (with their default values):

indir=in
outdir=out
libdir=lib
command.open=cmd /c start "Start..." "${outfile}"
command.edit=cmd /c start "Start..." winword /n "${infile}"
command.runner=java -cp "${classpath}" fit.FileRunner "${infile}" "${outfile}"
runner.workingDir=

All entries contain either an absolute path, or a relative path, relative to the directory where the configuration file is residing. You will guess, that there is a sort of variable expansion: this is true, see variable expansion for more.

indir: Base directory for test files.
outdir: Base directory for result files. The directory structure beneath indir and outdir will be the same. Required subdirectories in beneath outdir are created as needed.
libdir: A general-purpose directory. May specify a directory where libraries or shared modules reside. For the java world, contents of libdir will be scanned for *.jar files.
command.open: The command used to start a html viewer.
command.edit: The command used to start a html editor.
command.runner: The actual test-runner command.
runner.workingDir: Working directory of the respective runner. May be specified with absolute or relative path. Also a variable reference, e.g. ${infiledir} - the directory where the input file resides, may be specified. Such a variable reference will be expanded just before the runner starts.

At start GuiRunner uses the last used configuration.

GuiRunner maintains a preferences file, stored in users's home. The file is named .fit.GuiRunner.properties.

Variable expansion

Following variables will be expanded at present: indir, outdir, libdir, classpath, outfile, infile and infiledir (directory name in which infile resides).
classpath - all jar-files found in libdir are joined together according to the os-specific rules (e.g. fit.jar:test.jar for *nix, fit.jar;test.jar for MsWin32 etc.)
Hint If your code under test is not packaged in jar-files, use ${libdir} instead of ${classpath}.

Runner-implementation specific commands

In the following, typical runner-commands are listed.

Running Java-FIT-Tests

command.runner=java -cp "${classpath}" fit.FileRunner "${infile}" "${outfile}"

Running Perl-FIT-Tests

command.runner=perl -MTest::C2FIT -I${libdir} -e file_runner "${infile}" "${outfile}"

Of course, you need to have the Test::C2FIT module installed.

Running python-FIT-Tests

command.runner=python FitRunner.py "${infile}" "${outfile}"

Download

Size of the "executable" jar file is about 500k.
Latest version: guirunner.jar (Build 010; 2008-06-10)
Previous version: guirunner-004.jar (2007-03-11)
The source code is available at sourceforge.

Test Drive

Test drive is a package with wich you can explore the fit-tests and the gui runner. Test drive is a zip-file containing some tests, the java and the perl runner. Download it, download the guirunner, start the guirunner and open one of the configurations supplied.
You can download test drive here.

Changes

Following the contents of the Changes.txt file is listed (as of 2008-06-02):

Revision history for fit.GuiRunner

010  2008-06-10
    - Copy results to clipboard - the contents of the view is copied
      to the clipboard. The format is suitable for pasting into
      a spreadsheet application
    - MRU List of configurations
    - Configuration contains now a "runner working directory" setting.
      This may be specified either as absolute path, or relative path
      (relative to the configurtion file) or a variable reference,
      e.g. ${infiledir} - directory of the input file.
      Supported variables are: indir, outdir, infiledir, outfiledir

009  2008-06-06 
    - if sorting is on, vies does not resort on every single
      change, but the user has to press the "re-sort" button.
      This seems to be better, than the immediate resort of
      the 008 build, as selected entries cannot disappear of the 
      visible part of the entries in view.
    - new column "timestamp of last run"
    - cell padding in the view
    - column titles are localisable, currently localised for
      german

008  2008-06-01 Martin Busik
    - quite a lot of new features and usability improvements
    - Managing tests: create new test, delete test, rename/move test
    - Running tests: run single, run marked, run all
    - GuiRunner can be also used as a "directory runner" from
      the command line (java -jar guirunner.jar -cli <confname>
    - colored cells with correct, wrong and exceptions numers,
      fit-like colors, if the numbers differ from 0
    - sorting of the view allowed, accessible via click on the
      row heading. Multi-Col sort possible (press CTRL while
      clicking)
    - "System information" MessageBox
    - Default button set in all dialogs
    - ESC key set for all dialogs
    - new columns:
        mark - for marking of rows ("run marked")
        folder - relative path name to the test "input directory"
    - elapsed-column right aligned
    - code cleanup


004  2007-03-11 Martin Busik
    - fixed: wrong command line handling during first startup
    - no action on first startup
    
003  2007-03-09 Martin Busik
    - fixed: preference file gets overwritten during startup
    - calls to setLocationRelativeTo() now after pack()
      in order to get the position really centered
    - L&F from JGoodies (www.jgoodies.com)

002  2007-02-XX Martin Busik
    - version number in about box
    - dialog for configuration settings

0.01 2007-01-01 Martin Busik
    - initial revision

Miscellaneous

Command line options

GuiRunner can be used as a command-line tool for running fit-tests. The same configuration file is used, as in the gui.

GuiRunner [-cli] [confname]
 -cli  no gui, just run and show summary
 confname filename of the configuration.
 (default: guirunner.conf)