NAME

USAGE

DESCRIPTION

aht is a Perl script meant to support unit tests during development,
and for acceptance and regression testing of FITS tools (Ftools).
It was originally developed for the Hitomi mission. The 'aht' Perl
script reads a "manifest" text file that is expected to reside in the
test current working directory.  This aht manifest file is a Perl
hash statement of key => values that is initialized by aht in the
current working directory with the fixed name: ./aht_manifest.pl.
It is evaluated by aht to conduct the indicated test and some options
that update/reset the contents of the manifest file.  The manifest
may also be edited (carefully) to customize the unit test.

The Ftool developer establishes test input(s) and runs the tool
application manually to produce output. The manifest text file,
as noted above, is implemented as a Perl hash statement, and
indicates the nature and specifics of a unit test.  The test Perl
script (aht) executes the Ftool application as a child process,
once expected output has been established ('aht -u' copies successful
output to the special sub-directory './expected_output/').  All
Ftool applications printout to stdout and stderr are redirected by
aht to text log files. The user may interrupt an aht test via
Control-C (interrupt signal).  Aht monitors child process signals
to determine if the Ftool application completes execution
successfully or fails, and reports its exit value. Upon a successful
exit value, aht compares/validates output with what is expected via
the standard Ftool 'ftdiff'.  On unsuccessful exit value, aht
searches logs for keywords (described in the manifest) and reports
accordingly. Should 'ftdiff' find differences in the final latest
output test file with the expected file content, the total number
of differences (integer count) is placed in the exit status value
of the aht script. This allows aht to be run via yet another level
script (such as 'hmake run-test'), with some measure of error handling.

The developer must specify the name of the tool and the expected exit 
status. The update mode uses the File/Directory Convention to locate and 
copy all current inputs and outputs to their reference locations.  

ARGUMENTS

[ -a | --aa ]: Recurse to run all unit tests found below the current directory

[ -c=text | --command=text]: Execute command specified by text in lieu of task
                             (for debugging)

[ -d=text | --descript=text]: Description of unit test (required in task name
                              given)

[ -e | --env ]: Display the environment as immediately prior to running the task

[ -h | --help ]: Display help screen

[ -i | --ignore ]: Ignore differences in non-FITS output files; this is used
                   for creating or updating unit tests in which differences in
                   log files are unavoidable

[ -m | --manifest ]: Display the manifest data for test

[ -n | --noop ]: Print test commands to screen - do not run test

[ -s=status | --status=status ]: Expected status of a new or updated test
                                 (required if task name is given)

[-t=tol | --tolerance=tol ]: Absolute acceptance tolerance of floating point
                             values in FITS and parameter files

[-r=reltol | --reltol=reltol ]: Relative acceptance tolerance of floating point
                                values in FITS and parameter files

[ -u | --update ]: Update the unit test (required if task name is given)

[ -v=valopt | --valgrind=valopt ]: Use valgrind to run test with memory checks;
                                  valopt are options passed to valgrind

EXAMPLES

1. Display help screen.
   
          aht -h
       

2. Create a new for ahdemo task.  This command assumes that an input
            directory exists containing the single input file: in.fits.  The
            task creates the output file, out.fits, in the output directory.
            The task is expected to complete successfully (i.e. exit status = 0).
   
         aht -u -s=0 -d="an ahdemo unit test!" ahdemo in.fits out.fits
       

3. Run the unit test in the current directory.  This command only works
            when the active directory contains the aht manifest file and test
            tarball.
   
         aht
       

4. Navigate all directories recursively and run all aht unit tests found.
   
         aht -a
       

5. Update unit test by copying output files into the expected output.
   
         aht -u
       

SEE ALSO:

LAST MODIFIED