harness(1)

SYNOPSIS
harness

DESCRIPTION
Harness is a GUI based test harness for packet shell scripts. Its purpose is to provide a convenient, and visual method for a developer to run a collection of tests.

When harness is invoked it pops up with a scrolling text region, with a variety of controls along the bottom. The scrolling text region contains a description of tests, and their current status. By convention, harness assumes all files ending in ".pst" in the current directory are packet shell tests.

The suffix after the test's description can be blank, an '*', 'Pass' or 'Fail - message'. No suffix indicates the test is not currently able to be run, due to insufficient configuration information. When a test is fully configured, but has not been run the suffix is '*'. Finally, when a test is run either 'Pass' or 'Fail' is added to indicate the test's outcome. In addition to 'Fail' a short few words from the test are displayed indicating something about the nature of the failure.

The user can drive a series of tests by using the controls across the bottom. On the far right, a configuration file may be specified. When a new name is entered, followed by a carriage return, the indicated file is loaded as a configuration file.

Pressing the Save Cfg button causes the current configuration values to be saved into a file. The Mod Cfg button allows configuration parameters to be added or modified. (Presently configuration parameters may not be deleted.) A pop-up menu provides this. Somewhere in the pop-up menu is an entry box entitled New variable. When a string is entered, followed by a return, a new variable is created, and the pop-up menu is modified to display the new variable.

The Update button provides a way to clear all run status and verify correct configuration for all the tests. This will also notice if additional tests have been created in harness's current directory.

CONFIGURATION FILE
A configuration file contains a series of lines, with one configuration variable declared on that line. The line begins with the name of the configuration parameter. Any combination of blanks or tabs separate the parameter name from the value. The value must not contain white spaces and is terminated by white space or and end-of-line. Any subsequent text is ignored.

Each of these configuration variables is available in the global tcl array named configTable. The index into the array is the name of the variable.

WRITING TESTS FOR HARNESS
Any packet shell test can easily be used with the harness if the test is constructed to meet several requirements.

All code must be declared inside Tcl procedures.

All scripts must have a t_info procedure. It must return a short string describing the test.

All tests must have a t_req procedure which checks that all requirements for running this test have been satisfied. Normally this means checking that all configuration variables are set in configTable. Returning non-zero implies configuration is correct. t_req should not create any state which needs to be cleaned up afterward, since calling t_req could be the only call ever made into a test.

All tests must have a t_run procedure. This procedure must run the actual test. It must return an empty string if the test passes, otherwise it must return a string.

All tests must define a procedure t_cleanup which guarantees that all variables and connections which might interfere with subsequent tests is destroyed. The t_cleanup routine is called after t_run only.

CHECKING CONFIGURATION
Below is a piece of sample code which demonstrates how to correctly test for a configuration variable in a t_req.
	proc t_req {
		global configTable
		foreach {i} {H1IP H2IP} {
			if {[array names configTable $i] == ""} {
				return 0
			}
		}
		return 1
	}

SEE ALSO
xpsh(1), tcl(1), tk(3).