.\"  $HeadURL$ $LastChangedRevision$
.\"
.TH ADETEST 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
adetest \- A test harness
.br
.ne 5
.SH SYNOPSIS
.B adetest
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
] 
[
.B \-g
|
.B \-\-generate
] [
.B \-t
|
.B \-\-test
] [
.B \-r
|
.B \-\-run
] [
.B \-f
|
.B \-\-force
] [
.B \-k
|
.B \-\-keep\-sandpits
] [
.B \-R
|
.B \-\-recursive\-verbosity
] 
[
.B \-m
.I cmd
|
.B \-\-make=\fIcmd\fR
] 
.I testcmd \fR...
.br
.ne 5
.SH DESCRIPTION
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of 
.B adetest\fR.
.PP 
.B Adetest
is a test harness.
.PP
A test consists of a program or sources that when 
run successfully may produce some output and
return a zero exit status. 
.B Adetest
will invoke 
.B make\fR(1)
to make the test before it executes it. 
.PP
Normally, while the test is being developed, 
.B adetest
should be used in \(oqrun' mode. When the output
and exit code are correct then run
.B adetest
in \(oqgenerate' mode to generate the reference
file. Thereafter run 
.B adetest
in \(oqtest' mode (the default) to run the test,
check the output matches the reference file, and 
that the test still returns a zero exit status.
.br
.ne 5
.SH CONFIGURATION
Normally
.N adetest
is invoked from a Makefile in a ADE-based module,
and in this context configuration is beyond the scope
of this manual page. Please refer to 
.B adeintro\fR(1),
where complete details of the whole development
process are given.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B adetest
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP 
.B \-f\fR, \fB\-\-force
Forces 
.B adetest
to do the following things which it would not normally do:
.RS 25
.IP \(bu 5
remake test programs when the test program is not in ./bin
.IP \(bu 5
generate reference files when the test program is not in ./bin.
.RE
.TP
.B \-g\fR, \fB\-\-generate
Generates the reference files
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-k\fR, \fB\-\-keep\-sandpits
Prevents the usual deletion of the sandpit when the test completes. 
.TP
.B \-m \fIcmd\fR, \fB\-\-make=\fIcmd\fR
Sets the path of the 
.B make\fR(1)
command to 
.I cmd\fR.
This option is typically only used by the ADE makefiles.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B adetest
uses.
.TP 
.B \-r\fR, \fB\-\-run
Run the test without capturing its output, but do not compare
with the reference file.
.TP
.B \-R\fR, \fB\-\-recursive\-verbosity
.B adetest 
will set the environment variable 
.B ADE_MSG_VERBOSELEVEL
before invoking the test. This may prove useful when running
with 
.B \-r\fR.
.TP 
.B \-t\fR, \fB\-\-test
Run the test, check the exit status is zero, and check the resulting 
output matches the reference file. This is the default behaviour.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B adetest
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 25
.B ./bin
directory for tests and/or their sources
.TP
.B ./ref
directory for test reference files
.TP
.B ./out
directory for test outputs, the files in this
directory can be considered temporary.
.B ./tmp/adetest.\fIpid\fB.sandpit-\fItestname
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
.B ADETEST_MODROOT
.B Adetest
sets this to point at the base of the module before
invoking the test. This is to help the test find any
data files it may need, and to allow it to strip
out (typically with 
.B sed\fR(1))
any output which varies depending on where the module
is located in the filesystem hierarchy.
See
.B adeintro\fR(1)
for more information on the module layout.
.TP 25 
.B PATH
.B Adetest
changes
.B PATH
so that the test will find the program being tested in
.B ../bin 
before the one anywhere else. See
.B adeintro\fR(1)
for more information on the module layout.
.TP
.B TMPDIR
.B Adetest
sets this variable to allow the program under test to
keep its private temporary files inside the sandpit's
purpose-built 'tmp' directory.
.TP
.B ADE_MSG_VERBOSELEVEL
.B Adetest 
sets this variable in correspondence with the 
.B \-d 
or 
.B \-v 
options with which it itself was invoked, before running
the test. 
.br
.ne 5
.SH EXAMPLES
The following commands will create and run a very simple
test:
.IP
.nf
.fam C
.B mkdir bin out ref tmp
.B echo '#!/bin/sh' > bin/simple.sh
.B echo 'true' >> bin/simple.sh
.B adetest -g -v bin/simple
.B adetest -v bin/simple
.fam T
.fi
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH SEE ALSO
adeintro(1), adegmt(1), sed(1), make(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2002-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.