CUnit Programmers Reference  3.0
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Framework

Data Structures

struct  CU_Test
 CUnit test case data type. More...
 
struct  CU_Suite
 CUnit suite data type. More...
 
struct  CU_TestRegistry
 CUnit test registry data type. More...
 
struct  CU_TestInfo
 Test case parameters structure. More...
 
struct  CU_SuiteInfo
 Suite parameters. More...
 
struct  test_suite
 Deprecated (version 1). More...
 
struct  CU_FailureRecord
 Data type for holding assertion failure information (linked list). More...
 
struct  CU_RunSummary
 Data type for holding statistics and assertion failures for a test run. More...
 
struct  bindings
 Structure containing mappings of special characters to xml entity codes. More...
 

Macros

#define get_error()   CU_get_error_msg()
 Deprecated (version 1). More...
 
#define CU_CALLOC(x, y)   calloc((x), (y))
 Standard calloc() if MEMTRACE not defined. More...
 
#define CU_MALLOC(x)   malloc((x))
 Standard malloc() if MEMTRACE not defined. More...
 
#define CU_FREE(x)   free((x))
 Standard free() if MEMTRACE not defined. More...
 
#define CU_REALLOC(x, y)   realloc((x), (y))
 Standard realloc() if MEMTRACE not defined. More...
 
#define CU_CREATE_MEMORY_REPORT(x)
 No-op if MEMTRACE not defined. More...
 
#define CU_DUMP_MEMORY_USAGE(x)
 No-op if MEMTRACE not defined. More...
 
#define CU_FREE_ZERO(x)   do { CU_FREE(x); x = NULL; } while(0)
 Free then set x to NULL.
 
#define CU_ADD_TEST(suite, test)   (CU_add_test(suite, #test, (CU_TestFunc)test))
 Shortcut macro for adding a test to a suite. More...
 
#define CU_TEST_INFO_NULL   { NULL, NULL }
 NULL CU_test_info_t to terminate arrays of tests. More...
 
#define CU_SUITE_INFO_NULL   { NULL, NULL, NULL, NULL, NULL, NULL }
 NULL CU_suite_info_t to terminate arrays of suites. More...
 
#define TEST_CASE_NULL   { NULL, NULL }
 Deprecated (version 1). More...
 
#define TEST_GROUP_NULL   { NULL, NULL, NULL, NULL }
 Deprecated (version 1). More...
 
#define test_group_register(tg)   CU_register_suites(tg)
 Deprecated (version 1). More...
 
#define initialize_registry()   CU_initialize_registry()
 Deprecated (version 1). More...
 
#define cleanup_registry()   CU_cleanup_registry()
 Deprecated (version 1). More...
 
#define add_test_group(name, init, clean)   CU_add_suite(name, init, clean)
 Deprecated (version 1). More...
 
#define add_test_case(group, name, test)   CU_add_test(group, name, test)
 Deprecated (version 1). More...
 
#define get_registry()   CU_get_registry()
 Deprecated (version 1). More...
 
#define set_registry(reg)   CU_set_registry((reg))
 Deprecated (version 1). More...
 
#define get_group_by_name(group, reg)   CU_get_suite_by_name(group, reg)
 Deprecated (version 1). More...
 
#define get_test_by_name(test, group)   CU_get_test_by_name(test, group)
 Deprecated (version 1). More...
 
#define ADD_TEST_TO_GROUP(group, test)   (CU_add_test(group, #test, (CU_TestFunc)test))
 Deprecated (version 1). More...
 
#define CU_SKIP_IF(value)   { CU_SkipImplementation((value), __LINE__, ("CU_SKIP_IF(" #value ")"), __FILE__, ""); }
 Skip the current suite or test if true. More...
 
#define CUNIT_MAX_ENTITY_LEN   5
 Maximum number of characters in a translated xml entity. More...
 
#define CUNIT_MAX_STRING_LENGTH   1024
 Maximum string length. More...
 
#define translate_special_characters(src, dest, len)   CU_translate_special_characters(src, dest, len)
 Deprecated (version 1). More...
 
#define compare_strings(src, dest)   CU_compare_strings(src, dest)
 Deprecated (version 1). More...
 
#define trim_left(str)   CU_trim_left(str)
 Deprecated (version 1). More...
 
#define trim_right(str)   CU_trim_right(str)
 Deprecated (version 1). More...
 
#define trim(str)   CU_trim(str)
 Deprecated (version 1). More...
 

Typedefs

typedef enum CU_ErrorAction CU_ErrorAction
 CUnit error action codes. More...
 
typedef int(* CU_InitializeFunc) (void)
 Signature for suite initialization function. More...
 
typedef int(* CU_CleanupFunc) (void)
 Signature for suite cleanup function. More...
 
typedef void(* CU_TestFunc) (void)
 Signature for a testing function in a test case. More...
 
typedef void(* CU_SetUpFunc) (void)
 Signature for a test SetUp function. More...
 
typedef void(* CU_TearDownFunc) (void)
 Signature for a test TearDown function. More...
 
typedef struct CU_Test CU_Test
 CUnit test case data type. More...
 
typedef CU_TestCU_pTest
 Pointer to a CUnit test case. More...
 
typedef struct CU_Suite CU_Suite
 CUnit suite data type. More...
 
typedef CU_SuiteCU_pSuite
 Pointer to a CUnit suite. More...
 
typedef struct CU_TestRegistry CU_TestRegistry
 CUnit test registry data type. More...
 
typedef CU_TestRegistryCU_pTestRegistry
 Pointer to a CUnit test registry. More...
 
typedef struct CU_TestInfo CU_TestInfo
 Test case parameters structure. More...
 
typedef CU_TestInfoCU_pTestInfo
 Pointer to CU_TestInfo type. More...
 
typedef struct CU_SuiteInfo CU_SuiteInfo
 Suite parameters. More...
 
typedef CU_SuiteInfoCU_pSuiteInfo
 Pointer to CU_SuiteInfo type. More...
 
typedef CU_TestInfo test_case_t
 Deprecated (version 1). More...
 
typedef CU_SuiteInfo test_group_t
 Deprecated (version 1). More...
 
typedef struct test_suite test_suite_t
 Deprecated (version 1). More...
 
typedef CU_InitializeFunc InitializeFunc
 Deprecated (version 1). More...
 
typedef CU_CleanupFunc CleanupFunc
 Deprecated (version 1). More...
 
typedef CU_TestFunc TestFunc
 Deprecated (version 1). More...
 
typedef CU_Test _TestCase
 Deprecated (version 1). More...
 
typedef CU_pTest PTestCase
 Deprecated (version 1). More...
 
typedef CU_Suite _TestGroup
 Deprecated (version 1). More...
 
typedef CU_pSuite PTestGroup
 Deprecated (version 1). More...
 
typedef CU_TestRegistry _TestRegistry
 Deprecated (version 1). More...
 
typedef CU_pTestRegistry PTestRegistry
 Deprecated (version 1). More...
 
typedef enum CU_FailureTypes CU_FailureType
 Types of failures occurring during test runs. More...
 
typedef struct CU_FailureRecord CU_FailureRecord
 Data type for holding assertion failure information (linked list). More...
 
typedef CU_FailureRecordCU_pFailureRecord
 Pointer to CU_FailureRecord. More...
 
typedef struct CU_RunSummary CU_RunSummary
 Data type for holding statistics and assertion failures for a test run. More...
 
typedef CU_RunSummaryCU_pRunSummary
 Pointer to CU_RunSummary. More...
 
typedef void(* CU_SuiteStartMessageHandler) (const CU_pSuite pSuite)
 Message handler called at the start of a suite. More...
 
typedef void(* CU_TestStartMessageHandler) (const CU_pTest pTest, const CU_pSuite pSuite)
 Message handler called at the start of a test. More...
 
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. More...
 
typedef void(* CU_TestSkippedMessageHandler) (const CU_pTest pTest, const CU_pSuite pSuite)
 Message handler called when a test is skipped. More...
 
typedef void(* CU_SuiteCompleteMessageHandler) (const CU_pSuite pSuite, const CU_pFailureRecord pFailure)
 Message handler called at the completion of a suite. More...
 
typedef void(* CU_AllTestsCompleteMessageHandler) (const CU_pFailureRecord pFailure)
 Message handler called at the completion of a test run. More...
 
typedef void(* CU_SuiteInitFailureMessageHandler) (const CU_pSuite pSuite)
 Message handler called when a suite initializer fails. More...
 
typedef void(* CU_SuiteCleanupFailureMessageHandler) (const CU_pSuite pSuite)
 Message handler called when a suite cleanup function fails. More...
 
typedef void(* CU_SuiteSkippedMessageHandler) (const CU_pSuite pSuite)
 Message handler called when a suite is skipped during setup.
 
typedef CU_FailureRecord _TestResult
 
typedef CU_pFailureRecord PTestResult
 

Enumerations

enum  CU_ErrorCode {
  CUE_SUCCESS = 0, CUE_NOMEMORY = 1, CUE_NOREGISTRY = 10, CUE_REGISTRY_EXISTS = 11,
  CUE_NOSUITE = 20, CUE_NO_SUITENAME = 21, CUE_SINIT_FAILED = 22, CUE_SCLEAN_FAILED = 23,
  CUE_DUP_SUITE = 24, CUE_SUITE_INACTIVE = 25, CUE_NOTEST = 30, CUE_NO_TESTNAME = 31,
  CUE_DUP_TEST = 32, CUE_TEST_NOT_IN_SUITE = 33, CUE_TEST_INACTIVE = 34, CUE_FOPEN_FAILED = 40,
  CUE_FCLOSE_FAILED = 41, CUE_BAD_FILENAME = 42, CUE_WRITE_ERROR = 43
}
 CUnit error codes. More...
 
enum  CU_ErrorAction { CUEA_IGNORE, CUEA_FAIL, CUEA_ABORT }
 CUnit error action codes. More...
 
enum  CU_FailureTypes {
  CUF_SuiteInactive = 1, CUF_SuiteInitFailed, CUF_SuiteCleanupFailed, CUF_TestInactive,
  CUF_AssertFailed
}
 Types of failures occurring during test runs. More...
 

Functions

CU_EXPORT CU_ErrorCode CU_get_error (void)
 Retrieves the current CUnit framework error code. More...
 
CU_EXPORT const char * CU_get_error_msg (void)
 Retrieves a message corresponding to the current framework error code. More...
 
CU_EXPORT void CU_set_error_action (CU_ErrorAction action)
 Sets the action to take when a framework error condition occurs. More...
 
CU_EXPORT CU_ErrorAction CU_get_error_action (void)
 Retrieves the current framework error action code. More...
 
CU_EXPORT void CU_set_error (CU_ErrorCode error)
 Sets the CUnit framework error code. More...
 
CU_EXPORT CU_ErrorCode CU_initialize_registry (void)
 Initializes the framework test registry. More...
 
CU_EXPORT void CU_cleanup_registry (void)
 Clears the test registry. More...
 
CU_EXPORT CU_BOOL CU_registry_initialized (void)
 Checks whether the test registry has been initialized. More...
 
CU_EXPORT CU_pSuite CU_add_suite (const char *strName, CU_InitializeFunc pInit, CU_CleanupFunc pClean)
 Creates a new test suite and adds it to the test registry. More...
 
CU_EXPORT CU_pSuite CU_add_suite_with_setup_and_teardown (const char *strName, CU_InitializeFunc pInit, CU_CleanupFunc pClean, CU_SetUpFunc pSetup, CU_TearDownFunc pTear)
 The same as CU_add_suite but also adds setup and tear down callbacks for each test in this suite. More...
 
CU_EXPORT CU_ErrorCode CU_set_suite_active (CU_pSuite pSuite, CU_BOOL fNewActive)
 Activates or deactivates a suite. More...
 
CU_EXPORT CU_ErrorCode CU_set_suite_name (CU_pSuite pSuite, const char *strNewName)
 Modifies the name of a suite. More...
 
CU_EXPORT CU_ErrorCode CU_set_suite_initfunc (CU_pSuite pSuite, CU_InitializeFunc pNewInit)
 Modifies the initialization function of a suite. More...
 
CU_EXPORT CU_ErrorCode CU_set_suite_cleanupfunc (CU_pSuite pSuite, CU_CleanupFunc pNewClean)
 Modifies the cleanup function of a suite. More...
 
CU_EXPORT CU_pSuite CU_get_suite (const char *strName)
 Retrieves the suite having the specified name. More...
 
CU_EXPORT CU_pSuite CU_get_suite_at_pos (unsigned int pos)
 Retrieves the suite at the specified position. More...
 
CU_EXPORT unsigned int CU_get_suite_pos (CU_pSuite pSuite)
 Looks up the position of the specified suite. More...
 
CU_EXPORT unsigned int CU_get_suite_pos_by_name (const char *strName)
 Looks up the position of the suite having the specified name. More...
 
CU_EXPORT CU_pTest CU_add_test (CU_pSuite pSuite, const char *strName, CU_TestFunc pTestFunc)
 This function creates a new test having the specified name and function, and adds it to the specified suite. More...
 
CU_EXPORT CU_ErrorCode CU_set_test_active (CU_pTest pTest, CU_BOOL fNewActive)
 Activates or deactivates a specific test. More...
 
CU_EXPORT CU_ErrorCode CU_set_test_name (CU_pTest pTest, const char *strNewName)
 Modifies the name of a test. More...
 
CU_EXPORT CU_ErrorCode CU_set_test_func (CU_pTest pTest, CU_TestFunc pNewFunc)
 Modifies the test function of a test. More...
 
CU_EXPORT CU_pTest CU_get_test (CU_pSuite pSuite, const char *strName)
 Retrieves the test having the specified name. More...
 
CU_EXPORT CU_pTest CU_get_test_at_pos (CU_pSuite pSuite, unsigned int pos)
 Retrieves the test at the specified position in pSuite. More...
 
CU_EXPORT unsigned int CU_get_test_pos (CU_pSuite pSuite, CU_pTest pTest)
 Looks up the position of the specified test in pSuite. More...
 
CU_EXPORT unsigned int CU_get_test_pos_by_name (CU_pSuite pSuite, const char *strName)
 Looks up the position of the test having the specified name in pSuite. More...
 
CU_EXPORT CU_ErrorCode CU_register_suites (CU_SuiteInfo suite_info[])
 Registers the suites in a single CU_SuiteInfo array. More...
 
CU_EXPORT CU_ErrorCode CU_register_nsuites (int suite_count,...)
 Registers multiple suite arrays in CU_SuiteInfo format. More...
 
CU_EXPORT int test_suite_register (test_suite_t *ts)
 Deprecated (version 1). More...
 
CU_EXPORT CU_pTestRegistry CU_get_registry (void)
 Retrieves a pointer to the current test registry. More...
 
CU_EXPORT CU_pTestRegistry CU_set_registry (CU_pTestRegistry pTestRegistry)
 Sets the registry to an existing CU_pTestRegistry instance. More...
 
CU_EXPORT CU_pTestRegistry CU_create_new_registry (void)
 Creates and initializes a new test registry. More...
 
CU_EXPORT void CU_destroy_existing_registry (CU_pTestRegistry *ppRegistry)
 Destroys and frees all memory for an existing test registry. More...
 
CU_EXPORT CU_pSuite CU_get_suite_by_name (const char *szSuiteName, CU_pTestRegistry pRegistry)
 Retrieves a pointer to the suite having the specified name. More...
 
CU_EXPORT CU_pSuite CU_get_suite_by_index (unsigned int index, CU_pTestRegistry pRegistry)
 Retrieves a pointer to the suite at the specified (1-based) index. More...
 
CU_EXPORT CU_pTest CU_get_test_by_name (const char *szTestName, CU_pSuite pSuite)
 Retrieves a pointer to the test case in pSuite having the specified name. More...
 
CU_EXPORT CU_pTest CU_get_test_by_index (unsigned int index, CU_pSuite pSuite)
 Retrieves a pointer to the test at the specified (1-based) index. More...
 
CU_EXPORT void CU_set_suite_start_handler (CU_SuiteStartMessageHandler pSuiteStartMessage)
 Sets the message handler to call before each suite is run. More...
 
CU_EXPORT void CU_set_test_start_handler (CU_TestStartMessageHandler pTestStartMessage)
 Sets the message handler to call before each test is run. More...
 
CU_EXPORT void CU_set_test_complete_handler (CU_TestCompleteMessageHandler pTestCompleteMessage)
 Sets the message handler to call after each test is run. More...
 
CU_EXPORT void CU_set_test_skipped_handler (CU_TestSkippedMessageHandler pTestSkippedMessage)
 Sets the message handler to call when a test is skipped. More...
 
CU_EXPORT void CU_set_suite_complete_handler (CU_SuiteCompleteMessageHandler pSuiteCompleteMessage)
 Sets the message handler to call after each suite is run. More...
 
CU_EXPORT void CU_set_all_test_complete_handler (CU_AllTestsCompleteMessageHandler pAllTestsCompleteMessage)
 Sets the message handler to call after all tests have been run. More...
 
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. More...
 
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. More...
 
CU_EXPORT void CU_set_suite_skipped_handler (CU_SuiteSkippedMessageHandler pSuiteSkipped)
 Sets the message handler to call when a suite is skipped.
 
CU_EXPORT CU_SuiteStartMessageHandler CU_get_suite_start_handler (void)
 Retrieves the message handler called before each suite is run. More...
 
CU_EXPORT CU_TestStartMessageHandler CU_get_test_start_handler (void)
 Retrieves the message handler called before each test is run. More...
 
CU_EXPORT CU_TestCompleteMessageHandler CU_get_test_complete_handler (void)
 Retrieves the message handler called after each test is run. More...
 
CU_EXPORT CU_TestSkippedMessageHandler CU_get_test_skipped_handler (void)
 Retrieves the message handler called when a test is skipped. More...
 
CU_EXPORT CU_SuiteCompleteMessageHandler CU_get_suite_complete_handler (void)
 Retrieves the message handler called after each suite is run. More...
 
CU_EXPORT CU_AllTestsCompleteMessageHandler CU_get_all_test_complete_handler (void)
 Retrieves the message handler called after all tests are run. More...
 
CU_EXPORT CU_SuiteInitFailureMessageHandler CU_get_suite_init_failure_handler (void)
 Retrieves the message handler called when a suite initialization error occurs. More...
 
CU_EXPORT CU_SuiteCleanupFailureMessageHandler CU_get_suite_cleanup_failure_handler (void)
 Retrieves the message handler called when a suite cleanup error occurs. More...
 
CU_EXPORT CU_ErrorCode CU_run_all_tests (void)
 Runs all tests in all suites registered in the test registry. More...
 
CU_EXPORT CU_ErrorCode CU_run_suite (CU_pSuite pSuite)
 Runs all tests in a specified suite. More...
 
CU_EXPORT CU_ErrorCode CU_run_test (CU_pSuite pSuite, CU_pTest pTest)
 Runs a specific test in a specified suite. More...
 
CU_EXPORT void CU_set_fail_on_inactive (CU_BOOL new_inactive)
 Sets whether an inactive suite or test is treated as a failure. More...
 
CU_EXPORT CU_BOOL CU_get_fail_on_inactive (void)
 Retrieves the current setting for whether inactive suites/tests are treated as failures. More...
 
CU_EXPORT unsigned int CU_get_number_of_suites_run (void)
 Retrieves the number of suites completed during the previous run (reset each run). More...
 
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). More...
 
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). More...
 
CU_EXPORT unsigned int CU_get_number_of_tests_run (void)
 Retrieves the number of tests completed during the previous run (reset each run). More...
 
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). More...
 
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). More...
 
CU_EXPORT unsigned int CU_get_number_of_asserts (void)
 Retrieves the number of assertions processed during the last run (reset each run). More...
 
CU_EXPORT unsigned int CU_get_number_of_successes (void)
 Retrieves the number of successful assertions during the last run (reset each run). More...
 
CU_EXPORT unsigned int CU_get_number_of_failures (void)
 Retrieves the number of failed assertions during the last run (reset each run). More...
 
CU_EXPORT unsigned int CU_get_number_of_failure_records (void)
 Retrieves the number failure records created during the previous run (reset each run). More...
 
CU_EXPORT double CU_get_elapsed_time (void)
 Retrieves the elapsed time for the last run in seconds (reset each run). More...
 
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). More...
 
CU_EXPORT CU_pFailureRecord CU_iterate_test_failures (CU_pTest test, CU_pFailureRecord previous)
 Iterate over the recorded failure records of a given test. More...
 
CU_EXPORT int CU_count_test_failures (CU_pTest pTest)
 Count the number of failures from the given test. More...
 
CU_EXPORT int CU_count_suite_failures (CU_pSuite pSuite)
 Count the number of failed tests in a suite. More...
 
CU_EXPORT int CU_count_all_failures (CU_pTestRegistry pRegistry)
 Count the number of failed tests overall. More...
 
CU_EXPORT int CU_count_all_tests (CU_pTestRegistry pRegistry)
 Count the number of tests in a suite. More...
 
CU_EXPORT CU_pRunSummary CU_get_run_summary (void)
 Count the number of tests in all suites. More...
 
CU_EXPORT char * CU_get_run_results_string (void)
 Creates a string and fills it with a summary of the current run results. More...
 
CU_EXPORT void CU_print_run_results (FILE *file)
 Prints a summary of the current run results to file. More...
 
CU_EXPORT double CU_get_test_duration (CU_pTest pTest)
 
CU_EXPORT double CU_get_suite_duration (CU_pSuite pSuite)
 
CU_EXPORT CU_pSuite CU_get_current_suite (void)
 Retrieves a pointer to the currently-running suite (NULL if none). More...
 
CU_EXPORT CU_pTest CU_get_current_test (void)
 Retrievea a pointer to the currently-running test (NULL if none). More...
 
CU_EXPORT CU_BOOL CU_is_test_running (void)
 Returns CU_TRUE if a test run is in progress, CU_TRUE otherwise.
 
CU_EXPORT void CU_clear_previous_results (void)
 Initializes the run summary information stored from the previous test run. More...
 
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. More...
 
CU_EXPORT void CU_SkipImplementation (CU_BOOL bValue, unsigned int uiLine, const char *strCondition, const char *strFile, const char *strFunction)
 Skip Implementation Called to skip execution of current test or current suite. More...
 
CU_EXPORT size_t CU_translate_special_characters (const char *szSrc, char *szDest, size_t maxlen)
 Converts special characters in szSrc to xml entity codes and stores result in szDest. More...
 
CU_EXPORT size_t CU_translated_strlen (const char *szSrc)
 Calculates the length of a translated string. More...
 
CU_EXPORT int CU_compare_strings (const char *szSrc, const char *szDest)
 Case-insensitive string comparison. More...
 
CU_EXPORT void CU_trim_left (char *szString)
 Trims leading whitespace from the specified string. More...
 
CU_EXPORT void CU_trim_right (char *szString)
 Trims trailing whitespace from the specified string. More...
 
CU_EXPORT void CU_trim (char *szString)
 Trims leading and trailing whitespace from the specified string. More...
 
CU_EXPORT size_t CU_number_width (int number)
 Calulates the number of places required to display number in decimal.
 
CU_EXPORT const char * CU_get_basename (const char *path)
 Given a file path, return a pointer to the last component (the basename). More...
 
static const char * get_error_desc (CU_ErrorCode iError)
 Internal function to look up the error message for a specified error code. More...
 
static void cleanup_test_registry (CU_pTestRegistry pRegistry)
 Internal function to clean up the specified test registry. More...
 
static CU_pSuite create_suite (const char *strName, CU_InitializeFunc pInit, CU_CleanupFunc pClean, CU_SetUpFunc pSetup, CU_TearDownFunc pTear)
 Internal function to create a new test suite having the specified parameters. More...
 
static void cleanup_suite (CU_pSuite pSuite)
 Internal function to clean up the specified test suite. More...
 
static void insert_suite (CU_pTestRegistry pRegistry, CU_pSuite pSuite)
 Internal function to insert a suite into a registry. More...
 
static CU_pTest create_test (const char *strName, CU_TestFunc pTestFunc)
 Internal function to create a new test case having the specified parameters. More...
 
static void cleanup_test (CU_pTest pTest)
 Internal function to clean up the specified test. More...
 
static void insert_test (CU_pSuite pSuite, CU_pTest pTest)
 Internal function to insert a test into a suite. More...
 
static CU_BOOL suite_exists (CU_pTestRegistry pRegistry, const char *szSuiteName)
 Internal function to check whether a suite having a specified name already exists. More...
 
static CU_BOOL test_exists (CU_pSuite pSuite, const char *szTestName)
 Internal function to check whether a test having a specified name is already registered in a given suite. More...
 
static void clear_previous_results (CU_pRunSummary pRunSummary, CU_pFailureRecord *ppFailure)
 Initializes the run summary information in the specified structure. More...
 
static void cleanup_failure_list (CU_pFailureRecord *ppFailure)
 Frees all memory allocated for the linked list of test failure records. More...
 
static CU_ErrorCode run_single_suite (CU_pSuite pSuite, CU_pRunSummary pRunSummary)
 Runs all tests in a specified suite. More...
 
static CU_ErrorCode run_single_test (CU_pTest pTest, CU_pRunSummary pRunSummary)
 Runs a specific test. More...
 
static void add_failure (CU_pFailureRecord *ppFailure, CU_pRunSummary pRunSummary, CU_FailureType type, unsigned int uiLineNumber, const char *szCondition, const char *szFileName, CU_pSuite pSuite, CU_pTest pTest)
 Records a runtime failure. More...
 
static int get_index (const char ch)
 Checks whether a character is a special xml character. More...
 

Variables

static CU_ErrorCode g_error_number = CUE_SUCCESS
 Local variable holding the current error code. More...
 
static CU_ErrorAction g_error_action = CUEA_IGNORE
 Local variable holding the current error action code. More...
 
static CU_pTestRegistry f_pTestRegistry = NULL
 The active internal Test Registry. More...
 
static CU_BOOL f_bTestIsRunning = CU_FALSE
 Flag for whether a test run is in progress.
 
static CU_pSuite f_pCurSuite = NULL
 Pointer to the suite currently being run. More...
 
static CU_pTest f_pCurTest = NULL
 Pointer to the test currently being run. More...
 
static CU_RunSummary f_run_summary = {"", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
 CU_RunSummary to hold results of each test run. More...
 
static CU_pFailureRecord f_failure_list = NULL
 CU_pFailureRecord to hold head of failure record list of each test run. More...
 
static CU_pFailureRecord f_last_failure = NULL
 CU_pFailureRecord to hold head of failure record list of each test run. More...
 
static CU_BOOL f_failure_on_inactive = CU_TRUE
 Flag for whether inactive suites/tests are treated as failures. More...
 
static clock_t f_start_time
 Variable for storage of start time for test run. More...
 

Detailed Description

Macro Definition Documentation

◆ add_test_case

#define add_test_case (   group,
  name,
  test 
)    CU_add_test(group, name, test)

Deprecated (version 1).

Deprecated:
Use CU_add_test().

◆ add_test_group

#define add_test_group (   name,
  init,
  clean 
)    CU_add_suite(name, init, clean)

Deprecated (version 1).

Deprecated:
Use CU_add_suite().

◆ ADD_TEST_TO_GROUP

#define ADD_TEST_TO_GROUP (   group,
  test 
)    (CU_add_test(group, #test, (CU_TestFunc)test))

Deprecated (version 1).

Deprecated:
Use ADD_TEST_TO_SUITE.

◆ cleanup_registry

#define cleanup_registry ( )    CU_cleanup_registry()

Deprecated (version 1).

Deprecated:
Use CU_cleanup_registry().

◆ compare_strings

#define compare_strings (   src,
  dest 
)    CU_compare_strings(src, dest)

Deprecated (version 1).

Deprecated:
Use CU_compare_strings().

◆ CU_ADD_TEST

#define CU_ADD_TEST (   suite,
  test 
)    (CU_add_test(suite, #test, (CU_TestFunc)test))

Shortcut macro for adding a test to a suite.

◆ CU_CALLOC

#define CU_CALLOC (   x,
 
)    calloc((x), (y))

Standard calloc() if MEMTRACE not defined.

Referenced by run_single_test().

◆ CU_CREATE_MEMORY_REPORT

#define CU_CREATE_MEMORY_REPORT (   x)

No-op if MEMTRACE not defined.

Referenced by CU_cleanup_registry().

◆ CU_DUMP_MEMORY_USAGE

#define CU_DUMP_MEMORY_USAGE (   x)

No-op if MEMTRACE not defined.

◆ CU_FREE

#define CU_FREE (   x)    free((x))

◆ CU_MALLOC

#define CU_MALLOC (   x)    malloc((x))

◆ CU_REALLOC

#define CU_REALLOC (   x,
 
)    realloc((x), (y))

Standard realloc() if MEMTRACE not defined.

◆ CU_SKIP_IF

#define CU_SKIP_IF (   value)    { CU_SkipImplementation((value), __LINE__, ("CU_SKIP_IF(" #value ")"), __FILE__, ""); }

Skip the current suite or test if true.

◆ CU_SUITE_INFO_NULL

#define CU_SUITE_INFO_NULL   { NULL, NULL, NULL, NULL, NULL, NULL }

NULL CU_suite_info_t to terminate arrays of suites.

Referenced by CU_get_test_by_index().

◆ CU_TEST_INFO_NULL

#define CU_TEST_INFO_NULL   { NULL, NULL }

NULL CU_test_info_t to terminate arrays of tests.

Referenced by CU_get_test_by_index().

◆ CUNIT_MAX_ENTITY_LEN

#define CUNIT_MAX_ENTITY_LEN   5

Maximum number of characters in a translated xml entity.

◆ CUNIT_MAX_STRING_LENGTH

#define CUNIT_MAX_STRING_LENGTH   1024

Maximum string length.

◆ get_error

#define get_error ( )    CU_get_error_msg()

Deprecated (version 1).

Deprecated:
Use CU_get_error_msg().

◆ get_group_by_name

#define get_group_by_name (   group,
  reg 
)    CU_get_suite_by_name(group, reg)

Deprecated (version 1).

Deprecated:
Use CU_get_suite_by_name().

◆ get_registry

#define get_registry ( )    CU_get_registry()

Deprecated (version 1).

Deprecated:
Use CU_get_registry().

◆ get_test_by_name

#define get_test_by_name (   test,
  group 
)    CU_get_test_by_name(test, group)

Deprecated (version 1).

Deprecated:
Use CU_get_test_by_name().

◆ initialize_registry

#define initialize_registry ( )    CU_initialize_registry()

Deprecated (version 1).

Deprecated:
Use CU_initialize_registry().

◆ set_registry

#define set_registry (   reg)    CU_set_registry((reg))

Deprecated (version 1).

Deprecated:
Use CU_set_registry().

◆ TEST_CASE_NULL

#define TEST_CASE_NULL   { NULL, NULL }

Deprecated (version 1).

Deprecated:
Use CU_TEST_INFO_NULL.

◆ TEST_GROUP_NULL

#define TEST_GROUP_NULL   { NULL, NULL, NULL, NULL }

Deprecated (version 1).

Deprecated:
Use CU_TEST_GROUP_NULL.

◆ test_group_register

#define test_group_register (   tg)    CU_register_suites(tg)

Deprecated (version 1).

Deprecated:
Use CU_register_suites().

◆ translate_special_characters

#define translate_special_characters (   src,
  dest,
  len 
)    CU_translate_special_characters(src, dest, len)

Deprecated (version 1).

Deprecated:
Use CU_translate_special_characters().

◆ trim

#define trim (   str)    CU_trim(str)

Deprecated (version 1).

Deprecated:
Use CU_trim().

◆ trim_left

#define trim_left (   str)    CU_trim_left(str)

Deprecated (version 1).

Deprecated:
Use CU_trim_left().

◆ trim_right

#define trim_right (   str)    CU_trim_right(str)

Deprecated (version 1).

Deprecated:
Use CU_trim_right().

Typedef Documentation

◆ _TestCase

typedef CU_Test _TestCase

Deprecated (version 1).

Deprecated:
Use CU_Test.

◆ _TestGroup

Deprecated (version 1).

Deprecated:
Use CU_Suite.

◆ _TestRegistry

Deprecated (version 1).

Deprecated:
Use CU_TestRegistry.

◆ _TestResult

◆ CleanupFunc

Deprecated (version 1).

Deprecated:
Use CU_CleanupFunc.

◆ CU_AllTestsCompleteMessageHandler

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.

◆ CU_CleanupFunc

typedef int(* CU_CleanupFunc) (void)

Signature for suite cleanup function.

◆ CU_ErrorAction

CUnit error action codes.

These are used to set the action desired when an error condition is detected in the CUnit framework.

See also
CU_set_error_action()
CU_get_error_action()

◆ CU_FailureRecord

Data type for holding assertion failure information (linked list).

◆ CU_FailureType

Types of failures occurring during test runs.

Failure type.

◆ CU_InitializeFunc

typedef int(* CU_InitializeFunc) (void)

Signature for suite initialization function.

◆ CU_pFailureRecord

Pointer to CU_FailureRecord.

◆ CU_pRunSummary

Pointer to CU_RunSummary.

◆ CU_pSuite

typedef CU_Suite* CU_pSuite

Pointer to a CUnit suite.

◆ CU_pSuiteInfo

Pointer to CU_SuiteInfo type.

◆ CU_pTest

typedef CU_Test* CU_pTest

Pointer to a CUnit test case.

◆ CU_pTestInfo

Pointer to CU_TestInfo type.

◆ CU_pTestRegistry

Pointer to a CUnit test registry.

◆ CU_RunSummary

typedef struct CU_RunSummary CU_RunSummary

Data type for holding statistics and assertion failures for a test run.

◆ CU_SetUpFunc

typedef void(* CU_SetUpFunc) (void)

Signature for a test SetUp function.

◆ CU_Suite

typedef struct CU_Suite CU_Suite

CUnit suite data type.

CU_Suite is a linked list of CU_Test containers. Each suite has a name, a count of registered unit tests, and a flag for whether the suite is active during test runs. It also holds pointers to optional initialization and cleanup functions. If non-NULL, these are called before and after running the suite's tests, respectively. In addition, the suite holds a pointer to the head of the linked list of associated CU_Test objects. Finally, pointers to the next and previous suites in the linked list are maintained.

Generally, the linked list includes suites which are associated with each other in a CU_TestRegistry. As a result, suites are run in the order in which they are registered (see CU_add_suite()).

It is recommended that name of each CU_Suite in a test registry have a unique name. Otherwise, only the first-registered suite having a given name will be accessible by name. There are no restrictions on the contained tests. This means that the same CU_Test could, in principle, be run more than once fron different suites.

See also
CU_Test
CU_TestRegistry

◆ CU_SuiteCleanupFailureMessageHandler

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.

◆ CU_SuiteCompleteMessageHandler

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.

◆ CU_SuiteInfo

typedef struct CU_SuiteInfo CU_SuiteInfo

Suite parameters.

This data type is provided to assist CUnit users manage collections of tests and suites. It is intended to be used to build arrays of suite parameters that can be passed to a bulk registration function such as CU_register_suite() or CU_register_suites().

◆ CU_SuiteInitFailureMessageHandler

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.

◆ CU_SuiteStartMessageHandler

typedef void(* CU_SuiteStartMessageHandler) (const CU_pSuite pSuite)

Message handler called at the start of a suite.

pSuite will not be null.

◆ CU_TearDownFunc

typedef void(* CU_TearDownFunc) (void)

Signature for a test TearDown function.

◆ CU_Test

typedef struct CU_Test CU_Test

CUnit test case data type.

CU_Test is a double linked list of unit tests. Each test has a name, a callable test function, and a flag for whether the test is active and thus executed during a test run. A test also holds links to the next and previous tests in the list, as well as a jmp_buf reference for use in implementing fatal assertions.

Generally, the linked list includes tests which are associated with each other in a CU_Suite. As a result, tests are run in the order in which they are added to a suite (see CU_add_test()).

It is recommended that the name of each CU_Test in a suite have a unique name. Otherwise, only the first-registered test having a given name will be accessible by that name. There are no restrictions on the test function. This means that the same function could, in principle, be called more than once from different tests.

See also
CU_Suite
CU_TestRegistry

◆ CU_TestCompleteMessageHandler

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.

◆ CU_TestFunc

typedef void(* CU_TestFunc) (void)

Signature for a testing function in a test case.

◆ CU_TestInfo

typedef struct CU_TestInfo CU_TestInfo

Test case parameters structure.

This data type is provided to assist CUnit users manage collections of tests and suites. It is intended to be used to build arrays of test case parameters that can be then be referred to in a CU_suite_info_t variable.

◆ CU_TestRegistry

CUnit test registry data type.

CU_TestRegisty is the repository for suites containing unit tests. The test registry maintains a count of the number of CU_Suite objects contained in the registry, as well as a count of the total number of CU_Test objects associated with those suites. It also holds a pointer to the head of the linked list of CU_Suite objects.

With this structure, the user will normally add suites implictly to the internal test registry using CU_add_suite(), and then add tests to each suite using CU_add_test(). Test runs are then initiated using one of the appropriate functions in TestRun.c via one of the user interfaces.

Automatic creation and destruction of the internal registry and its objects is available using CU_initialize_registry() and CU_cleanup_registry(), respectively. For internal and testing purposes, the internal registry can be retrieved and assigned. Functions are also provided for creating and destroying independent registries.

Note that earlier versions of CUnit also contained a pointer to a linked list of CU_FailureRecord objects (termed _TestResults). This has been removed from theregistry and relocated to TestRun.c.

See also
CU_Test
CU_Suite
CU_initialize_registry()
CU_cleanup_registry()
CU_get_registry()
CU_set_registry()
CU_create_new_registry()
CU_destroy_existing_registry()

◆ CU_TestSkippedMessageHandler

typedef void(* CU_TestSkippedMessageHandler) (const CU_pTest pTest, const CU_pSuite pSuite)

Message handler called when a test is skipped.

The parameters are the test and suite being skipped. The message handler will be called when the test is marked as inactive inside an active suite or when the whole suite is marked as inactive. Neither pTest nor pSuite may be null.

◆ CU_TestStartMessageHandler

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.

◆ InitializeFunc

Deprecated (version 1).

Deprecated:
Use CU_InitializeFunc.

◆ PTestCase

Deprecated (version 1).

Deprecated:
Use CU_pTest.

◆ PTestGroup

Deprecated (version 1).

Deprecated:
Use CU_pSuite.

◆ PTestRegistry

Deprecated (version 1).

Deprecated:
Use CU_pTestRegistry.

◆ PTestResult

Deprecated:
Use CU_pFailureRecord.

◆ test_case_t

Deprecated (version 1).

Deprecated:
Use CU_TestInfo.

◆ test_group_t

Deprecated (version 1).

Deprecated:
Use CU_SuiteInfo.

◆ test_suite_t

typedef struct test_suite test_suite_t

Deprecated (version 1).

Deprecated:
Use CU_SuiteInfo and CU_TestInfo.

◆ TestFunc

Deprecated (version 1).

Deprecated:
Use CU_TestFunc.

Enumeration Type Documentation

◆ CU_ErrorAction

CUnit error action codes.

These are used to set the action desired when an error condition is detected in the CUnit framework.

See also
CU_set_error_action()
CU_get_error_action()
Enumerator
CUEA_IGNORE 

Runs should be continued when an error condition occurs (if possible).

CUEA_FAIL 

Runs should be stopped when an error condition occurs.

CUEA_ABORT 

The application should exit() when an error conditions occurs.

◆ CU_ErrorCode

CUnit error codes.

If codes are added or removed, be sure to make a change to the error messages in CUError.c/get_error_desc().

See also
CU_set_error()
CU_get_error()
CU_get_error_msg()
Enumerator
CUE_SUCCESS 

No error condition.

CUE_NOMEMORY 

Memory allocation failed.

CUE_NOREGISTRY 

Test registry not initialized.

CUE_REGISTRY_EXISTS 

Attempt to CU_set_registry() without CU_cleanup_registry().

CUE_NOSUITE 

A required CU_pSuite pointer was NULL.

CUE_NO_SUITENAME 

Required CU_Suite name not provided.

CUE_SINIT_FAILED 

Suite initialization failed.

CUE_SCLEAN_FAILED 

Suite cleanup failed.

CUE_DUP_SUITE 

Duplicate suite name not allowed.

CUE_SUITE_INACTIVE 

Test run initiated for an inactive suite.

CUE_NOTEST 

A required CU_pTest or CU_TestFunc pointer was NULL.

CUE_NO_TESTNAME 

Required CU_Test name not provided.

CUE_DUP_TEST 

Duplicate test case name not allowed.

CUE_TEST_NOT_IN_SUITE 

Test not registered in specified suite.

CUE_TEST_INACTIVE 

Test run initiated for an inactive test.

CUE_FOPEN_FAILED 

An error occurred opening a file.

CUE_FCLOSE_FAILED 

An error occurred closing a file.

CUE_BAD_FILENAME 

A bad filename was requested (NULL, empty, nonexistent, etc.).

CUE_WRITE_ERROR 

An error occurred during a write to a file.

◆ CU_FailureTypes

Types of failures occurring during test runs.

Enumerator
CUF_SuiteInactive 

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.

Function Documentation

◆ add_failure()

static void add_failure ( CU_pFailureRecord ppFailure,
CU_pRunSummary  pRunSummary,
CU_FailureType  type,
unsigned int  uiLineNumber,
const char *  szCondition,
const char *  szFileName,
CU_pSuite  pSuite,
CU_pTest  pTest 
)
static

Records a runtime failure.

This function is called whenever a runtime failure occurs. This includes user assertion failures, suite initialization and cleanup failures, and inactive suites/tests when set as failures. This function records the details of the failure in a new failure record in the linked list of runtime failures.

Parameters
ppFailurePointer to head of linked list of failure records to append with new failure record. If it points to a NULL pointer, it will be set to point to the new failure record.
pRunSummaryPointer to CU_RunSummary keeping track of failure records (ignored if NULL).
typeType of failure.
uiLineNumberLine number of the failure, if applicable.
szConditionDescription of failure condition
szFileNameName of file, if applicable
pSuiteThe suite being run at time of failure
pTestThe test being run at time of failure

References CU_FREE, CU_MALLOC, CU_FailureRecord::pNext, CU_FailureRecord::pPrev, CU_FailureRecord::pSuite, CU_FailureRecord::pTest, CU_FailureRecord::strCondition, CU_FailureRecord::strFileName, CU_FailureRecord::type, and CU_FailureRecord::uiLineNumber.

Referenced by CU_assertImplementation(), and CU_run_test().

◆ cleanup_failure_list()

static void cleanup_failure_list ( CU_pFailureRecord ppFailure)
static

Frees all memory allocated for the linked list of test failure records.

pFailure is reset to NULL after its list is cleaned up.

Parameters
ppFailurePointer to head of linked list of CU_pFailureRecords to clean.
See also
CU_clear_previous_results()

References CU_FREE, CU_FailureRecord::pNext, CU_FailureRecord::strCondition, and CU_FailureRecord::strFileName.

Referenced by clear_previous_results().

◆ cleanup_suite()

static void cleanup_suite ( CU_pSuite  pSuite)
static

Internal function to clean up the specified test suite.

Each test case registered with pSuite will be freed. Allocated memory held by the suite (i.e. the name) will also be deallocated. Severe problems can occur if this function is called during a test run involving pSuite.

Parameters
pSuiteCU_pSuite to clean up (non-NULL).
See also
cleanup_test_registry()
cleanup_test()

References cleanup_test(), CU_FREE, CU_Suite::pCleanupFuncTest, CU_Suite::pInitializeFuncTest, CU_Suite::pName, CU_Test::pNext, CU_Suite::pTest, and CU_Suite::uiNumberOfTests.

Referenced by cleanup_test_registry(), and CU_get_test_by_index().

◆ cleanup_test()

static void cleanup_test ( CU_pTest  pTest)
static

Internal function to clean up the specified test.

All memory associated with the test will be freed. Severe problems can occur if this function is called during a test run involving pTest.

Parameters
pTestCU_pTest to clean up (non-NULL).
See also
cleanup_test_registry()
cleanup_suite()

References CU_FREE, and CU_Test::pName.

Referenced by cleanup_suite(), and CU_get_test_by_index().

◆ cleanup_test_registry()

static void cleanup_test_registry ( CU_pTestRegistry  pRegistry)
static

Internal function to clean up the specified test registry.

cleanup_suite() will be called for each registered suite to perform cleanup of the associated test cases. Then, the suite's memory will be freed. Note that any pointers to tests or suites in pRegistry held by the user will be invalidated by this function. Severe problems can occur if this function is called during a test run involving pRegistry. Note that memory held for data members in the registry (e.g. pName) and the registry itself are not freed by this function.

See also
cleanup_suite()
cleanup_test()
Parameters
pRegistryCU_pTestRegistry to clean up (non-NULL).

References cleanup_suite(), CU_FREE, CU_Suite::pNext, CU_TestRegistry::pSuite, CU_TestRegistry::uiNumberOfSuites, and CU_TestRegistry::uiNumberOfTests.

Referenced by CU_destroy_existing_registry(), and CU_get_test_by_index().

◆ clear_previous_results()

static void clear_previous_results ( CU_pRunSummary  pRunSummary,
CU_pFailureRecord ppFailure 
)
static

Initializes the run summary information in the specified structure.

Resets the run counts to zero, and calls cleanup_failure_list() if failures were recorded by the last test run. Calling this function multiple times, while inefficient, will not cause an error condition.

Parameters
pRunSummaryCU_RunSummary to initialize (non-NULL).
ppFailureThe failure record to clean (non-NULL).
See also
CU_clear_previous_results()

References cleanup_failure_list(), CU_RunSummary::ElapsedTime, CU_RunSummary::nAsserts, CU_RunSummary::nAssertsFailed, CU_RunSummary::nFailureRecords, CU_RunSummary::nSuitesFailed, CU_RunSummary::nSuitesInactive, CU_RunSummary::nSuitesRun, CU_RunSummary::nTestsFailed, CU_RunSummary::nTestsInactive, and CU_RunSummary::nTestsRun.

Referenced by CU_clear_previous_results(), CU_run_all_tests(), CU_run_suite(), and CU_run_test().

◆ create_suite()

static CU_pSuite create_suite ( const char *  strName,
CU_InitializeFunc  pInit,
CU_CleanupFunc  pClean,
CU_SetUpFunc  pSetup,
CU_TearDownFunc  pTear 
)
static

Internal function to create a new test suite having the specified parameters.

This function creates a new test suite having the specified name and initialization/cleanup functions. The new suite is active for execution during test runs. The strName cannot be NULL (checked by assertion), but either or both function pointers can be. A pointer to the newly-created suite is returned, or NULL if there was an error allocating memory for the new suite. It is the responsibility of the caller to destroy the returned suite (use cleanup_suite() before freeing the returned pointer).

Parameters
strNameName for the new test suite (non-NULL).
pInitInitialization function to call before running suite.
pCleanCleanup function to call after running suite.
Returns
A pointer to the newly-created suite (NULL if creation failed)

References CU_FREE, CU_MALLOC, CU_Suite::fActive, CU_Suite::pCleanupFunc, CU_Suite::pInitializeFunc, CU_Suite::pName, CU_Suite::pNext, CU_Suite::pPrev, CU_Suite::pSetUpFunc, CU_Suite::pTearDownFunc, CU_Suite::pTest, and CU_Suite::uiNumberOfTests.

Referenced by CU_get_test_by_index().

◆ create_test()

static CU_pTest create_test ( const char *  strName,
CU_TestFunc  pTestFunc 
)
static

Internal function to create a new test case having the specified parameters.

This function creates a new test having the specified name and test function. The strName cannot be NULL (checked by assertion), but the function pointer may be. A pointer to the newly-created test is returned, or NULL if there was an error allocating memory for the new test. It is the responsibility of the caller to destroy the returned test (use cleanup_test() before freeing the returned pointer).

Parameters
strNameName for the new test.
pTestFuncTest function to call when running this test.
Returns
A pointer to the newly-created test (NULL if creation failed)

References CU_FREE, CU_MALLOC, CU_Test::fActive, CU_Test::pJumpBuf, CU_Test::pName, CU_Test::pNext, CU_Test::pPrev, and CU_Test::pTestFunc.

Referenced by CU_add_test(), and CU_get_test_by_index().

◆ CU_add_suite()

CU_pSuite CU_add_suite ( const char *  strName,
CU_InitializeFunc  pInit,
CU_CleanupFunc  pClean 
)

Creates a new test suite and adds it to the test registry.

This function creates a new test suite having the specified name and initialization/cleanup functions and adds it to the test registry. The new suite will be active and able to be executed during a test run. The test registry must be initialized before calling this function (checked by assertion). pInit and pClean may be NULL, in which case no corresponding initialization of cleanup function will be called when the suite is run. strName may be empty ("") but may not be NULL.

The return value is a pointer to the newly-created suite, or NULL if there was a problem with the suite creation or addition. An error code is also set for the framework. Note that if the name specified for the new suite is a duplicate, the suite will be created and added but the error code will be set to CUE_DUP_SUITE. The duplicate suite will not be accessible by name.

NOTE - the CU_pSuite pointer returned should NOT BE FREED BY THE USER. The suite is freed by the CUnit system when CU_cleanup_registry() is called. This function must not be called during a test run (checked by assertion).

CU_add_suite() sets the following error codes:

  • CUE_SUCCESS if no errors occurred.
  • CUE_NOREGISTRY if the registry has not been initialized.
  • CUE_NO_SUITENAME if strName is NULL.
  • CUE_DUP_SUITE if a suite having strName is already registered.
  • CUE_NOMEMORY if a memory allocation failed.
Parameters
strNameName for the new test suite (non-NULL).
pInitInitialization function to call before running suite.
pCleanCleanup function to call after running suite.
Returns
A pointer to the newly-created suite (NULL if creation failed)

References CU_add_suite_with_setup_and_teardown().

Referenced by CU_get_test_by_index().

◆ CU_add_suite_with_setup_and_teardown()

CU_pSuite CU_add_suite_with_setup_and_teardown ( const char *  strName,
CU_InitializeFunc  pInit,
CU_CleanupFunc  pClean,
CU_SetUpFunc  pSetup,
CU_TearDownFunc  pTear 
)

The same as CU_add_suite but also adds setup and tear down callbacks for each test in this suite.

Parameters
pSetupSetUp function to call before running each test.
pTearTearDown function to call after running each test.

References CUE_SUCCESS.

Referenced by CU_add_suite(), CU_CI_add_suite(), and CU_register_nsuites().

◆ CU_add_test()

CU_pTest CU_add_test ( CU_pSuite  pSuite,
const char *  strName,
CU_TestFunc  pTestFunc 
)

This function creates a new test having the specified name and function, and adds it to the specified suite.

The new test is active and able to be executed during a test run. At present, there is no mechanism for creating a test case independent of a suite. Neither pSuite, strName, nor pTestFunc may be NULL.

The return value is a pointer to the newly-created test, or NULL if there was a problem with the test creation or addition. An error code is also set for the framework. Note that if the name specified for the new test is a duplicate within pSuite, the test will be created and added but the error code will be set to CUE_DUP_TEST. The duplicate test will not be accessible by name.

NOTE - the CU_pTest pointer returned should NOT BE FREED BY THE USER. The test is freed by the CUnit system when CU_cleanup_registry() is called. This function must not be called during a test run (checked by assertion).

CU_add_test() sets the following error codes:

  • CUE_SUCCESS if no errors occurred.
  • CUE_NOREGISTRY if the registry has not been initialized.
  • CUE_NOSUITE if pSuite is NULL.
  • CUE_NO_TESTNAME if strName is NULL.
  • CUE_NOTEST if pTestFunc is NULL.
  • CUE_DUP_TEST if a test having strName is already registered to pSuite.
  • CUE_NOMEMORY if a memory allocation failed.

Parameters
pSuiteTest suite to which to add new test (non-NULL).
strNameName for the new test case (non-NULL).
pTestFunction to call when running the test (non-NULL).
Returns
A pointer to the newly-created test (NULL if creation failed)

References create_test(), CU_is_test_running(), CU_set_error(), CUE_DUP_TEST, CUE_NO_TESTNAME, CUE_NOMEMORY, CUE_NOREGISTRY, CUE_NOSUITE, CUE_NOTEST, CUE_SUCCESS, insert_test(), test_exists(), and CU_TestRegistry::uiNumberOfTests.

Referenced by CU_CI_add_test(), CU_get_test_by_index(), and CU_register_nsuites().

◆ CU_assertImplementation()

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.

Parameters
bValueValue of the assertion (CU_TRUE or CU_FALSE).
uiLineLine number of failed test statement.
strConditionString containing logical test that failed.
strFileSource file where test statement failed.
strFunctionFunction where test statement failed.
bFatalCU_TRUE to abort test (via longjmp()), CU_FALSE to continue test.
Returns
As a convenience, returns the value of the assertion (i.e. bValue).

References add_failure(), CUF_AssertFailed, CU_Suite::fCleanupError, CU_Suite::fInClean, CU_Suite::fInSetUp, CU_Suite::fSetUpError, CU_RunSummary::nAsserts, CU_RunSummary::nAssertsFailed, and CU_Test::pJumpBuf.

◆ CU_cleanup_registry()

void CU_cleanup_registry ( void  )

Clears the test registry.

The active test registry is freed, including all stored suites and associated tests. The most recent stored test results are also cleared. After calling this function, CUnit suites cannot be added until CU_initialize_registry() or CU_set_registry() is called. Further, any pointers to suites or test cases held by the user will be invalidated by calling this function.

This function may be called multiple times without generating an error condition. However, this function must not be called during a test run (checked by assertion)

.

See also
CU_initialize_registry
CU_get_registry
CU_set_registry

References CU_clear_previous_results(), CU_CREATE_MEMORY_REPORT, CU_destroy_existing_registry(), CU_is_test_running(), CU_set_error(), and CUE_SUCCESS.

Referenced by CU_get_test_by_index(), and CU_initialize_registry().

◆ CU_clear_previous_results()

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 also
clear_previous_results()

References clear_previous_results().

Referenced by CU_cleanup_registry().

◆ CU_compare_strings()

int CU_compare_strings ( const char *  szSrc,
const char *  szDest 
)

Case-insensitive string comparison.

Neither string pointer can be NULL (checked by assertion).

Parameters
szSrc1st string to compare (non-NULL).
szDest2nd string to compare (non-NULL).
Returns
0 if the strings are equal, non-zero otherwise.

Referenced by CU_get_basename(), CU_get_suite_by_name(), CU_get_test_by_name(), suite_exists(), and test_exists().

◆ CU_count_all_failures()

int CU_count_all_failures ( CU_pTestRegistry  pRegistry)

Count the number of failed tests overall.

Returns

References CU_count_suite_failures(), CU_Suite::pNext, and CU_TestRegistry::pSuite.

◆ CU_count_all_tests()

int CU_count_all_tests ( CU_pTestRegistry  pRegistry)

Count the number of tests in a suite.

Returns

References CU_TestRegistry::pSuite.

◆ CU_count_suite_failures()

int CU_count_suite_failures ( CU_pSuite  pSuite)

Count the number of failed tests in a suite.

Returns

References CU_iterate_test_failures(), CU_Test::pNext, and CU_Suite::pTest.

Referenced by CU_count_all_failures().

◆ CU_count_test_failures()

int CU_count_test_failures ( CU_pTest  pTest)

Count the number of failures from the given test.

Returns

References CU_iterate_test_failures().

◆ CU_create_new_registry()

CU_pTestRegistry CU_create_new_registry ( void  )

Creates and initializes a new test registry.

Returns a pointer to a new, initialized registry (NULL if memory could not be allocated). It is the caller's responsibility to destroy and free the new registry (unless it is made the active test registry using CU_set_registry()).

References CU_MALLOC, CU_TestRegistry::pSuite, CU_TestRegistry::uiNumberOfSuites, and CU_TestRegistry::uiNumberOfTests.

Referenced by CU_get_test_by_index(), and CU_initialize_registry().

◆ CU_destroy_existing_registry()

void CU_destroy_existing_registry ( CU_pTestRegistry ppRegistry)

Destroys and frees all memory for an existing test registry.

The active test registry is destroyed by the CUnit system in CU_cleanup_registry(), so only call this function on registries created or held independently of the internal CUnit system.

Once a registry is made the active test registry using CU_set_registry(), its destruction will be handled by the framework. ppRegistry may not be NULL (checked by assertion), but *ppRegistry can be NULL (in which case the function has no effect). Note that *ppRegistry will be set to NULL on return.

Parameters
ppRegistryAddress of a pointer to the registry to destroy (non-NULL).

References cleanup_test_registry(), and CU_FREE.

Referenced by CU_cleanup_registry(), and CU_get_test_by_index().

◆ CU_get_all_test_complete_handler()

CU_EXPORT CU_AllTestsCompleteMessageHandler CU_get_all_test_complete_handler ( void  )

Retrieves the message handler called after all tests are run.

◆ CU_get_basename()

const char * CU_get_basename ( const char *  path)

Given a file path, return a pointer to the last component (the basename).

If on windows, the result will not contain ".exe"

References CU_compare_strings(), CU_number_width(), CU_translate_special_characters(), CU_translated_strlen(), CU_trim(), CU_trim_left(), and CU_trim_right().

◆ CU_get_current_suite()

CU_pSuite CU_get_current_suite ( void  )

Retrieves a pointer to the currently-running suite (NULL if none).

References f_pCurSuite.

◆ CU_get_current_test()

CU_pTest CU_get_current_test ( void  )

Retrievea a pointer to the currently-running test (NULL if none).

References f_pCurTest.

◆ CU_get_elapsed_time()

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.

References CU_RunSummary::ElapsedTime, f_bTestIsRunning, and f_start_time.

◆ CU_get_error()

CU_ErrorCode CU_get_error ( void  )

Retrieves the current CUnit framework error code.

CUnit implementation functions set the error code to indicate the status of the most recent operation. In general, the CUnit functions will clear the code to CUE_SUCCESS, then reset it to a specific error code if an exception condition is encountered. Some functions return the code, others leave it to the user to inspect if desired.

Returns
The current error condition code.
See also
CU_get_error_msg()
CU_ErrorCode

References g_error_number.

Referenced by CU_get_test_by_index(), CU_register_nsuites(), initialize_result_file(), and uninitialize_result_file().

◆ CU_get_error_action()

CU_ErrorAction CU_get_error_action ( void  )

Retrieves the current framework error action code.

Returns
The current error action code.
See also
CU_set_error_action()
CU_set_error()
CU_ErrorAction

References g_error_action.

Referenced by CU_run_all_tests().

◆ CU_get_error_msg()

const char * CU_get_error_msg ( void  )

Retrieves a message corresponding to the current framework error code.

CUnit implementation functions set the error code to indicate the of the most recent operation. In general, the CUnit functions will clear the code to CUE_SUCCESS, then reset it to a specific error code if an exception condition is encountered. This function allows the user to retrieve a descriptive error message corresponding to the error code set by the last operation.

Returns
A message corresponding to the current error condition.
See also
CU_get_error()
CU_ErrorCode

References g_error_number, and get_error_desc().

◆ CU_get_fail_on_inactive()

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.

Returns
CU_TRUE if inactive suites/tests are failures, CU_FALSE if not.
See also
CU_set_fail_on_inactive()

References f_failure_on_inactive.

◆ CU_get_failure_list()

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().

References f_failure_list.

Referenced by CU_iterate_test_failures(), and show_failures().

◆ CU_get_number_of_asserts()

unsigned int CU_get_number_of_asserts ( void  )

Retrieves the number of assertions processed during the last run (reset each run).

References CU_RunSummary::nAsserts.

◆ CU_get_number_of_failure_records()

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.

References CU_RunSummary::nFailureRecords.

Referenced by show_failures().

◆ CU_get_number_of_failures()

unsigned int CU_get_number_of_failures ( void  )

Retrieves the number of failed assertions during the last run (reset each run).

References CU_RunSummary::nAssertsFailed.

◆ CU_get_number_of_successes()

unsigned int CU_get_number_of_successes ( void  )

Retrieves the number of successful assertions during the last run (reset each run).

References CU_RunSummary::nAsserts, and CU_RunSummary::nAssertsFailed.

◆ CU_get_number_of_suites_failed()

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).

References CU_RunSummary::nSuitesFailed.

◆ CU_get_number_of_suites_inactive()

unsigned int CU_get_number_of_suites_inactive ( void  )

Retrieves the number of inactive suites found during the previous run (reset each run).

References CU_RunSummary::nSuitesInactive.

◆ CU_get_number_of_suites_run()

unsigned int CU_get_number_of_suites_run ( void  )

Retrieves the number of suites completed during the previous run (reset each run).

References CU_RunSummary::nSuitesRun.

◆ CU_get_number_of_tests_failed()

unsigned int CU_get_number_of_tests_failed ( void  )

Retrieves the number of tests containing failed assertions during the previous run (reset each run).

References CU_RunSummary::nTestsFailed.

Referenced by curses_test_complete_message_handler().

◆ CU_get_number_of_tests_inactive()

unsigned int CU_get_number_of_tests_inactive ( void  )

Retrieves the number of inactive tests found during the previous run (reset each run).

References CU_RunSummary::nTestsInactive.

◆ CU_get_number_of_tests_run()

unsigned int CU_get_number_of_tests_run ( void  )

Retrieves the number of tests completed during the previous run (reset each run).

References CU_RunSummary::nTestsRun.

◆ CU_get_registry()

CU_pTestRegistry CU_get_registry ( void  )

Retrieves a pointer to the current test registry.

Returns NULL if the registry has not been initialized using CU_initialize_registry(). Directly accessing the registry should not be necessary for most users. This function is provided primarily for internal and testing purposes.

Returns
A pointer to the current registry (NULL if uninitialized).
See also
CU_initialize_registry
CU_set_registry

References f_pTestRegistry.

Referenced by automated_all_tests_complete_message_handler(), CU_automated_run_tests(), CU_basic_run_tests(), CU_get_run_results_string(), CU_get_test_by_index(), CU_list_tests_to_file(), CU_run_all_tests(), curses_registry_level_run(), curses_suite_level_run(), list_suites(), select_suite(), and test_initialize().

◆ CU_get_run_results_string()

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.

Returns
A new string containing the run summary (owned by caller).

References CU_get_registry(), CU_MALLOC, and f_run_summary.

Referenced by CU_print_run_results().

◆ CU_get_run_summary()

CU_pRunSummary CU_get_run_summary ( void  )

Count the number of tests in all suites.

Returns
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.

References f_run_summary.

Referenced by automated_all_tests_complete_message_handler().

◆ CU_get_suite()

CU_pSuite CU_get_suite ( const char *  strName)

Retrieves the suite having the specified name.

Searches the active test registry and returns a pointer to the 1st suite found. NULL is returned if no suite having the specified name is found. In addition, the framework error state is set to CUE_NOREGISTRY if the registry is not initialized or to CUE_NO_SUITENAME if strName is NULL. If the return value is NULL and framework error state is CUE_SUCCESS, then the search simply failed to find the specified name. Use CU_get_suite_at_pos() to retrieve a suite by position rather than name.

Parameters
strNameThe name of the suite to search for (non-NULL).
Returns
Returns a pointer to the suite, or NULL if not found or an error occurred.
See also
CU_get_suite_at_pos()

References CU_get_suite_by_name(), CU_set_error(), CUE_NO_SUITENAME, CUE_NOREGISTRY, and CUE_SUCCESS.

Referenced by CU_get_test_by_index().

◆ CU_get_suite_at_pos()

CU_pSuite CU_get_suite_at_pos ( unsigned int  pos)

Retrieves the suite at the specified position.

Iterates the active test registry and returns a pointer to the suite at position pos. pos is a 1-based index having valid values [1 .. CU_get_registry()->uiNumberOfSuites] and corresponds to the order in which suites were registered. If pos is invalid or an error occurs, 0 is returned. In addition, the framework error state is set to CUE_NOREGISTRY if the registry is not initialized, or CUE_SUCCESS if pos was invalid. Use CU_get_suite() to retrieve a suite by name rather than position.

Parameters
posThe 1-based position of the suite to fetch.
Returns
Returns a pointer to the suite, or 0 if not found or an error occurred.
See also
CU_get_suite()

References CU_get_suite_by_index(), CU_set_error(), CUE_NOREGISTRY, and CUE_SUCCESS.

Referenced by CU_get_test_by_index().

◆ CU_get_suite_by_index()

CU_pSuite CU_get_suite_by_index ( unsigned int  index,
CU_pTestRegistry  pRegistry 
)

Retrieves a pointer to the suite at the specified (1-based) index.

Iterates pRegistry and returns a pointer to the suite located at the specified index. pRegistry may not be NULL (checked by assertion). Clients should normally use CU_get_suite_at_pos() instead, which automatically searches the active test registry.

Parameters
indexThe 1-based index of the suite to find.
pRegistryThe registry to scan (non-NULL).
Returns
Pointer to the suite at the specified index, or NULL if index is invalid.
See also
CU_get_suite_at_pos()

References CU_Suite::pNext, and CU_TestRegistry::pSuite.

Referenced by CU_get_suite_at_pos(), and CU_get_test_by_index().

◆ CU_get_suite_by_name()

CU_pSuite CU_get_suite_by_name ( const char *  szSuiteName,
CU_pTestRegistry  pRegistry 
)

Retrieves a pointer to the suite having the specified name.

Scans the pRegistry and returns a pointer to the first suite located having the specified name. Neither szSuiteName nor pRegistry may be NULL (checked by assertion). Clients should normally use CU_get_suite() instead, which automatically searches the active test registry.

Parameters
szSuiteNameThe name of the suite to locate (non-NULL).
pRegistryThe registry to scan (non-NULL).
Returns
Pointer to the first suite having the specified name, NULL if not found.
See also
CU_get_suite()

References CU_compare_strings(), CU_Suite::pName, CU_Suite::pNext, and CU_TestRegistry::pSuite.

Referenced by CU_get_suite(), and CU_get_test_by_index().

◆ CU_get_suite_cleanup_failure_handler()

CU_EXPORT CU_SuiteCleanupFailureMessageHandler CU_get_suite_cleanup_failure_handler ( void  )

Retrieves the message handler called when a suite cleanup error occurs.

◆ CU_get_suite_complete_handler()

CU_EXPORT CU_SuiteCompleteMessageHandler CU_get_suite_complete_handler ( void  )

Retrieves the message handler called after each suite is run.

◆ CU_get_suite_duration()

CU_EXPORT double CU_get_suite_duration ( CU_pSuite  pSuite)
Returns
Get the number of seconds this test took to execute.

References CU_Suite::dEnded.

◆ CU_get_suite_init_failure_handler()

CU_EXPORT CU_SuiteInitFailureMessageHandler CU_get_suite_init_failure_handler ( void  )

Retrieves the message handler called when a suite initialization error occurs.

◆ CU_get_suite_pos()

unsigned int CU_get_suite_pos ( CU_pSuite  pSuite)

Looks up the position of the specified suite.

The position is a 1-based index of suites in the active test registry which corresponds to the order in which suites were registered. If pSuite is not found or an error occurs, 0 is returned. In addition, the framework error state is set to CUE_NOREGISTRY if the registry is not initialized, or CUE_NOSUITE if pSuite is NULL. The returned position may be used to retrieve the suite using CU_get_suite_by_pos().

Parameters
pSuitePointer to the suite to find (non-NULL).
Returns
Returns the 1-based position of pSuite in the registry, or NULL if not found or an error occurred.
See also
CU_get_suite_by_pos()
CU_get_suite_pos_by_name()

References CU_set_error(), CUE_NOREGISTRY, CUE_NOSUITE, CUE_SUCCESS, CU_Suite::pNext, and CU_TestRegistry::pSuite.

Referenced by CU_get_test_by_index().

◆ CU_get_suite_pos_by_name()

unsigned int CU_get_suite_pos_by_name ( const char *  strName)

Looks up the position of the suite having the specified name.

The position is a 1-based index of suites in the active test registry which corresponds to the order in which suites were registered. If no suite has the specified name or an error occurs, 0 is returned. In addition, the framework error state is set to CUE_NOREGISTRY if the registry is not initialized, or CUE_NO_SUITENAME if strName is NULL. The search ends at the 1st suite found having name strName. The returned position may be used to retrieve the suite using CU_get_suite_by_pos().

Parameters
strNameName of the suite to find (non-NULL).
Returns
Returns the 1-based position of pSuite in the registry, or NULL if not found or an error occurred.
See also
CU_get_suite_by_pos()
CU_get_suite_pos_by_name()

References CU_set_error(), CUE_NO_SUITENAME, CUE_NOREGISTRY, CUE_SUCCESS, CU_Suite::pName, CU_Suite::pNext, and CU_TestRegistry::pSuite.

Referenced by CU_get_test_by_index().

◆ CU_get_suite_start_handler()

CU_EXPORT CU_SuiteStartMessageHandler CU_get_suite_start_handler ( void  )

Retrieves the message handler called before each suite is run.

◆ CU_get_test()

CU_pTest CU_get_test ( CU_pSuite  pSuite,
const char *  strName 
)

Retrieves the test having the specified name.

Searches pSuite and returns a pointer to the 1st test found named strName. NULL is returned if no test having the specified name is found in pSuite. In addition, the framework error state is set as follows:

  • CUE_NOREGISTRY if the registry is not initialized
  • CUE_NOSUITE if pSuite is NULL
  • CUE_NO_TESTNAME if strName is NULL.

If the return value is NULL and framework error state is CUE_SUCCESS, then the search simply failed to find the specified name. Use CU_get_test_at_pos() to retrieve a test by position rather than name.

Parameters
pSuitePointer to the suite to search (non-NULL).
strNameThe name of the test to search for (non-NULL).
Returns
Returns a pointer to the test, or NULL if not found or an error occurred.
See also
CU_get_test_at_pos()

References CU_get_test_by_name(), CU_set_error(), CUE_NO_SUITENAME, CUE_NOREGISTRY, CUE_NOSUITE, and CUE_SUCCESS.

Referenced by CU_get_test_by_index().

◆ CU_get_test_at_pos()

CU_pTest CU_get_test_at_pos ( CU_pSuite  pSuite,
unsigned int  pos 
)

Retrieves the test at the specified position in pSuite.

Iterates the tests registered in pSuite and returns a pointer to the test at position pos. pos is a 1-based index having valid values [1 .. pSuite->uiNumberOfTests] and corresponds to the order in which tests were added to pSuite. If pos is invalid or an error occurs, 0 is returned. In addition, the framework error state is set as follows:

  • CUE_NOREGISTRY if the registry is not initialized
  • CUE_NOSUITE if pSuite is NULL Use CU_get_test() to retrieve a test by name rather than position.
Parameters
pSuitePointer to the suite to search (non-NULL).
posThe 1-based position of the test to fetch.
Returns
Returns a pointer to the test, or 0 if not found or an error occurred.
See also
CU_get_test()

References CU_get_test_by_index(), CU_set_error(), CUE_NOREGISTRY, CUE_NOSUITE, and CUE_SUCCESS.

Referenced by CU_get_test_by_index().

◆ CU_get_test_by_index()

CU_pTest CU_get_test_by_index ( unsigned int  index,
CU_pSuite  pSuite 
)

Retrieves a pointer to the test at the specified (1-based) index.

Iterates pSuite and returns a pointer to the test located at the specified index. pSuite may not be NULL (checked by assertion). Clients should normally use CU_get_test_at_pos() instead, which automatically searches the active test registry.

Parameters
indexThe 1-based index of the test to find.
pRegistryThe registry to scan (non-NULL).
Returns
Pointer to the test at the specified index, or NULL if index is invalid.
See also
CU_get_test_at_pos()

References cleanup_suite(), cleanup_test(), cleanup_test_registry(), create_suite(), create_test(), CU_add_suite(), CU_add_test(), CU_cleanup_registry(), CU_create_new_registry(), CU_destroy_existing_registry(), CU_FREE, CU_get_error(), CU_get_registry(), CU_get_suite(), CU_get_suite_at_pos(), CU_get_suite_by_index(), CU_get_suite_by_name(), CU_get_suite_pos(), CU_get_suite_pos_by_name(), CU_get_test(), CU_get_test_at_pos(), CU_get_test_by_name(), CU_get_test_pos(), CU_get_test_pos_by_name(), CU_initialize_registry(), CU_register_nsuites(), CU_register_suites(), CU_registry_initialized(), CU_set_error(), CU_set_registry(), CU_set_suite_active(), CU_set_suite_cleanupfunc(), CU_set_suite_initfunc(), CU_set_suite_name(), CU_set_test_active(), CU_set_test_func(), CU_set_test_name(), CU_SUITE_INFO_NULL, CU_TEST_INFO_NULL, CUE_DUP_SUITE, CUE_DUP_TEST, CUE_NO_SUITENAME, CUE_NO_TESTNAME, CUE_NOMEMORY, CUE_NOREGISTRY, CUE_NOSUITE, CUE_NOTEST, CUE_SUCCESS, CU_Test::fActive, CU_Suite::fActive, insert_suite(), insert_test(), CU_Suite::pCleanupFunc, CU_Suite::pInitializeFunc, CU_Test::pJumpBuf, CU_Test::pName, CU_Suite::pName, CU_Test::pNext, CU_Suite::pNext, CU_Test::pPrev, CU_TestRegistry::pSuite, CU_Suite::pTest, CU_Test::pTestFunc, suite_exists(), test_exists(), CU_TestRegistry::uiNumberOfSuites, CU_Suite::uiNumberOfTests, and CU_TestRegistry::uiNumberOfTests.

Referenced by CU_get_test_at_pos().

◆ CU_get_test_by_name()

CU_pTest CU_get_test_by_name ( const char *  szTestName,
CU_pSuite  pSuite 
)

Retrieves a pointer to the test case in pSuite having the specified name.

The first test case in pSuite having the specified name is returned, or NULL if not found. Neither szSuiteName nor pSuite may be NULL (checked by assertion). Clients should normally use CU_get_test() instead.

Parameters
szTestNameThe name of the test case to locate (non-NULL).
pSuiteThe suite to scan (non-NULL).
Returns
Pointer to the first test case having the specified name, NULL if not found.
See also
CU_get_test()

References CU_compare_strings(), CU_Test::pName, CU_Test::pNext, and CU_Suite::pTest.

Referenced by CU_get_test(), and CU_get_test_by_index().

◆ CU_get_test_complete_handler()

CU_EXPORT CU_TestCompleteMessageHandler CU_get_test_complete_handler ( void  )

Retrieves the message handler called after each test is run.

◆ CU_get_test_duration()

CU_EXPORT double CU_get_test_duration ( CU_pTest  pTest)
Returns
Get the number of seconds this test took to execute.

References CU_Test::dEnded.

◆ CU_get_test_pos()

unsigned int CU_get_test_pos ( CU_pSuite  pSuite,
CU_pTest  pTest 
)

Looks up the position of the specified test in pSuite.

The position is a 1-based index of tests in pSuite which corresponds to the order in which tests were added. If pTest is not found or an error occurs, 0 is returned. In addition, the framework error state is set as follows:

  • CUE_NOREGISTRY if the registry is not initialized
  • CUE_NOSUITE if pSuite is NULL
  • CUE_NOTEST if pTest is NULL

The returned position may be used to retrieve the test using CU_get_test_by_pos().

Parameters
pSuitePointer to the suite to search (non-NULL).
pTestPointer to the test to find (non-NULL).
Returns
Returns the 1-based position of pTest in pSuite, or NULL if not found or an error occurred.
See also
CU_get_test_by_pos()
CU_get_test_pos_by_name()

References CU_set_error(), CUE_NOREGISTRY, CUE_NOSUITE, CUE_NOTEST, CUE_SUCCESS, CU_Test::pNext, and CU_Suite::pTest.

Referenced by CU_get_test_by_index().

◆ CU_get_test_pos_by_name()

unsigned int CU_get_test_pos_by_name ( CU_pSuite  pSuite,
const char *  strName 
)

Looks up the position of the test having the specified name in pSuite.

The position is a 1-based index of tests in pSuite which corresponds to the order in which tests were added. If no test has the specified name or an error occurs, 0 is returned. In addition, the framework error state is set as follows:

  • CUE_NOREGISTRY if the registry is not initialized
  • CUE_NOSUITE if pSuite is NULL
  • CUE_NO_TESTNAME if strName is NULL The search ends at the 1st test found having name strName. The returned position may be used to retrieve the suite using CU_get_test_by_pos().
Parameters
pSuitePointer to the suite to search (non-NULL).
strNameName of the test to find (non-NULL).
Returns
Returns the 1-based position of pTest in pSuite, or NULL if not found or an error occurred.
See also
CU_get_test_by_pos()
CU_get_test_pos_by_name()

References CU_set_error(), CUE_NO_TESTNAME, CUE_NOREGISTRY, CUE_NOSUITE, CUE_SUCCESS, CU_Test::pName, CU_Test::pNext, and CU_Suite::pTest.

Referenced by CU_get_test_by_index().

◆ CU_get_test_skipped_handler()

CU_EXPORT CU_TestSkippedMessageHandler CU_get_test_skipped_handler ( void  )

Retrieves the message handler called when a test is skipped.

◆ CU_get_test_start_handler()

CU_EXPORT CU_TestStartMessageHandler CU_get_test_start_handler ( void  )

Retrieves the message handler called before each test is run.

◆ CU_initialize_registry()

CU_ErrorCode CU_initialize_registry ( void  )

Initializes the framework test registry.

Any existing registry is freed, including all stored suites and associated tests. It is not necessary to explicitly call CU_cleanup_registry() before reinitializing the framework. The most recent stored test results are also cleared.

This function must not be called during a test run (checked by assertion)

Returns
CUE_NOMEMORY if memory for the new registry cannot be allocated, CUE_SUCCESS otherwise.
See also
CU_cleanup_registry
CU_get_registry
CU_set_registry
CU_registry_initialized

References CU_cleanup_registry(), CU_create_new_registry(), CU_is_test_running(), CU_set_error(), CUE_NOMEMORY, and CUE_SUCCESS.

Referenced by CU_CI_add_suite(), and CU_get_test_by_index().

◆ CU_iterate_test_failures()

CU_pFailureRecord CU_iterate_test_failures ( CU_pTest  test,
CU_pFailureRecord  previous 
)

Iterate over the recorded failure records of a given test.

Returns

References CU_get_failure_list(), CU_FailureRecord::pNext, and CU_FailureRecord::pTest.

Referenced by CU_count_suite_failures(), and CU_count_test_failures().

◆ CU_print_run_results()

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 '
' characters. file may not be NULL (checked by assertion).

Parameters
filePointer to stream to receive the printed summary (non-NULL).

References CU_FREE, and CU_get_run_results_string().

Referenced by basic_all_tests_complete_message_handler(), and console_all_tests_complete_message_handler().

◆ CU_register_nsuites()

CU_ErrorCode CU_register_nsuites ( int  suite_count,
  ... 
)

Registers multiple suite arrays in CU_SuiteInfo format.

The function accepts a variable number of suite arrays to be registered. The number of arrays is indicated by the value of the 1st argument, suite_count. Each suite in each array is registered with the CUnit test registry, along with all of the associated tests.

Parameters
suite_countThe number of CU_SuiteInfo* arguments to follow.
...suite_count number of CU_SuiteInfo* arguments. NULLs are ignored.
Returns
A CU_ErrorCode indicating the error status.
See also
CU_register_suites()

References CU_add_suite_with_setup_and_teardown(), CU_add_test(), CU_get_error(), CU_SuiteInfo::pCleanupFunc, CU_SuiteInfo::pInitFunc, CU_TestInfo::pName, CU_SuiteInfo::pName, CU_SuiteInfo::pSetUpFunc, CU_SuiteInfo::pTearDownFunc, CU_TestInfo::pTestFunc, and CU_SuiteInfo::pTests.

Referenced by CU_get_test_by_index(), and CU_register_suites().

◆ CU_register_suites()

CU_ErrorCode CU_register_suites ( CU_SuiteInfo  suite_info[])

Registers the suites in a single CU_SuiteInfo array.

Multiple arrays can be registered using CU_register_nsuites().

Parameters
suite_infoNULL-terminated array of CU_SuiteInfo items to register.
Returns
A CU_ErrorCode indicating the error status.
See also
CU_register_suites()

References CU_register_nsuites().

Referenced by CU_get_test_by_index(), and test_suite_register().

◆ CU_registry_initialized()

CU_BOOL CU_registry_initialized ( void  )

Checks whether the test registry has been initialized.

Returns
CU_TRUE if the registry has been initialized, CU_FALSE otherwise.
See also
CU_initialize_registry
CU_cleanup_registry

Referenced by CU_CI_add_suite(), and CU_get_test_by_index().

◆ CU_run_all_tests()

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.

Returns
A CU_ErrorCode indicating the first error condition encountered while running the tests.
See also
CU_run_suite() to run the tests in a specific suite.
CU_run_test() for run a specific test only.

References clear_previous_results(), CU_get_error_action(), CU_get_registry(), CU_set_error(), CUE_NOREGISTRY, CUE_SUCCESS, CUEA_IGNORE, CU_RunSummary::ElapsedTime, f_bTestIsRunning, f_start_time, CU_Suite::pNext, CU_TestRegistry::pSuite, and run_single_suite().

Referenced by automated_run_all_tests(), basic_run_all_tests(), console_run_all_tests(), and curses_run_all_tests().

◆ CU_run_suite()

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.

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()).

Parameters
pSuiteThe suite containing the test (non-NULL)
Returns
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 also
CU_run_all_tests() to run all suites.
CU_run_test() to run a single test in a specific suite.

References clear_previous_results(), CU_set_error(), CUE_NOSUITE, CU_RunSummary::ElapsedTime, f_bTestIsRunning, f_start_time, and run_single_suite().

Referenced by basic_run_suite(), console_run_suite(), and curses_run_suite_tests().

◆ CU_run_test()

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.

Parameters
pSuiteThe suite containing the test (non-NULL)
pTestThe test to run (non-NULL)
Returns
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 also
CU_run_all_tests() to run all tests/suites.
CU_run_suite() to run all tests in a specific suite.

References add_failure(), clear_previous_results(), CUE_NOSUITE, CUE_NOTEST, CUE_SUCCESS, CUF_SuiteInactive, f_failure_on_inactive, CU_Suite::fActive, and CU_RunSummary::nSuitesInactive.

Referenced by basic_run_single_test(), console_run_single_test(), and curses_run_single_test().

◆ CU_set_all_test_complete_handler()

void CU_set_all_test_complete_handler ( CU_AllTestsCompleteMessageHandler  pAllTestsCompleteMessage)

Sets the message handler to call after all tests have been run.

Referenced by test_initialize().

◆ CU_set_error()

void CU_set_error ( CU_ErrorCode  error)

Sets the CUnit framework error code.

This function is used internally by CUnit implementation functions when an error condition occurs within the framework. It should not generally be called by user code. NOTE that if the current error action is CUEA_ABORT, then calling this function will result in exit() being called for the current application.

Parameters
errorCU_ErrorCode indicating the current error condition.
See also
CU_get_error()
CU_get_error_msg()
CU_ErrorCode

References CUE_SUCCESS, CUEA_ABORT, and g_error_action.

Referenced by automated_list_all_tests(), basic_initialize(), CU_add_test(), CU_cleanup_registry(), CU_get_suite(), CU_get_suite_at_pos(), CU_get_suite_pos(), CU_get_suite_pos_by_name(), CU_get_test(), CU_get_test_at_pos(), CU_get_test_by_index(), CU_get_test_pos(), CU_get_test_pos_by_name(), CU_initialize_registry(), CU_run_all_tests(), CU_run_suite(), CU_set_registry(), CU_set_suite_active(), CU_set_suite_cleanupfunc(), CU_set_suite_initfunc(), CU_set_suite_name(), CU_set_test_active(), CU_set_test_func(), CU_set_test_name(), initialize_result_file(), and uninitialize_result_file().

◆ CU_set_error_action()

void CU_set_error_action ( CU_ErrorAction  action)

Sets the action to take when a framework error condition occurs.

This function should be used to specify the action to take when an error condition is encountered. The default action is CUEA_IGNORE, which results in errors being ignored and test runs being continued (if possible). A value of CUEA_FAIL causes test runs to stop as soon as an error condition occurs, while CU_ABORT causes the application to exit on any error.

Parameters
actionCU_ErrorAction indicating the new error action.
See also
CU_get_error_action()
CU_set_error()
CU_ErrorAction

References g_error_action.

◆ CU_set_fail_on_inactive()

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.

Parameters
new_inactiveNew setting for whether to treat inactive suites and tests as failures during a test run (CU_TRUE) or not (CU_FALSE).
See also
CU_get_fail_on_failure()

References f_failure_on_inactive.

◆ CU_set_registry()

CU_pTestRegistry CU_set_registry ( CU_pTestRegistry  pTestRegistry)

Sets the registry to an existing CU_pTestRegistry instance.

A pointer to the original registry is returned. Note that the original registry is not freed, and it becomes the caller's responsibility to do so. Directly accessing the registry should not be necessary for most users. This function is provided primarily for internal and testing purposes.

This function must not be called during a test run (checked by assertion).

Returns
A pointer to the original registry that was replaced.
See also
CU_initialize_registry
CU_cleanup_registry
CU_get_registry

References CU_is_test_running(), CU_set_error(), CUE_SUCCESS, and f_pTestRegistry.

Referenced by automated_run_all_tests(), basic_run_all_tests(), console_run_all_tests(), CU_get_test_by_index(), and curses_run_all_tests().

◆ CU_set_suite_active()

CU_ErrorCode CU_set_suite_active ( CU_pSuite  pSuite,
CU_BOOL  fNewActive 
)

Activates or deactivates a suite.

Only activated suites can be executed during a test run. By default a suite is active upon creation, but can be deactivated by passing it along with CU_FALSE to this function. The suite can be reactivated by passing it along with CU_TRUE. The current value of the active flag is available as pSuite->fActive. If pSuite is NULL then error code CUE_NOSUITE is returned.

Parameters
pSuitePointer to the suite to modify (non-NULL).
fNewActiveIf CU_TRUE then the suite will be activated; if CU_FALSE it will be deactivated.
Returns
Returns CUE_NOSUITE if pSuite is NULL, CUE_SUCCESS if all is well.

References CU_set_error(), CUE_NOSUITE, CUE_SUCCESS, and CU_Suite::fActive.

Referenced by CU_get_test_by_index().

◆ CU_set_suite_cleanup_failure_handler()

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_set_suite_cleanupfunc()

CU_ErrorCode CU_set_suite_cleanupfunc ( CU_pSuite  pSuite,
CU_CleanupFunc  pNewClean 
)

Modifies the cleanup function of a suite.

This function allows the cleanup function associated with a suite to be changed. This is neither recommended nor should it be necessary under most circumstances. However, this function is provided for those clients who need to change the function. The current value of the function is available as pSuite->pCleanupFunc. CUE_SUCCESS is returned if the function succeeds, or CUE_NOSUITE if pSuite is NULL. pNewClean may be NULL, which indicates the suite has no cleanup function.

Parameters
pSuitePointer to the suite to modify (non-NULL).
pNewCleanPointer to function to use to clean up suite.
Returns
Returns CUE_NOSUITE if pSuite is NULL, and CUE_SUCCESS if all is well.

References CU_set_error(), CUE_NOSUITE, CUE_SUCCESS, and CU_Suite::pCleanupFunc.

Referenced by CU_get_test_by_index().

◆ CU_set_suite_complete_handler()

void CU_set_suite_complete_handler ( CU_SuiteCompleteMessageHandler  pSuiteCompleteMessage)

Sets the message handler to call after each suite is run.

◆ CU_set_suite_init_failure_handler()

void CU_set_suite_init_failure_handler ( CU_SuiteInitFailureMessageHandler  pSuiteInitFailureMessage)

Sets the message handler to call when a suite initialization function returns an error.

Referenced by test_initialize().

◆ CU_set_suite_initfunc()

CU_ErrorCode CU_set_suite_initfunc ( CU_pSuite  pSuite,
CU_InitializeFunc  pNewInit 
)

Modifies the initialization function of a suite.

This function allows the initialization function associated with a suite to be changed. This is neither recommended nor should it be necessary under most circumstances. However, this function is provided for those clients who need to change the function. The current value of the function is available as pSuite->pInitializeFunc. CUE_SUCCESS is returned if the function succeeds, or CUE_NOSUITE if pSuite is NULL. pNewInit may be NULL, which indicates the suite has no initialization function.

Parameters
pSuitePointer to the suite to modify (non-NULL).
pNewInitPointer to function to use to initialize suite.
Returns
Returns CUE_NOSUITE if pSuite is NULL, and CUE_SUCCESS if all is well.

References CU_set_error(), CUE_NOSUITE, CUE_SUCCESS, and CU_Suite::pInitializeFunc.

Referenced by CU_get_test_by_index().

◆ CU_set_suite_name()

CU_ErrorCode CU_set_suite_name ( CU_pSuite  pSuite,
const char *  strNewName 
)

Modifies the name of a suite.

This function allows the name associated with a suite to be changed. It is not recommended that a suite name be changed, nor should it be necessary under most circumstances. However, this function is provided for those clients who need to change a suite's name. The current value of the suite's name is available as pSuite->pName. CUE_SUCCESS is returned if the function succeeds in changing the name. CUE_NOSUITE is returned if pSuite is NULL, and CUE_NO_SUITENAME if strNewName is NULL.

Parameters
pSuitePointer to the suite to modify (non-NULL).
strNewNamePointer to string containing new suite name (non-NULL).
Returns
Returns CUE_NOSUITE if pSuite is NULL, CUE_NO_SUITENAME if strNewName is NULL, and CUE_SUCCESS if all is well.

References CU_FREE, CU_MALLOC, CU_set_error(), CUE_NO_SUITENAME, CUE_NOSUITE, CUE_SUCCESS, and CU_Suite::pName.

Referenced by CU_get_test_by_index().

◆ CU_set_suite_start_handler()

void CU_set_suite_start_handler ( CU_SuiteStartMessageHandler  pSuiteStartMessage)

Sets the message handler to call before each suite is run.

◆ CU_set_test_active()

CU_ErrorCode CU_set_test_active ( CU_pTest  pTest,
CU_BOOL  fNewActive 
)

Activates or deactivates a specific test.

Only activated tests can be executed during a test run. By default a test is active upon creation, but can be deactvated by passing it along with CU_FALSE to this function. The test can be reactivated by passing it along with CU_TRUE. The current value of the active flag is available as pTest->fActive. If pTest is NULL then error code CUE_NOTEST is returned. Otherwise CUE_SUCCESS is returned.

Parameters
pTestPointer to the test to modify (non-NULL).
fNewActiveIf CU_TRUE then test will be activated; if CU_FALSE it will be deactivated.
Returns
Returns CUE_NOTEST if pTest is NULL, CUE_SUCCESS if all is well.

References CU_set_error(), CUE_NOTEST, CUE_SUCCESS, and CU_Test::fActive.

Referenced by CU_get_test_by_index().

◆ CU_set_test_complete_handler()

void CU_set_test_complete_handler ( CU_TestCompleteMessageHandler  pTestCompleteMessage)

Sets the message handler to call after each test is run.

Referenced by test_initialize().

◆ CU_set_test_func()

CU_ErrorCode CU_set_test_func ( CU_pTest  pTest,
CU_TestFunc  pNewFunc 
)

Modifies the test function of a test.

This function allows the test function associated with a test to be changed. This is neither recommended nor should it be necessary under most circumstances. However, this function is provided for those clients who need to change the test function. The current value of the test function is available as pTest->pTestFunc. CUE_SUCCESS is returned if the function succeeds, or CUE_NOTEST if either pTest or pNewFunc is NULL.

Parameters
pTestPointer to the test to modify (non-NULL).
pNewFuncPointer to function to use for test function (non-NULL).
Returns
Returns CUE_NOTEST if pTest or pNewFunc is NULL, and CUE_SUCCESS if all is well.

References CU_set_error(), CUE_NOTEST, CUE_SUCCESS, and CU_Test::pTestFunc.

Referenced by CU_get_test_by_index().

◆ CU_set_test_name()

CU_ErrorCode CU_set_test_name ( CU_pTest  pTest,
const char *  strNewName 
)

Modifies the name of a test.

This function allows the name associated with a test to be changed. It is not recommended that a test name be changed, nor should it be necessary under most circumstances. However, this function is provided for those clients who need to change a test's name. The current value of the test's name is available as pTest->pName. CUE_SUCCESS is returned if the function succeeds in changing the name. CUE_NOTEST is returned if pTest is NULL, and CUE_NO_TESTNAME if strNewName is NULL.

Parameters
pTestPointer to the test to modify (non-NULL).
strNewNamePointer to string containing new test name (non-NULL).
Returns
Returns CUE_NOTEST if pTest is NULL, CUE_NO_TESTNAME if strNewName is NULL, and CUE_SUCCESS if all is well.

References CU_FREE, CU_MALLOC, CU_set_error(), CUE_NO_TESTNAME, CUE_NOTEST, CUE_SUCCESS, and CU_Test::pName.

Referenced by CU_get_test_by_index().

◆ CU_set_test_skipped_handler()

void CU_set_test_skipped_handler ( CU_TestSkippedMessageHandler  pTestSkippedMessage)

Sets the message handler to call when a test is skipped.

◆ CU_set_test_start_handler()

void CU_set_test_start_handler ( CU_TestStartMessageHandler  pTestStartMessage)

Sets the message handler to call before each test is run.

Referenced by test_initialize().

◆ CU_SkipImplementation()

void CU_SkipImplementation ( CU_BOOL  bValue,
unsigned int  uiLine,
const char *  strCondition,
const char *  strFile,
const char *  strFunction 
)

Skip Implementation Called to skip execution of current test or current suite.

Parameters
bValueCU_TRUE to skip
uiLineLine number of skip statement.
strConditionString containing logical test that was failed.
strFileSource file where skip happened.
strFunctionFunction where test skip happened.

References CU_Test::fActive, CU_Suite::fActive, CU_Suite::fInSetUp, CU_Test::fSkipped, CU_Suite::fSkipped, CU_RunSummary::nSuitesSkipped, CU_RunSummary::nTestsSkipped, CU_Test::pJumpBuf, and CU_Test::pSkipReason.

◆ CU_translate_special_characters()

size_t CU_translate_special_characters ( const char *  szSrc,
char *  szDest,
size_t  maxlen 
)

Converts special characters in szSrc to xml entity codes and stores result in szDest.

Currently conversion of '&', '<', and '>' is supported. Note that conversion to entities increases the length of the converted string. The greatest conversion size increase would be a string consisting entirely of entity characters of converted length CUNIT_MAX_ENTITY_LEN. Neither szSrc nor szDest may be NULL (checked by assertion).

maxlen gives the maximum number of characters in the translated string. If szDest does not have enough room to hold the converted string, the return value will be zero and szDest will contain an empty string. If this occurs, the remaining characters in szDest may be overwritten in an unspecified manner. It is the caller's responsibility to make sure there is sufficient room in szDest to hold the converted string. CU_translated_strlen() may be used to calculate the length of buffer required (remember to add 1 for the terminating \0).

Parameters
szSrcSource string to convert (non-NULL).
szDestLocation to hold the converted string (non-NULL).
maxlenMaximum number of characters szDest can hold.
Returns
The number of special characters converted (always 0 if szDest did not have enough room to hold converted string).

References get_index().

Referenced by automated_test_complete_message_handler(), automated_test_start_message_handler(), and CU_get_basename().

◆ CU_translated_strlen()

size_t CU_translated_strlen ( const char *  szSrc)

Calculates the length of a translated string.

This function calculates the buffer length required to hold a string after processing with CU_translate_special_characters(). The returned length does not include space for the terminating '\0' character. szSrc may not be NULL (checked by assertion).

Parameters
szSrcSource string to analyze (non-NULL).
Returns
The number of characters szSrc will expand to when converted.

References get_index().

Referenced by automated_test_complete_message_handler(), automated_test_start_message_handler(), and CU_get_basename().

◆ CU_trim()

void CU_trim ( char *  szString)

Trims leading and trailing whitespace from the specified string.

Parameters
szStringThe string to trim.

References CU_trim_left(), and CU_trim_right().

Referenced by CU_get_basename().

◆ CU_trim_left()

void CU_trim_left ( char *  szString)

Trims leading whitespace from the specified string.

Parameters
szStringThe string to trim.

Referenced by CU_get_basename(), and CU_trim().

◆ CU_trim_right()

void CU_trim_right ( char *  szString)

Trims trailing whitespace from the specified string.

Parameters
szStringThe string to trim.

Referenced by CU_get_basename(), and CU_trim().

◆ get_error_desc()

static const char * get_error_desc ( CU_ErrorCode  iError)
static

Internal function to look up the error message for a specified error code.

An empty string is returned if iError is not a member of CU_ErrorCode. If you add an error code to enum CU_ErrorCode, be sure to add a corresponding error message here.

Parameters
iErrorCU_ErrorCode to look up.
Returns
Pointer to a string containing the error message.
See also
CU_get_error_msg()

Referenced by CU_get_error_msg().

◆ get_index()

static int get_index ( const char  ch)
static

Checks whether a character is a special xml character.

This function performs a lookup of the specified character in the CU_bindings structure. If it is a special character, its index into the CU_bindings array is returned. If not, -1 is returned.

Parameters
chThe character to check
Returns
Index into CU_bindings if a special character, -1 otherwise.

Referenced by CU_translate_special_characters(), and CU_translated_strlen().

◆ insert_suite()

static void insert_suite ( CU_pTestRegistry  pRegistry,
CU_pSuite  pSuite 
)
static

Internal function to insert a suite into a registry.

The suite name is assumed to be unique. Internally, the list of suites is a double-linked list, which this function manages. Insertion of NULL pSuites is not allowed (checked by assertion). Severe problems can occur if this function is called during a test run involving pRegistry.

Parameters
pRegistryCU_pTestRegistry to insert into (non-NULL).
pSuiteCU_pSuite to insert (non-NULL).
See also
insert_test()

References CU_Suite::pNext, CU_Suite::pPrev, CU_TestRegistry::pSuite, and CU_TestRegistry::uiNumberOfSuites.

Referenced by CU_get_test_by_index().

◆ insert_test()

static void insert_test ( CU_pSuite  pSuite,
CU_pTest  pTest 
)
static

Internal function to insert a test into a suite.

The test name is assumed to be unique. Internally, the list of tests in a suite is a double-linked list, which this function manages. Neither pSuite nor pTest may be NULL (checked by assertion). Further, pTest must be an independent test (i.e. both pTest->pNext and pTest->pPrev == NULL), which is also checked by assertion. Severe problems can occur if this function is called during a test run involving pSuite.

Parameters
pSuiteCU_pSuite to insert into (non-NULL).
pTestCU_pTest to insert (non-NULL).
See also
insert_suite()

References CU_Test::pNext, CU_Test::pPrev, CU_Suite::pTest, and CU_Suite::uiNumberOfTests.

Referenced by CU_add_test(), and CU_get_test_by_index().

◆ run_single_suite()

static CU_ErrorCode run_single_suite ( CU_pSuite  pSuite,
CU_pRunSummary  pRunSummary 
)
static

Runs all tests in a specified suite.

Internal function to run all tests in a suite. The suite need not be registered in the test registry to be run. Only suites having their fActive flags set CU_TRUE will actually be run. If the CUnit framework is in an error condition after running a test, no additional tests are run.

Parameters
pSuiteThe suite containing the test (non-NULL).
pRunSummaryThe CU_RunSummary to receive the results (non-NULL).
Returns
A CU_ErrorCode indicating the status of the run.
See also
CU_run_suite() for public interface function.
CU_run_all_tests() for running all suites.

References CUE_SUCCESS, f_last_failure, CU_Suite::fActive, and CU_RunSummary::nFailureRecords.

Referenced by CU_run_all_tests(), and CU_run_suite().

◆ run_single_test()

static CU_ErrorCode run_single_test ( CU_pTest  pTest,
CU_pRunSummary  pRunSummary 
)
static

Runs a specific test.

Internal function to run a test case. This includes calling any handler to be run before executing the test, running the test's function (if any), and calling any handler to be run after executing a test. Suite initialization and cleanup functions are not called by this function. A current suite must be set and active (checked by assertion).

Parameters
pTestThe test to be run (non-NULL).
pRunSummaryThe CU_RunSummary to receive the results (non-NULL).
Returns
A CU_ErrorCode indicating the status of the run.
See also
CU_run_test() for public interface function.
CU_run_all_tests() for running all suites.

References CU_CALLOC, CUE_SUCCESS, CUE_TEST_INACTIVE, f_last_failure, CU_Test::fActive, CU_Suite::fActive, CU_Test::fSuiteCleanup, CU_Test::fSuiteSetup, and CU_RunSummary::nFailureRecords.

◆ suite_exists()

static CU_BOOL suite_exists ( CU_pTestRegistry  pRegistry,
const char *  szSuiteName 
)
static

Internal function to check whether a suite having a specified name already exists.

Parameters
pRegistryCU_pTestRegistry to check (non-NULL).
szSuiteNameSuite name to check (non-NULL).
Returns
CU_TRUE if suite exists in the registry, CU_FALSE otherwise.

References CU_compare_strings(), CU_Suite::pName, CU_Suite::pNext, and CU_TestRegistry::pSuite.

Referenced by CU_get_test_by_index().

◆ test_exists()

static CU_BOOL test_exists ( CU_pSuite  pSuite,
const char *  szTestName 
)
static

Internal function to check whether a test having a specified name is already registered in a given suite.

Parameters
pSuiteCU_pSuite to check (non-NULL).
szTestNameTest case name to check (non-NULL).
Returns
CU_TRUE if test exists in the suite, CU_FALSE otherwise.

References CU_compare_strings(), CU_Test::pName, CU_Test::pNext, and CU_Suite::pTest.

Referenced by CU_add_test(), and CU_get_test_by_index().

◆ test_suite_register()

CU_EXPORT int test_suite_register ( test_suite_t ts)

Variable Documentation

◆ f_failure_list

CU_pFailureRecord f_failure_list = NULL
static

CU_pFailureRecord to hold head of failure record list of each test run.

Referenced by CU_get_failure_list().

◆ f_failure_on_inactive

CU_BOOL f_failure_on_inactive = CU_TRUE
static

Flag for whether inactive suites/tests are treated as failures.

Referenced by CU_get_fail_on_inactive(), CU_run_test(), and CU_set_fail_on_inactive().

◆ f_last_failure

CU_pFailureRecord f_last_failure = NULL
static

CU_pFailureRecord to hold head of failure record list of each test run.

Referenced by run_single_suite(), and run_single_test().

◆ f_pCurSuite

CU_pSuite f_pCurSuite = NULL
static

Pointer to the suite currently being run.

Referenced by CU_get_current_suite().

◆ f_pCurTest

CU_pTest f_pCurTest = NULL
static

Pointer to the test currently being run.

Referenced by CU_get_current_test().

◆ f_pTestRegistry

CU_pTestRegistry f_pTestRegistry = NULL
static

The active internal Test Registry.

Referenced by CU_get_registry(), and CU_set_registry().

◆ f_run_summary

CU_RunSummary f_run_summary = {"", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
static

CU_RunSummary to hold results of each test run.

Referenced by CU_get_run_results_string(), and CU_get_run_summary().

◆ f_start_time

clock_t f_start_time
static

Variable for storage of start time for test run.

Referenced by CU_get_elapsed_time(), CU_run_all_tests(), and CU_run_suite().

◆ g_error_action

CU_ErrorAction g_error_action = CUEA_IGNORE
static

Local variable holding the current error action code.

Referenced by CU_get_error_action(), CU_set_error(), and CU_set_error_action().

◆ g_error_number

CU_ErrorCode g_error_number = CUE_SUCCESS
static

Local variable holding the current error code.

Referenced by CU_get_error(), and CU_get_error_msg().