runtest is the executable test driver for DejaGnu. You can
specify two kinds of things on the
runtest command line: command
line options, and Tcl variables for the test scripts. The options are
listed alphabetically below. You can control the defaults for all
runtest options; see section Defaults for
runtest returns an exit code of
1 if any test
has an unexpected result; otherwise (if all tests pass or fail as
expected) it returns
0 as the exit code.
runtest flags the outcome of each test as one of these cases.
(See section A POSIX conforming test framework, for a discussion of
how POSIX specifies the meanings of these cases.)
FAIL. You can also use this outcome in dummy "tests" that note explicitly the absence of a real test case for a particular property.
runtest may also display the following messages:
UNRESOLVEDinstead, as appropriate.)
This is the full set of command line options that
runtest --tool tool [ testfile ... ] [ tclvar=value... ] [ --all ] [ --connect type ] [ --debug ] [ --help ] [ --mail "name ..." ] [ --name string ] [ --noreboot ] [ --outdir path ] [ --objdir path ] [ --srcdir path ] [ --strace n ] [ --name name ] [ --target string ] [ --host string ] [ --Dn ] [ -v | --verbose ] [ -V | -version ]
runtestcommand line runs tests from all test subdirectories whose names match `gcc.*', and uses one of the initialization modules named `config/*-gcc.exp'. To specify the name of the compiler (perhaps as an alternative path to what
runtestwould use by default), use `GCC=binname' on the
runtestruns all tests available in the test source directory, but you can restrict it to particular test files by listing their names. testfile may not include path information; use plain filenames. Only names that end with `.exp', `.C', `.cc', `.c', or `.s' are accepted as valid testfile arguments. File names ending with `.exp' are
expectscripts; this is the most general case for specifying particular DejaGnu tests. For compiler or assembler tests, which often use a single `.exp' script covering many different source files, you can further restrict the tests by listing particular source files to compile.
makefor environment variables. For example, `runtest GDB=gdb.old' defines a variable called `GDB'; when your scripts refer to `$GDB' in this run, they use the value `gdb.old'. The default Tcl variables used for most tools are defined in the main DejaGnu
Makefile; their values are captured in the `site.exp' file. See section Configuration dependent values.
runtestshows only the output of tests that produce unexpected results; that is, tests with status `FAIL' (unexpected failure), `XPASS' (unexpected success), or `ERROR' (a severe error in the test case itself). Specify `--all' to see output for tests with status `PASS' (success, as expected) `XFAIL' (failure, as expected), or `WARNING' (minor error in the test case itself).
--baud baud rate
tip, use a separate initialization file instead of this value.)
runtest. For example, use `--connect' to change the program used to connect to a "bare board" boot monitor. The choices for type in the DejaGnu 1.0 distribution are `rlogin', `telnet', `rsh', `tip', `kermit', and `mondfe'. The default for this option depends on the configuration (see section Remote targets supported). The default is chosen to be the most convenient communication method available, but often other alternatives work as well; you may find it useful to try alternative connect methods if you suspect a communication problem with your testing target.
expectinternal debugging output. Debugging output is displayed as part of the
runtestoutput, and logged to a file called `dbg.log'. The extra debugging output does not appear on standard output, unless the verbose level is greater than 2 (for instance, to see debug output immediately, specify `--debug -v -v'). The debugging output shows all attempts at matching the test output of the tool with the scripted patterns describing expected output. The output generated with `--strace' also goes into `dbg.log'.
runtestoptions, then exits (even if you also specify other options).
--mail "name1 name2 ..."
tipconnections require names from a serial line configuration file (usually called `/etc/remote'), while
telnetconnections use IP hostnames.
runtestinitializes. Usually, when running tests on a separate target board, it is safer to reboot the target to be certain of its state. However, when developing test scripts, this option can save a lot of time.
runtest. This option affects only the summary and the detailed log files `tool.sum' and `tool.log'. The DejaGnu debug log `dbg.log' always appears (when requested) in the local directory.
expectshell stops at a breakpoint as soon as DejaGnu invokes it. If you specify `-D0', DejaGnu starts as usual, but you can enter the debugger by sending an interrupt (e.g. by typing C-c).
runtestlooks in this directory for any subdirectory whose name begins with the toolname (specified with `--tool'). For instance, with `--tool gdb',
runtestuses tests in subdirectories `gdb.*' (with the usual shell-like filename expansion). If you do not use `--srcdir',
runtestlooks for test directories under the current working directory.
expect, to n levels deep. By adjusting the level, you can control the extent to which your output expands multi-level Tcl statements. This allows you to ignore some levels of
ifstatements. Each procedure call or control structure counts as one "level". The output is recorded in the same file, `dbg.log', used for output from `--debug'.
configure. This option changes the configuration
runtestuses for the default tool names, and other setup information. See section `Using
configure' in Cygnus configure, for details about
configure. Use this option to override the default string recorded by your configuration's choice of host. This choice does not change how anything is actually configured; it affects only DejaGnu procedures that compare the host string with particular values. The procedures
setup_xfailare affected by `--host'.
NFS), this is the network name for the target itself. (name is not the configuration string you specify as a target with
configure; the `--name' option names a particular target, rather than describing a class of targets.) For targets that connect in other ways, the meaning of the name string depends on the connection method. See section Remote targets supported.
expectand Tcl, and exits without running any tests.