faux/lub/test/test.c

/***********************************************************************
**
**	Filename	: test.c
**	Project		: Unit Test
**	Subsystem	: 
**	Module		: Basic routines for performing a Unit Test
**	Document	: 
**
*************************************************************************
**
**	Brief Description
**	=================
**
**	Functions to provide a nice, consistent Unit Test infrastructure.
**	
**
*************************************************************************
**
**  Change History
**  --------------
**
** 20-Jun-2005    Graeme McKerrell     Populated lub_test_stop_here() t ensure it is reached when a
**                                                                optimising compiler is used.
** 7-Dec-2004    Graeme McKerrell     Updated to use the "lub_test_" prefix 
**                                    rather than "unittest_"
**  4  Mar 2004  Graeme McKerrell     Ported for use in Garibaldi
**  4  Oct 2002  Graeme McKerrell     updated to use central interface
**                                    definition
**  18-Mar-2002	 Graeme McKerrell     Added unitest_stop_here() support
**  16-Mar-2002	 Graeme McKerrell     LINTed...
**  14 Nov 2000  Brett B. Bonner      created
**
*************************************************************************
**
**  Copyright (C) 3Com Corporation. All Rights Reserved.
**
\************************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdarg.h>
#include <stdlib.h>
/*lint -esym(534,vsprintf) */
/*lint -esym(632,va_list,__va_list) */
/*lint -esym(633,va_list,__gnuc_va_list) */
#include "lub/test.h"



/* Where to direct output (bitmasks) */
#define LUB_TEST_LOGTOFILE   0x1
#define LUB_TEST_LOGTOSTDOUT 0x2

/* Termination Mode */
typedef enum {
  ContinueOnFail,
  StopOnFail
} TerminationMode;

/* local variables */
static char unitTestName[80];
static char seqDescr[80];
static FILE *logp=NULL;
static lub_test_verbosity_t verbosity = LUB_TEST_NORMAL;
static int outputTo;
static lub_test_status_t unitTestStatus=LUB_TEST_PASS;
static int seqNum=0;
static int testNum=0;
static int failureCount=0;
static int testCount=0;
static TerminationMode termMode=ContinueOnFail;

/* local functions */
static void testLogNoIndent(lub_test_verbosity_t level, const char *format, ...);
static void printUsage(void);

/* definitions */
#define LOGGING_TO_FILE ((outputTo & LUB_TEST_LOGTOFILE) != 0)
#define LOGGING_TO_STDOUT ((outputTo & LUB_TEST_LOGTOSTDOUT) != 0)


/*
 * This is provided as a debug aid.
 */
void 
lub_test_stop_here(void)
{
  /* If any test fails, the unit test fails */
  unitTestStatus = LUB_TEST_FAIL;
  failureCount++;
  if (termMode == StopOnFail) {
    lub_test_end();
    exit(1);
  }
}

static lub_test_status_t
checkStatus(lub_test_status_t value)
{
    /* Test number gets incremented automatically... */
    testNum++;
    testCount++; /* update total number of tests performed */

    if(LUB_TEST_FAIL == value)
    {
        lub_test_stop_here();
    }
    return value;
}

/*******************************************************
* unit-test-level functions
********************************************************/
/* NAME:    unitTestLog
   PURPOSE: Log output to file and/or stdout, verbosity-filtered
   ARGS:    level - priority of this message.
                    Will be logged only if priority equals or exceeds
                    the current lub_test_verbosity_t level.
            format, args - printf-style format and parameters
   RETURN:  none
*/
static void 
unitTestLog(lub_test_verbosity_t level, const char *format, ...)
{
    va_list args;
    char string[320]; /* ought to be big enough; that's 4 lines */

    /* Turn format,args into a string */
    va_start(args, format);
    vsprintf(string, format, args);
    va_end(args);

    /* output to selected destination if lub_test_verbosity_t equals or exceeds
     current setting. */ 
    if (level <= verbosity) 
    {
        if (LOGGING_TO_FILE) 
        {
            if (NULL != logp)
            {
                fprintf(logp, "%s\n", string);
            }
            else
            {
                fprintf(stderr, "ERROR: Trying to log to file, but no logfile is open!\n");
            }
        }
        if (LOGGING_TO_STDOUT) 
        {
            fprintf(stdout, "%s\n", string);
        }
    }
}

/* NAME:    TestStartLog
   PURPOSE: Sets up logging destination(s) and opens logfile.
   ARGS:    whereToLog   - where output gets directed to
                           Bitmask of lub_test_LOGTOFILE, lub_test_LOGTOSTDOUT
            logfile      - file name to open.
                           Use NULL if not logging to file.
   RETURN:  BOOL_FALSE == failure
            BOOL_TRUE  == success
*/
static int TestStartLog(int whereToLog, const char *logFile) 
{
    bool_t status = BOOL_TRUE;
    /* Where are we logging? */
    outputTo = whereToLog;
  
    /* open log file */
    if (LOGGING_TO_FILE && (strlen(logFile) < 1)) 
    {
        status = BOOL_FALSE;
        fprintf(stderr, "ERROR: No logfile name specified.\n");  
    }
    if (LOGGING_TO_FILE && status) 
    {
        if ( (logp = fopen(logFile, "w")) == NULL ) 
        {
            status = BOOL_FALSE;
            fprintf(stderr, 
                    "ERROR: could not open log file '%s'.\n",
                    logFile);
        }
    }
    return status;
}

/* NAME:    lub_test_begin
   PURPOSE: Starts unit test.  
   ARGS:    format,args  - Specification of unit test name
   RETURN:  none
*/
void 
lub_test_begin(const char *name, ...) 
{
    va_list args;

    /* Process varargs list into unit test name string */
    va_start(args, name);
    vsprintf(unitTestName, name, args);
    va_end(args);
    unitTestLog(LUB_TEST_NORMAL, "BEGIN: Testing '%s'.", unitTestName);

    /* reset counters */
    seqNum=testNum=testCount=failureCount=0;
} 

/* NAME:    lub_test_get_status
   PURPOSE: Reports current unit test status
   ARGS:    none
   RETURN:  Status code - TESTPASS/TESTFAIL
*/
lub_test_status_t
lub_test_get_status(void)
{
    return unitTestStatus;
}

/* NAME:    lub_test_failure_count
   PURPOSE: Reports current number of test failures
   ARGS:    none
   RETURN:  Count of failures
*/
int 
lub_test_failure_count(void)
{
    return failureCount;
}

/* NAME:    lub_test_end
   PURPOSE: Ends test.  Closes log file.
   ARGS:    none
   RETURN:  none
*/
void 
lub_test_end(void)
{
    char result[40];

    if (unitTestStatus == LUB_TEST_PASS) 
    {
        sprintf(result, "PASSED (%d tests)",testCount);
    } 
    else 
    {
        if (failureCount == 1)
        {
            sprintf(result, "FAILED (%d failure, %d tests)", 
                    failureCount, testCount);
        }
        else 
        {
              sprintf(result, "FAILED (%d failures, %d tests)", 
                      failureCount, testCount);
        }
    }
    if ((termMode == ContinueOnFail) ||
        (unitTestStatus == LUB_TEST_PASS)) 
    {
        /* ran to end - either due to continue-on-fail, or because
           everything passed */ 
        unitTestLog(LUB_TEST_TERSE, "END: Test '%s' %s.\n",unitTestName, result);
    } 
    else 
    { 
        /* stopped on first failure */
        unitTestLog(LUB_TEST_TERSE, "END: Test '%s': STOPPED AT FIRST FAILURE.\n",unitTestName);    
    }
    if (LOGGING_TO_FILE) 
    {
        fclose(logp);
    }
}

/* NAME:    printUsage
   PURPOSE: Prints usage message
   ARGS:    none
   RETURN:  none
*/
static void 
printUsage(void) 
{
    printf("Usage:\n");
    printf("-terse, -normal, -verbose    : set lub_test_verbosity_t level (default: normal)\n");
    printf("-stoponfail, -continueonfail : set behavior upon failure (default: continue)\n");
    printf("-logfile [FILENAME]          : log to FILENAME (default: 'test.log')\n"); 
    printf("-nologfile                   : disable logging to file \n");
    printf("-stdout, -nostdout           : enable/disable logging to STDOUT\n");
    printf("-usage, -help                : print these options and exit\n");
    printf("\nAll arguments are optional.  Defaults are equivalent to: \n");
    printf("  -normal -continueonfail -logfile test.log -stdout\n");
}

/* NAME:    lub_test_parse_command_line
   PURPOSE: Parses command-line arguments & sets unit test options.
   ARGS:    argc, argv - as passed to main()
   RETURN:  none (will exit if there is an error)
*/
void 
lub_test_parse_command_line(int argc, const char * const *argv) 
{
    bool_t status=BOOL_TRUE;
    int logDest=0;
    static char defaultFile[] = "test.log"; 
    char *logFile;
    bool_t logFileAllocatedFromHeap=BOOL_FALSE;

    /* variables used to detect conflicting options */
    int verbset=0;
    int failset=0;
    int logfset=0;
    int stdset=0;

    /* Set logFile to defaultFile so there is always a valid filename.
       Also set logging destination to both STDOUT and FILE.
       These will be changed later if user specifies something else. */
    logFile = defaultFile;
    logDest = (LUB_TEST_LOGTOFILE | LUB_TEST_LOGTOSTDOUT);

    /* Loop through the command line arguments.  */
    while (--argc > 0) 
    {
        /* Usage/Help */
        if ((strstr(argv[argc], "-usage") != NULL) ||
            (strstr(argv[argc], "-help") != NULL)) 
        {
            printUsage();
            exit (0);
        }
        /* lub_test_verbosity_t Levels */
        else if (strstr(argv[argc], "-terse") != NULL) 
        { 
            verbosity = LUB_TEST_TERSE; verbset++;
        }
        else if (strstr(argv[argc], "-normal") != NULL) 
        {
            verbosity = LUB_TEST_NORMAL; verbset++;
        }
        else if (strstr(argv[argc], "-verbose") != NULL) 
        {
            verbosity = LUB_TEST_VERBOSE; verbset++;
        }
        /* Failure behavior */
        else if (strstr(argv[argc], "-stoponfail") != NULL) 
        {
            termMode = StopOnFail; failset++;
        }
        else if (strstr(argv[argc], "-continueonfail") != NULL) 
        {
            termMode = ContinueOnFail; failset++;
        }
        /* Log file options */
        else if (strstr(argv[argc], "-logfile") != NULL) 
        {
            logDest |= LUB_TEST_LOGTOFILE;
            /* Was a log file name specified?  
               We assume it's a file name if it doesn't start with '-' */
            if (strstr(argv[argc+1], "-") != argv[argc+1]) 
            {
                /* Yes, got a filename */
                logFile = (char *)malloc(strlen(argv[argc+1])+1);

                if (NULL == logFile) 
                {
                    status = BOOL_FALSE;
                    fprintf(stderr, "unitTestParseCL: ERROR: Memory allocation problem.\n");
                }
                else 
                {
                    /* all is well, go ahead and copy the string */
                    strcpy(logFile, argv[argc+1]);
                }
                logFileAllocatedFromHeap=BOOL_TRUE;
            }
            logfset++;
        }
        else if (strstr(argv[argc], "-nologfile") != NULL) 
        {
            logDest &= ~LUB_TEST_LOGTOFILE;
            logfset++;
        }
        /* Stdout options */
        else if (strstr(argv[argc], "-stdout") != NULL) 
        {
            logDest |= LUB_TEST_LOGTOSTDOUT;
            stdset++;
        }
        else if (strstr(argv[argc], "-nostdout") != NULL) 
        {
            logDest &= ~LUB_TEST_LOGTOSTDOUT;
            stdset++;
        }
        /* Unhandled arguments */
        else 
        {
            /* If the next argument down in the list is '-logfile', then
               this is the logfile name; don't complain. */
            if (strstr(argv[argc-1], "-logfile") == NULL) 
            {
                /* This is an unrecognized option. 
                   Don't bother setting status and forcing an exit; just ignore it. */
                fprintf(stderr,"Unrecognized argument: '%s', ignoring it...\n",argv[argc]);
            }
        }
    }
    /* See if there is a logging destination */
    if (logDest == 0) 
    {
        fprintf(stderr, "WARNING: No logging is enabled to either stdout or a logfile; expect no output.\n");
    }
    /* Make sure there were no conflicting options */
    if (verbset > 1) 
    {
        fprintf(stderr,"ERROR: conflicting lub_test_verbosity_t options specified.\n");
        fprintf(stderr,"       Specify only ONE of -terse, -normal, -verbose\n");
        status = BOOL_FALSE;
    }
    if (failset > 1) 
    {
        fprintf(stderr,"ERROR: conflicting Failure Mode options specified.\n");
        fprintf(stderr,"       Specify only ONE of -stoponfail, -continueonfail\n");
        status = BOOL_FALSE;
    }
    if (logfset > 1) 
    {
        fprintf(stderr,"ERROR: conflicting Logfile options specified.\n");
        fprintf(stderr,"       Specify only ONE of -logfile, -nologfile\n");
        status = BOOL_FALSE;
    }
    if (stdset > 1) 
    {
        fprintf(stderr,"ERROR: conflicting Stdout options specified.\n");
        fprintf(stderr,"       Specify only ONE of -stdout, -nostdout\n");
        status = BOOL_FALSE;
    }

    /* Set up log file, if things are OK so far */
    if (status && !TestStartLog(logDest, logFile))
    {
          status = BOOL_FALSE;
    }
    if (logFileAllocatedFromHeap) 
    {
        /*lint -e673 Possibly inappropriate deallocation (free) for 'static' data */
        free(logFile);
        /*lint +e673 */
    }
    if (BOOL_FALSE == status) 
    {
        fprintf(stderr, "Something bad has occurred.  Aborting...\n");
        exit(1);
    }

}

/*******************************************************
* sequence level functions
********************************************************/

/* NAME:    lub_test_seq_begin
   PURPOSE: Starts a new test sequence.
   ARGS:    num - sequence number, must be different than last one
            format, args - printf-style name for the sequence
   RETURN:  none
*/
void 
lub_test_seq_begin(int num, const char *seqName, ...)
{
    va_list args;

    /* Get sequence name */
    va_start(args, seqName);
    vsprintf(seqDescr, seqName, args);
    va_end(args);

    /* Start new sequence number */
    if (num == seqNum) 
    {
        seqNum++;
        unitTestLog(LUB_TEST_TERSE, "seq_start: duplicate sequence number.  Using next available sequence number (%d).\n", seqNum);
    } 
    else 
    {
        seqNum = num;
    }

    /* Reset test number */
    testNum = 0;

    /* Log beginning of sequence */
    lub_test_seq_log(LUB_TEST_NORMAL, "*** Sequence '%s' begins ***", seqDescr);
}

/* NAME:    lub_test_seq_end
   PURPOSE: Ends current test sequence
   ARGS:    none
   RETURN:  none
*/
void 
lub_test_seq_end(void)
{
    lub_test_seq_log(LUB_TEST_NORMAL, 
                     "----------------------------------------"
                     "--------------------");
}

/* NAME:    lub_test_seq_log
   PURPOSE: Log output to file and/or stdout, verbosity-filtered and
            formatted as a "sequence-level" message
   ARGS:    level - priority of this message.
                    Will be logged only if priority equals or exceeds
                    the current lub_test_verbosity_t level.
            format, args - printf-style format and parameters
   RETURN:  none
*/
void
lub_test_seq_log(lub_test_verbosity_t level, const char *format, ...)
{
    va_list args;
    char string[160];

    /* Turn format,args into a string */
    va_start(args, format);
    vsprintf(string, format, args);
    va_end(args);

    unitTestLog(level, "%03d     :        %s", seqNum, string);
}

/*******************************************************
* test level functions
********************************************************/

/* NAME:    lub_test_check
   PURPOSE: True/False test of an expression.  If True, test passes.
   ARGS:    expr - expression to evaluate.
            format, args - Printf-style format/parameters describing test.  
   RETURN:  Status code - PASS or FAIL
*/
lub_test_status_t
lub_test_check(bool_t expr, const char *testName, ...)
{
    va_list args;
    char testDescr[80];
    lub_test_status_t testStatus;
    char result[5];
    lub_test_verbosity_t verb;

    /* evaluate expression */
    testStatus = expr ? LUB_TEST_PASS : LUB_TEST_FAIL;

    /* extract description as a string */
    va_start(args, testName);
    vsprintf(testDescr, testName, args);
    va_end(args);

    /* log results */
    if (testStatus == LUB_TEST_PASS) 
    {
        verb=LUB_TEST_NORMAL;
        sprintf(result, "pass");
    } 
    else 
    {
        verb=LUB_TEST_TERSE;
        sprintf(result, "FAIL");
    }
    testLogNoIndent(verb, "[%s] %s", result, testDescr);

    return checkStatus(testStatus);
}

/* NAME:    lub_test_check_int
   PURPOSE: Checks whether an integer equals its expected value.
   ARGS:    expect - expected value.
            actual - value being checked.
            format, args - Printf-style format/parameters describing test.
   RETURN:  Status code - PASS or FAIL
*/
lub_test_status_t
lub_test_check_int(int expect, int actual, const char *testName, ... )
{
    va_list args;
    char testDescr[80];
    lub_test_status_t testStatus;
    char result[5];
    char eqne[3];
    lub_test_verbosity_t verb;

    /* evaluate expression */
    testStatus = (expect == actual) ? LUB_TEST_PASS : LUB_TEST_FAIL;

    /* extract description as a string */
    va_start(args, testName);
    vsprintf(testDescr, testName, args);
    va_end(args);

    /* log results */
    if (testStatus == LUB_TEST_PASS) 
    {
        sprintf(result, "pass");
        sprintf(eqne, "==");
        verb = LUB_TEST_NORMAL;
    } 
    else 
    {
        sprintf(result, "FAIL");
        sprintf(eqne, "!=");
        verb = LUB_TEST_TERSE;
    }
    testLogNoIndent(verb, "[%s] (%d%s%d) %s", 
                    result, actual, eqne, expect, testDescr);

    return checkStatus(testStatus);
}

/* NAME:    lub_test_check_float
   PURPOSE: Checks whether a float is within min/max limits.
   ARGS:    min    - minimum acceptable value.
            max    - maximum acceptable value.
            actual - value being checked.
            format, args - Printf-style format/parameters describing test.
   RETURN:  Status code - PASS or FAIL
*/
lub_test_status_t 
lub_test_check_float(double min, double max, double actual, 
                 const char *testName, ...)
{
    va_list args;
    char testDescr[80];
    lub_test_status_t testStatus;
    char result[5];
    char gteq[4], lteq[4];

    /* evaluate expression */
    testStatus = ((actual >= min) && (actual <= max)) ? LUB_TEST_PASS : LUB_TEST_FAIL;

    /* extract description as a string */
    va_start(args, testName);
    vsprintf(testDescr, testName, args);
    va_end(args);

    /* log results */
    if (testStatus == LUB_TEST_PASS) 
    {
        sprintf(result, "pass");
        sprintf(gteq, " <=");
        sprintf(lteq, " <=");
    }
    else 
    {
        sprintf(result, "FAIL");
        if (actual < min) 
        {
            sprintf(gteq, "!<=");
            sprintf(lteq, " <=");
        } 
        else 
        {
            sprintf(gteq, " <=");
            sprintf(lteq, "!<=");
        }
    }

    testLogNoIndent(LUB_TEST_NORMAL, "[%s] (%8f%s%8f%s%8f) %s", 
                    result, min, gteq, actual, lteq, max, testDescr);

    return checkStatus(testStatus);
}

/* NAME:    lub_test_log
   PURPOSE: Log output to file and/or stdout, verbosity-filtered and
            formatted as a "test-level" message
   ARGS:    level - priority of this message.
                    Will be logged only if priority equals or exceeds
                    the current lub_test_verbosity_t level.
            format, args - printf-style format and parameters
   RETURN:  none
*/
void
lub_test_log(lub_test_verbosity_t level, const char *format, ...)
{
    va_list args;
    char string[160];

    /* Turn format,args into a string */
    va_start(args, format);
    vsprintf(string, format, args);
    va_end(args);

    unitTestLog(level, "%03d-%04d:        %s", seqNum, testNum, string);
}

/* NAME:    testLogNoIndent
   PURPOSE: Log output to file and/or stdout, verbosity-filtered and
            formatted as a "test-level" message.  
            This "internal" version does not indent, so that the
            pass/fail column can be printed in the proper place.
   ARGS:    level - priority of this message.
                    Will be logged only if priority equals or exceeds
                    the current lub_test_verbosity_t level.
            format, args - printf-style format and parameters
   RETURN:  none
*/
static void testLogNoIndent(lub_test_verbosity_t level, const char *format, ...)
{
    va_list args;
    char string[160];

    /* Turn format,args into a string */
    va_start(args, format);
    vsprintf(string, format, args);
    va_end(args);

    unitTestLog(level, "%03d-%04d: %s", seqNum, testNum, string);
}