libcunit1-ncurses-dev 2.1-2.dfsg-1 / usr / include / CUnit / TestRun.h

/*
 *  CUnit - A Unit testing framework library for C.
 *  Copyright (C) 2001       Anil Kumar
 *  Copyright (C) 2004-2006  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 Interface to Run tests.
 *
 *  Aug 2001      Initial implementation. (AK)
 *
 *  09/Aug/2001   Contains generic run tests interface which can be used
 *                for any type of frontend interface framework. (AK)
 *
 *  24/Nov/2001   Added Handler for Group Initialization failure condition. (AK)
 *
 *  05-Aug-2004   New interface.  Since these should be internal functions,
 *                no support for deprecated version 1 names provided now,
 *                eliminated global variables for current test & suite,
 *                moved (renamed) _TestResult here from TestDB.h. (JDS)
 *
 *  05-Sep-2004   Added internal test interface. (JDS)
 *
 *  23-Apr-2006   Moved doxygen comments into header.
 *                Added type marker to CU_FailureRecord.
 *                Added support for tracking inactive suites/tests. (JDS)
 *
 *  08-May-2006   Moved CU_print_run_results() functionality from
 *                console/basic test complete handler.  (JDS)
 *
 *  24-May-2006   Added callbacks for suite start and complete events.
 *                Added tracking/reported of elapsed time.  (JDS)
 */

/** @file
 *  Test run management functions (user interface).
 *  The TestRun module implements functions supporting the running
 *  of tests elements (suites and tests).  This includes functions for
 *  running suites and tests, retrieving the number of tests/suites run,
 *  and managing callbacks during the run process.<br /><br />
 *
 *  The callback mechanism works as follows.  The CUnit runtime system
 *  supports the registering and calling of functions at the start and end
 *  of each test, when all tests are complete, and when a suite
 *  initialialization function returns an error.  This allows clients to
 *  perform actions associated with these events such as output formatting
 *  and reporting.
 */
/** @addtogroup Framework
 * @{
 */

#ifndef CUNIT_TESTRUN_H_SEEN
#define CUNIT_TESTRUN_H_SEEN

#include "CUnit.h"
#include "CUError.h"
#include "TestDB.h"
#include <stdio.h>

#ifdef __cplusplus
extern "C" {
#endif

/** Types of failures occurring during test runs. */
typedef enum CU_FailureTypes
{
  CUF_SuiteInactive = 1,    /**< Inactive suite was run. */
  CUF_SuiteInitFailed,      /**< Suite initialization function failed. */
  CUF_SuiteCleanupFailed,   /**< Suite cleanup function failed. */
  CUF_TestInactive,         /**< Inactive test was run. */
  CUF_AssertFailed          /**< CUnit assertion failed during test run. */
} CU_FailureType;           /**< Failure type. */

/* CU_FailureRecord type definition. */
/** Data type for holding assertion failure information (linked list). */
typedef struct CU_FailureRecord
{
  CU_FailureType  type;           /**< Failure type. */
  unsigned int    uiLineNumber;   /**< Line number of failure. */
  char*           strFileName;    /**< Name of file where failure occurred. */
  char*           strCondition;   /**< Test condition which failed. */
  CU_pTest        pTest;          /**< Test containing failure. */
  CU_pSuite       pSuite;         /**< Suite containing test having failure. */

  struct CU_FailureRecord* pNext; /**< Pointer to next record in linked list. */
  struct CU_FailureRecord* pPrev; /**< Pointer to previous record in linked list. */

} CU_FailureRecord;
typedef CU_FailureRecord* CU_pFailureRecord;  /**< Pointer to CU_FailureRecord. */

/* CU_RunSummary type definition. */
/** Data type for holding statistics and assertion failures for a test run. */
typedef struct CU_RunSummary
{
  unsigned int nSuitesRun;        /**< Number of suites completed during run. */
  unsigned int nSuitesFailed;     /**< Number of suites for which initialization failed. */
  unsigned int nSuitesInactive;   /**< Number of suites which were inactive. */
  unsigned int nTestsRun;         /**< Number of tests completed during run. */
  unsigned int nTestsFailed;      /**< Number of tests containing failed assertions. */
  unsigned int nTestsInactive;    /**< Number of tests which were inactive (in active suites). */
  unsigned int nAsserts;          /**< Number of assertions tested during run. */
  unsigned int nAssertsFailed;    /**< Number of failed assertions. */
  unsigned int nFailureRecords;   /**< Number of failure records generated. */
  double       ElapsedTime;       /**< Elapsed time for run in seconds. */
} CU_RunSummary;
typedef CU_RunSummary* CU_pRunSummary;  /**< Pointer to CU_RunSummary. */

/*-------------------------------------------------------------------- 
 * Type Definitions for Message Handlers.
 *--------------------------------------------------------------------*/
typedef void (*CU_SuiteStartMessageHandler)(const CU_pSuite pSuite);
/**< Message handler called at the start of a suite. pSuite will not be null. */

typedef void (*CU_TestStartMessageHandler)(const CU_pTest pTest, const CU_pSuite pSuite);
/**< Message handler called at the start of a test.
 *  The parameters are the test and suite being run.  The test run is 
 *  considered in progress when the message handler is called.  
 *  Neither pTest nor pSuite may be null.
 */

typedef void (*CU_TestCompleteMessageHandler)(const CU_pTest pTest, const CU_pSuite pSuite,
                                              const CU_pFailureRecord pFailure);
/**< Message handler called at the completion of a test.
 *  The parameters are the test and suite being run, plus a pointer to 
 *  the first failure record applicable to this test.  If the test did 
 *  not have any assertion failures, pFailure will be NULL.  The test run 
 *  is considered in progress when the message handler is called.
 */

typedef void (*CU_SuiteCompleteMessageHandler)(const CU_pSuite pSuite,
                                               const CU_pFailureRecord pFailure);
/**< Message handler called at the completion of a suite.
 *  The parameters are suite being run, plus a pointer to the first failure 
 *  record applicable to this suite.  If the suite and it's tests did not 
 *  have any failures, pFailure will be NULL.  The test run is considered 
 *  in progress when the message handler is called.
 */

typedef void (*CU_AllTestsCompleteMessageHandler)(const CU_pFailureRecord pFailure);
/**< Message handler called at the completion of a test run.
 *  The parameter is a pointer to the linked list holding the failure 
 *  records for the test run.  The test run is considered completed 
 *  when the message handler is called.
 */

typedef void (*CU_SuiteInitFailureMessageHandler)(const CU_pSuite pSuite);
/**< Message handler called when a suite initializer fails.
 *  The test run is considered in progress when the message handler is called.
 */

typedef void (*CU_SuiteCleanupFailureMessageHandler)(const CU_pSuite pSuite);
/**< Message handler called when a suite cleanup function fails.
 *  The test run is considered in progress when the message handler is called.
 */

/*-------------------------------------------------------------------- 
 * Get/Set functions for Message Handlers
 *--------------------------------------------------------------------*/
CU_EXPORT void CU_set_suite_start_handler(CU_SuiteStartMessageHandler pSuiteStartMessage);
/**< Sets the message handler to call before each suite is run. */
CU_EXPORT void CU_set_test_start_handler(CU_TestStartMessageHandler pTestStartMessage);
/**< Sets the message handler to call before each test is run. */
CU_EXPORT void CU_set_test_complete_handler(CU_TestCompleteMessageHandler pTestCompleteMessage);
/**< Sets the message handler to call after each test is run. */
CU_EXPORT void CU_set_suite_complete_handler(CU_SuiteCompleteMessageHandler pSuiteCompleteMessage);
/**< Sets the message handler to call after each suite is run. */
CU_EXPORT void CU_set_all_test_complete_handler(CU_AllTestsCompleteMessageHandler pAllTestsCompleteMessage);
/**< Sets the message handler to call after all tests have been run. */
CU_EXPORT void CU_set_suite_init_failure_handler(CU_SuiteInitFailureMessageHandler pSuiteInitFailureMessage);
/**< Sets the message handler to call when a suite initialization function returns an error. */
CU_EXPORT void CU_set_suite_cleanup_failure_handler(CU_SuiteCleanupFailureMessageHandler pSuiteCleanupFailureMessage);
/**< Sets the message handler to call when a suite cleanup function returns an error. */

CU_EXPORT CU_SuiteStartMessageHandler          CU_get_suite_start_handler(void);
/**< Retrieves the message handler called before each suite is run. */
CU_EXPORT CU_TestStartMessageHandler           CU_get_test_start_handler(void);
/**< Retrieves the message handler called before each test is run. */
CU_EXPORT CU_TestCompleteMessageHandler        CU_get_test_complete_handler(void);
/**< Retrieves the message handler called after each test is run. */
CU_EXPORT CU_SuiteCompleteMessageHandler       CU_get_suite_complete_handler(void);
/**< Retrieves the message handler called after each suite is run. */
CU_EXPORT CU_AllTestsCompleteMessageHandler    CU_get_all_test_complete_handler(void);
/**< Retrieves the message handler called after all tests are run. */
CU_EXPORT CU_SuiteInitFailureMessageHandler    CU_get_suite_init_failure_handler(void);
/**< Retrieves the message handler called when a suite initialization error occurs. */
CU_EXPORT CU_SuiteCleanupFailureMessageHandler CU_get_suite_cleanup_failure_handler(void);
/**< Retrieves the message handler called when a suite cleanup error occurs. */

/*-------------------------------------------------------------------- 
 * Functions for running registered tests and suites.
 *--------------------------------------------------------------------*/
CU_EXPORT CU_ErrorCode CU_run_all_tests(void);
/**< 
 *  Runs all tests in all suites registered in the test registry.
 *  The suites are run in the order registered in the test registry.
 *  For each suite, it is first checked to make sure it is active.
 *  Any initialization function is then 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()).  An inactive suite is not
 *  considered an error for this function.  Note that the run
 *  statistics (counts of tests, successes, failures) are cleared 
 *  each time this function is run, even if it is unsuccessful.
 *
 *  @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_EXPORT CU_ErrorCode CU_run_suite(CU_pSuite pSuite);
/**< 
 *  Runs all tests in a specified suite.
 *  The suite need not be registered in the test registry to be 
 *  run.  It does, however, need to have its fActive flag set to 
 *  CU_TRUE.<br /><br />
 *
 *  Any initialization function for the suite is first called,
 *  then the suite is run using run_single_suite(), and any suite 
 *  cleanup function is called.  Note that the run statistics 
 *  (counts of tests, successes, failures) are initialized each 
 *  time this function is called even if it is unsuccessful.  If 
 *  an error condition occurs during the run, the action depends 
 *  on the  current error action (see CU_set_error_action()).
 *
 *  @param pSuite The suite containing the test (non-NULL)
 *  @return A CU_ErrorCode indicating the first error condition
 *          encountered while running the suite.  CU_run_suite()
 *          sets and returns CUE_NOSUITE if pSuite is NULL, or 
 *          CUE_SUITE_INACTIVE if the requested suite is not 
 *          activated.  Other error codes can be set during suite 
 *          initialization or cleanup or during test runs.
 *  @see CU_run_all_tests() to run all suites.
 *  @see CU_run_test() to run a single test in a specific suite.
 */

CU_EXPORT CU_ErrorCode CU_run_test(CU_pSuite pSuite, CU_pTest pTest);
/**< 
 *  Runs a specific test in a specified suite.
 *  The suite need not be registered in the test registry to be run,
 *  although the test must be registered in the specified suite.
 *  Any initialization function for the suite is first
 *  called, then the test is run using run_single_test(), and
 *  any suite cleanup function is called.  Note that the
 *  run statistics (counts of tests, successes, failures)
 *  will be initialized each time this function is called even
 *  if it is not successful.  Both the suite and test specified
 *  must be active for the test to be run.  The suite is not
 *  considered to be run, although it may be counted as a failed
 *  suite if the intialization or cleanup functions fail.
 *
 *  @param pSuite The suite containing the test (non-NULL)
 *  @param pTest  The test to run (non-NULL)
 *  @return A CU_ErrorCode indicating the first error condition
 *          encountered while running the suite.  CU_run_test()
 *          sets and returns CUE_NOSUITE if pSuite is NULL,
 *          CUE_NOTEST if pTest is NULL, CUE_SUITE_INACTIVE if
 *          pSuite is not active, CUE_TEST_NOT_IN_SUITE
 *          if pTest is not registered in pSuite, and CU_TEST_INACTIVE
 *          if pTest is not active.  Other error codes can be set during 
 *          suite initialization or cleanup or during the test run.
 *  @see CU_run_all_tests() to run all tests/suites.
 *  @see CU_run_suite() to run all tests in a specific suite.
 */

/*-------------------------------------------------------------------- 
 * Functions for setting runtime behavior.
 *--------------------------------------------------------------------*/
CU_EXPORT void CU_set_fail_on_inactive(CU_BOOL new_inactive);
/**<
 *  Sets whether an inactive suite or test is treated as a failure.
 *  If CU_TRUE, then failure records will be generated for inactive 
 *  suites or tests encountered during a test run.  The default is 
 *  CU_TRUE so that the client is reminded that the framewrork 
 *  contains inactive suites/tests.  Set to CU_FALSE to turn off 
 *  this behavior.
 *
 *  @param new_inactive New setting for whether to treat inactive
 *                      suites and tests as failures during a test 
 *                      run (CU_TRUE) or not (CU_FALSE).
 *  @see CU_get_fail_on_failure()
 */
 
CU_EXPORT CU_BOOL CU_get_fail_on_inactive(void);
/**<
 *  Retrieves the current setting for whether inactive suites/tests 
 *  are treated as failures.  If CU_TRUE then failure records will 
 *  be generated for inactive suites encountered during a test run.
 *
 *  @return CU_TRUE if inactive suites/tests are failures, CU_FALSE if not.
 *  @see CU_set_fail_on_inactive()
 */

/*-------------------------------------------------------------------- 
 * Functions for getting information about the previous test run. 
 *--------------------------------------------------------------------*/
CU_EXPORT unsigned int CU_get_number_of_suites_run(void);
/**< Retrieves the number of suites completed during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_suites_failed(void);
/**< Retrieves the number of suites which failed to initialize during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_suites_inactive(void);
/**< Retrieves the number of inactive suites found during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_tests_run(void);
/**< Retrieves the number of tests completed during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_tests_failed(void);
/**< Retrieves the number of tests containing failed assertions during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_tests_inactive(void);
/**< Retrieves the number of inactive tests found during the previous run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_asserts(void);
/**< Retrieves the number of assertions processed during the last run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_successes(void);
/**< Retrieves the number of successful assertions during the last run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_failures(void);
/**< Retrieves the number of failed assertions during the last run (reset each run). */
CU_EXPORT unsigned int CU_get_number_of_failure_records(void);
/**< 
 *  Retrieves the number failure records created during the previous run (reset each 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.
 */
CU_EXPORT double CU_get_elapsed_time(void);
/**< 
 *  Retrieves the elapsed time for the last run in seconds (reset each run).
 *  This function will calculate the current elapsed time if the test run has not
 *  yet completed.  This is in contrast to the run summary returned by
 *  CU_get_run_summary(), for which the elapsed time is not updated until the
 *  end of the run.
 */
CU_EXPORT CU_pFailureRecord CU_get_failure_list(void);
/**< 
 *  Retrieves the head of the linked list of failures which occurred during the 
 *  last run (reset each 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().
 */
CU_EXPORT CU_pRunSummary CU_get_run_summary(void);
/**< 
 *  Retrieves the entire run summary for the last test run (reset each run).
 *  The run counts and stats contained in the run summary are updated 
 *  throughout a test run.  Note, however, that the elapsed time is not 
 *  updated until after all suites/tests are run but before the "all tests 
 *  complete"  message handler is called (if any).  To get the elapsed 
 *  time during a test run, use CU_get_elapsed_time() instead.
 */

CU_EXPORT char * CU_get_run_results_string(void);
/**<
 *  Creates a string and fills it with a summary of the current run results.
 *  The run summary presents data for the suites, tests, and assertions 
 *  encountered during the run, as well as the elapsed time.  The data 
 *  presented include the number of registered, run, passed, failed, and 
 *  inactive entities for each, as well as the elapsed time.  This function 
 *  can be called at any time, although the test registry must have been 
 *  initialized (checked by assertion).  The returned string is owned by 
 *  the caller and should be deallocated using CU_FREE().  NULL is returned 
 *  if there is an error allocating the new string.
 *
 *  @return A new string containing the run summary (owned by caller).
 */
 
CU_EXPORT void CU_print_run_results(FILE *file);
/**<
 *  Prints a summary of the current run results to file.
 *  The run summary is the same as returned by CU_get_run_results_string().
 *  Note that no newlines are printed before or after the report, so any
 *  positioning must be performed before/after calling this function.  The
 *  report itself extends over several lines broken by '\n' characters.
 *  file may not be NULL (checked by assertion).
 *
 *  @param file Pointer to stream to receive the printed summary (non-NULL).
 */

/*-------------------------------------------------------------------- 
 * Functions for internal & testing use.
 *--------------------------------------------------------------------*/
CU_EXPORT CU_pSuite CU_get_current_suite(void);
/**< Retrieves a pointer to the currently-running suite (NULL if none). */
CU_EXPORT CU_pTest  CU_get_current_test(void);
/**< Retrievea a pointer to the currently-running test (NULL if none). */
CU_EXPORT CU_BOOL   CU_is_test_running(void);
/**< Returns <CODE>CU_TRUE</CODE> if a test run is in progress,
 *  <CODE>CU_TRUE</CODE> otherwise.
 */

CU_EXPORT void      CU_clear_previous_results(void);
/**< 
 *  Initializes the run summary information stored from the previous test run.  
 *  Resets the run counts to zero, and frees any memory associated with 
 *  failure records.  Calling this function multiple times, while inefficient, 
 *  will not cause an error condition.
 *  @see clear_previous_results()
 */

CU_EXPORT CU_BOOL CU_assertImplementation(CU_BOOL bValue,
                                          unsigned int uiLine,
                                          const char *strCondition,
                                          const char *strFile,
                                          const char *strFunction,
                                          CU_BOOL bFatal);
/**< 
 *  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 (CU_TRUE or CU_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        CU_TRUE to abort test (via longjmp()), CU_FALSE to continue test.
 *  @return As a convenience, returns the value of the assertion (i.e. bValue).
 */

#ifdef USE_DEPRECATED_CUNIT_NAMES
typedef CU_FailureRecord  _TestResult;  /**< @deprecated Use CU_FailureRecord. */
typedef CU_pFailureRecord PTestResult;  /**< @deprecated Use CU_pFailureRecord. */
#endif  /* USE_DEPRECATED_CUNIT_NAMES */

#ifdef CUNIT_BUILD_TESTS
void test_cunit_TestRun(void);
#endif

#ifdef __cplusplus
}
#endif
#endif  /*  CUNIT_TESTRUN_H_SEEN  */
/** @} */