testrun.c

CUNIT

/*
 *  CUnit - A Unit testing framework library for C.
 *  Copyright (C) 2001  Anil Kumar
 *  Copyright (C) 2004  Anil Kumar, Jerry St.Clair
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library 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
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

/*
 *  Contains the Console Test Interface  implementation.
 *
 *  Created By     : Anil Kumar on ...(in month of Aug 2001)
 *  Last Modified  : 19/Aug/2001
 *  Comment        : Added initial registry/Suite/test framework implementation.
 *  Email          : [e-mail]
 *
 *  Last Modified  : 24/Aug/2001 by Anil Kumar
 *  Comment        : Changed Data structure from SLL to DLL for all linked lists.
 *  Email          : [e-mail]
 *
 *  Last Modified  : 25/Nov/2001 by Anil Kumar
 *  Comment        : Added failure notification for Suite Initialization failure condition.
 *  Email          : [e-mail]
 *
 *  Last Modified  : 5-Aug-2004 (JDS)
 *  Comment        : New interface, doxygen comments, moved add_failure on suite
 *                   initialization so called even if a callback is not registered,
 *                   moved CU_assertImplementation into TestRun.c, consolidated
 *                   all run summary info out of CU_TestRegistry into TestRun.c,
 *                   revised counting and reporting of run stats to cleanly
 *                   differentiate suite, test, and assertion failures.
 *  Email          : [e-mail]
 *
 *  Last Modified  : 1-Sep-2004 (JDS)
 *  Comment        : Modified CU_assertImplementation() and run_single_test() for
 *                   setjmp/longjmp mechanism of aborting test runs, add asserts in
 *                   CU_assertImplementation() to trap use outside a registered
 *                   test function during an active test run.
 *  Email          : [e-mail]
 *
 *  Last Modified  : 22-Sep-2004 (JDS)
 *  Comment        : Initial implementation of internal unit tests, added nFailureRecords
 *                   to CU_Run_Summary, added CU_get_n_failure_records(), removed
 *                   requirement for registry to be initialized in order to run
 *                   CU_run_suite() and CU_run_test().
 *  Email          : [e-mail]
 */

/** @file
 *  Test run management functions (implementation).
 */
/** @addtogroup Framework
 @{
*/

#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <stdio.h>
#include <setjmp.h>

#include "CUnit.h"
#include "MyMem.h"
#include "TestDB.h"
#include "TestRun.h"

static BOOL       f_bTestIsRunning = FALSE; /**< Flag for whether a test run is in progress */
static CU_pSuite  f_pCurSuite = NULL;       /**< Pointer to the suite currently being run. */
static CU_pTest   f_pCurTest  = NULL;       /**< Pointer to the test currently being run. */

/** CU_RunSummary to hold results of each test run. */
static CU_RunSummary f_run_summary = {0, 0, 0, 0, 0, 0, 0};
/** CU_pFailureRecord to hold head of failure record list of each test run. */
static CU_pFailureRecord f_failure_list = NULL;
/** Keeps track of end of f_run_summary list for message handlers. */
static CU_pFailureRecord f_last_failure = NULL;

/* Forward declarations of static functions. */
static void         clear_previous_results(CU_pRunSummary pRunSummary, CU_pFailureRecord* ppFailure);
static void         cleanup_failure_list(CU_pFailureRecord* ppFailure);
static CU_ErrorCode run_single_suite(CU_pSuite pSuite, CU_pRunSummary pRunSummary);
static CU_ErrorCode run_single_test(CU_pTest pTest, CU_pRunSummary pRunSummary);
static void         add_failure(CU_pFailureRecord* ppFailure, CU_pRunSummary pRunSummary,
                                unsigned int uiLineNumber, char szCondition[],
                                char szFileName[], CU_pSuite pSuite, CU_pTest pTest);

/** Pointer to the function to be called before running a test. */
static CU_TestStartMessageHandler        f_pTestStartMessageHandler = NULL;
/** Pointer to the function to be called after running a test. */
static CU_TestCompleteMessageHandler     f_pTestCompleteMessageHandler = NULL;
/** Pointer to the function to be called when all tests have been run. */
static CU_AllTestsCompleteMessageHandler f_pAllTestsCompleteMessageHandler = NULL;
/** Pointer to the function to be called if a suite initialization function returns an error. */
static CU_SuiteInitFailureMessageHandler f_pSuiteInitFailureMessageHandler = NULL;

/*------------------------------------------------------------------------*/
/** Assertion implementation function.
 * All CUnit assertions reduce to a call to this function.
 * It should only be called during an active test run (checked
 * by assertion).  This means that CUnit assertions should only
 * be used in registered test functions during a test run.
 * @param bValue        Value of the assertion (TRUE or FALSE).
 * @param uiLine        Line number of failed test statement.
 * @param strCondition  String containing logical test that failed.
 * @param strFile       Source file where test statement failed.
 * @param strFunction   Function where test statement failed.
 * @param bFatal        TRUE to abort test (via longjmp()), FALSE to continue test.
 * @return As a convenience, returns the value of the assertion.
 */
BOOL CU_assertImplementation(BOOL bValue, unsigned int uiLine,
                             char strCondition[], char strFile[],
                             char strFunction[], BOOL bFatal)
{
  /* not used in current implementation - stop compiler warning */
  (void)strFunction;

  /* these should always be non-NULL (i.e. a test run is in progress) */
  assert(f_pCurSuite);
  assert(f_pCurTest);

  ++f_run_summary.nAsserts;
  if (!bValue) {
    ++f_run_summary.nAssertsFailed;
    add_failure(&f_failure_list, &f_run_summary,
                uiLine, strCondition, strFile, f_pCurSuite, f_pCurTest);

    if (bFatal && f_pCurTest->pJumpBuf)
      longjmp(*(f_pCurTest->pJumpBuf), 1);
  }

  return bValue;
}

/*
 * Get/Set functions for Message Handlers.
 */
/*------------------------------------------------------------------------*/
/** Set the message handler to call before each test is run. */
void CU_set_test_start_handler(CU_TestStartMessageHandler pTestStartHandler)
{
  f_pTestStartMessageHandler = pTestStartHandler;
}

/*------------------------------------------------------------------------*/
/** Set the message handler to call after each test is run. */
void CU_set_test_complete_handler(CU_TestCompleteMessageHandler pTestCompleteHandler)
{
  f_pTestCompleteMessageHandler = pTestCompleteHandler;
}

/*------------------------------------------------------------------------*/
/** Set the message handler to call after all tests have been run. */
void CU_set_all_test_complete_handler(CU_AllTestsCompleteMessageHandler pAllTestsCompleteHandler)
{
  f_pAllTestsCompleteMessageHandler = pAllTestsCompleteHandler;
}

/*------------------------------------------------------------------------*/
/** Set the message handler to call when a suite
 * initialization function returns an error.
 */
void CU_set_suite_init_failure_handler(CU_SuiteInitFailureMessageHandler pSuiteInitFailureHandler)
{
  f_pSuiteInitFailureMessageHandler = pSuiteInitFailureHandler;
}

/*------------------------------------------------------------------------*/
/** Retrieve the message handler called before each test is run. */
CU_TestStartMessageHandler CU_get_test_start_handler(void)
{
  return f_pTestStartMessageHandler;
}

/*------------------------------------------------------------------------*/
/** Retrieve the message handler called after each test is run. */
CU_TestCompleteMessageHandler CU_get_test_complete_handler(void)
{
  return f_pTestCompleteMessageHandler;
}

/*------------------------------------------------------------------------*/
/** Retrieve the message handler called after all tests are run. */
CU_AllTestsCompleteMessageHandler CU_get_all_test_complete_handler(void)
{
  return f_pAllTestsCompleteMessageHandler;
}

/*------------------------------------------------------------------------*/
/** Retrieve the message handler called when a suite
 * initialization error occurs.
 */
CU_SuiteInitFailureMessageHandler CU_get_suite_init_failure_handler(void)
{
  return f_pSuiteInitFailureMessageHandler;
}

/*
 * Functions to get the Run statistics for the Test Run.
 */
/*------------------------------------------------------------------------*/
/** Retrieve the number of suites completed during the previous run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_tests_run()
 */
unsigned int CU_get_number_of_suites_run(void)
{
  return f_run_summary.nSuitesRun;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of suites which failed to initialize
 * during the previous run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_tests_run()
 */
unsigned int CU_get_number_of_suites_failed(void)
{
  return f_run_summary.nSuitesFailed;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of tests completed during the previous run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_suites_run()
 */
unsigned int CU_get_number_of_tests_run(void)
{
  return f_run_summary.nTestsRun;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of tests which contained failed
 * assertions during the previous run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_suites_run()
 */
unsigned int CU_get_number_of_tests_failed(void)
{
  return f_run_summary.nTestsFailed;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of assertions processed during the last run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_successes()
 * @see CU_get_number_of_failures()
 */
unsigned int CU_get_number_of_asserts(void)
{
  return f_run_summary.nAsserts;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of successful assertions during the last run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_failures()
 */
unsigned int CU_get_number_of_successes(void)
{
  return (f_run_summary.nAsserts - f_run_summary.nAssertsFailed);
}

/*------------------------------------------------------------------------*/
/** Retrieve the number of failed assertions during the last run.
 * The count is reset each time the client initiates a run.
 * @see CU_get_number_of_successes()
 */
unsigned int CU_get_number_of_failures(void)
{
  return f_run_summary.nAssertsFailed;
}

/*------------------------------------------------------------------------*/
/** Retrieve the number failure records created during 
 * the previous run.  Note that this may be more than the
 * number of failed assertions, since failure records may also
 * be created for failed suite initialization and cleanup.
 * The count is reset each time the client initiates a run.
 */
unsigned int CU_get_number_of_failure_records(void)
{
  return f_run_summary.nFailureRecords;
}

/*------------------------------------------------------------------------*/
/** Retrieve the list of failures which occurred during
 * the last test run.  Note that the pointer returned
 * is invalidated when the client initiates a run using
 * CU_run_all_tests(), CU_run_suite(), or CU_run_test().
 * @see CU_get_number_of_successes()
 */
const CU_pFailureRecord CU_get_failure_list(void)
{
  return f_failure_list;
}

/*------------------------------------------------------------------------*/
/** Retrieve the entire run summary for the last test run.
 * Note that the pFailure pointer in the run summary is
 * invalidated when the client initiates a run using
 * CU_run_all_tests(), CU_run_suite(), or CU_run_test().
 * @see CU_get_number_of_successes()
 */
const CU_pRunSummary CU_get_run_summary(void)
{
  return &f_run_summary;
}

/*
 * Functions for running suites and tests.
 */
/*------------------------------------------------------------------------*/
/** Run all tests in all suites registered in the test registry.
 * The suites are run in the order registered in the test registry.
 * For each registered suite, any initialization function is first
 * called, the suite is run using run_single_suite(), and finally
 * any  suite cleanup function is called.  If an error condition
 * (other than CUE_NOREGISTRY) occurs during the run, the action
 * depends on the current error action (see CU_set_error_action()).
 * @return A CU_ErrorCode indicating the first error condition
 *         encountered while running the tests.
 * @see CU_run_suite() to run the tests in a specific suite.
 * @see CU_run_test() for run a specific test only.
 */
CU_ErrorCode CU_run_all_tests(void)
{
  CU_pTestRegistry pRegistry = CU_get_registry();
  CU_pSuite pSuite = NULL;
  CU_ErrorCode result;
  CU_ErrorCode result2;

  CU_set_error(result = CUE_SUCCESS);
  if (!pRegistry) {
    CU_set_error(result = CUE_NOREGISTRY);
  }
  else {
    /* test run is starting - set flag */
    f_bTestIsRunning = TRUE;