.\"  $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH ADETEST 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
adetest \- a test harness
.br
.ne 5
.SH SYNOPSIS
.B adetest
\*[ade_standard_synopsis_component]
[
.B \-\-args\-are\-generators
]
[
.B \-g
|
.B \-\-generate
] 
[
.B \-t
|
.B \-\-test
] 
[
.B \-r
|
.B \-\-run
] 
[
.B \-k
|
.B \-\-keep\-output\-files
] 
.\" [
.\" .B \-m
.\" .I cmd
.\" |
.\" .B \-\-make=\fIcmd\fR
.\" ] 
.I testcmd \fR...
.br
.ne 5
.SH DESCRIPTION
.B Adetest
is a test harness.
.PP
A test consists of a program or program 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
.B adetest
is invoked from a Makefile in a ADE-based module,
and in this context configuration is beyond the scope
of this manual page. 
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP
.B \-\-args\-are\-generators
Instead of interpreting arguments as tests to execute, they will be interpreted as scripts 
whose standard output lists the tests to execute. 
.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\-output\-files
Prevents the usual deletion of the sandpit when the test completes. 
.TP 
.B \-r\fR, \fB\-\-run
Run the test without capturing its output, but do not compare
with the reference file.
.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.
.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.
.TP
.B ./tmp/adetest.\fIpid\fB.sandpit-\fItestname
The sandpit.
.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.
.TP
.B MAKE
Set to the path of the
.B make\fR(1)
command.
.TP 
.B PATH\fR,\fB LD_LIBRARY_PATH\fR,\fB PERL5LIB
Set to ensure that commands, libraries and Perl libraries from the module's
sources are found before any installed elsewhere.
.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 -e '#!/bin/bash\\\\ntrue' > 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 STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B adetest\fR.
.br
.ne 5
.SH SEE ALSO
adegmt(1), sed(1), make(1), ade-config(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
\*[ade_standard_copyright_component]