NAME

USAGE

DESCRIPTION

Aht is a Perl script meant to support unit tests during development, and for 
acceptance and regression testing of the Hitomi FITS tools (Ftools). 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 Hitomi 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 Hitomi 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