1 /* 2 * CUnit - A Unit testing framework library for C. 3 * Copyright (C) 2001 Anil Kumar 4 * Copyright (C) 2004-2006 Anil Kumar, Jerry St.Clair 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Library General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Library General Public License for more details. 15 * 16 * You should have received a copy of the GNU Library General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 21 /* 22 * Contains Interface to Run tests. 23 * 24 * Aug 2001 Initial implementation. (AK) 25 * 26 * 09/Aug/2001 Contains generic run tests interface which can be used 27 * for any type of frontend interface framework. (AK) 28 * 29 * 24/Nov/2001 Added Handler for Group Initialization failure condition. (AK) 30 * 31 * 05-Aug-2004 New interface. Since these should be internal functions, 32 * no support for deprecated version 1 names provided now, 33 * eliminated global variables for current test & suite, 34 * moved (renamed) _TestResult here from TestDB.h. (JDS) 35 * 36 * 05-Sep-2004 Added internal test interface. (JDS) 37 * 38 * 23-Apr-2006 Moved doxygen comments into header. 39 * Added type marker to CU_FailureRecord. 40 * Added support for tracking inactive suites/tests. (JDS) 41 * 42 * 08-May-2006 Moved CU_print_run_results() functionality from 43 * console/basic test complete handler. (JDS) 44 * 45 * 24-May-2006 Added callbacks for suite start and complete events. 46 * Added tracking/reported of elapsed time. (JDS) 47 */ 48 49 /** @file 50 * Test run management functions (user interface). 51 * The TestRun module implements functions supporting the running 52 * of tests elements (suites and tests). This includes functions for 53 * running suites and tests, retrieving the number of tests/suites run, 54 * and managing callbacks during the run process.<br /><br /> 55 * 56 * The callback mechanism works as follows. The CUnit runtime system 57 * supports the registering and calling of functions at the start and end 58 * of each test, when all tests are complete, and when a suite 59 * initialialization function returns an error. This allows clients to 60 * perform actions associated with these events such as output formatting 61 * and reporting. 62 */ 63 /** @addtogroup Framework 64 * @{ 65 */ 66 67 #ifndef CUNIT_TESTRUN_H_SEEN 68 #define CUNIT_TESTRUN_H_SEEN 69 70 #include "CUnit.h" 71 #include "CUError.h" 72 #include "TestDB.h" 73 #include <stdio.h> 74 75 #ifdef __cplusplus 76 extern "C" { 77 #endif 78 79 /** Types of failures occurring during test runs. */ 80 typedef enum CU_FailureTypes 81 { 82 CUF_SuiteInactive = 1, /**< Inactive suite was run. */ 83 CUF_SuiteInitFailed, /**< Suite initialization function failed. */ 84 CUF_SuiteCleanupFailed, /**< Suite cleanup function failed. */ 85 CUF_TestInactive, /**< Inactive test was run. */ 86 CUF_AssertFailed /**< CUnit assertion failed during test run. */ 87 } CU_FailureType; /**< Failure type. */ 88 89 /* CU_FailureRecord type definition. */ 90 /** Data type for holding assertion failure information (linked list). */ 91 typedef struct CU_FailureRecord 92 { 93 CU_FailureType type; /**< Failure type. */ 94 unsigned int uiLineNumber; /**< Line number of failure. */ 95 char* strFileName; /**< Name of file where failure occurred. */ 96 char* strCondition; /**< Test condition which failed. */ 97 CU_pTest pTest; /**< Test containing failure. */ 98 CU_pSuite pSuite; /**< Suite containing test having failure. */ 99 100 struct CU_FailureRecord* pNext; /**< Pointer to next record in linked list. */ 101 struct CU_FailureRecord* pPrev; /**< Pointer to previous record in linked list. */ 102 103 } CU_FailureRecord; 104 typedef CU_FailureRecord* CU_pFailureRecord; /**< Pointer to CU_FailureRecord. */ 105 106 /* CU_RunSummary type definition. */ 107 /** Data type for holding statistics and assertion failures for a test run. */ 108 typedef struct CU_RunSummary 109 { 110 char PackageName[50]; 111 unsigned int nSuitesRun; /**< Number of suites completed during run. */ 112 unsigned int nSuitesFailed; /**< Number of suites for which initialization failed. */ 113 unsigned int nSuitesInactive; /**< Number of suites which were inactive. */ 114 unsigned int nTestsRun; /**< Number of tests completed during run. */ 115 unsigned int nTestsFailed; /**< Number of tests containing failed assertions. */ 116 unsigned int nTestsInactive; /**< Number of tests which were inactive (in active suites). */ 117 unsigned int nAsserts; /**< Number of assertions tested during run. */ 118 unsigned int nAssertsFailed; /**< Number of failed assertions. */ 119 unsigned int nFailureRecords; /**< Number of failure records generated. */ 120 double ElapsedTime; /**< Elapsed time for run in seconds. */ 121 } CU_RunSummary; 122 typedef CU_RunSummary* CU_pRunSummary; /**< Pointer to CU_RunSummary. */ 123 124 /*-------------------------------------------------------------------- 125 * Type Definitions for Message Handlers. 126 *--------------------------------------------------------------------*/ 127 typedef void (*CU_SuiteStartMessageHandler)(const CU_pSuite pSuite); 128 /**< Message handler called at the start of a suite. pSuite will not be null. */ 129 130 typedef void (*CU_TestStartMessageHandler)(const CU_pTest pTest, const CU_pSuite pSuite); 131 /**< Message handler called at the start of a test. 132 * The parameters are the test and suite being run. The test run is 133 * considered in progress when the message handler is called. 134 * Neither pTest nor pSuite may be null. 135 */ 136 137 typedef void (*CU_TestCompleteMessageHandler)(const CU_pTest pTest, const CU_pSuite pSuite, 138 const CU_pFailureRecord pFailure); 139 /**< Message handler called at the completion of a test. 140 * The parameters are the test and suite being run, plus a pointer to 141 * the first failure record applicable to this test. If the test did 142 * not have any assertion failures, pFailure will be NULL. The test run 143 * is considered in progress when the message handler is called. 144 */ 145 146 typedef void (*CU_SuiteCompleteMessageHandler)(const CU_pSuite pSuite, 147 const CU_pFailureRecord pFailure); 148 /**< Message handler called at the completion of a suite. 149 * The parameters are suite being run, plus a pointer to the first failure 150 * record applicable to this suite. If the suite and it's tests did not 151 * have any failures, pFailure will be NULL. The test run is considered 152 * in progress when the message handler is called. 153 */ 154 155 typedef void (*CU_AllTestsCompleteMessageHandler)(const CU_pFailureRecord pFailure); 156 /**< Message handler called at the completion of a test run. 157 * The parameter is a pointer to the linked list holding the failure 158 * records for the test run. The test run is considered completed 159 * when the message handler is called. 160 */ 161 162 typedef void (*CU_SuiteInitFailureMessageHandler)(const CU_pSuite pSuite); 163 /**< Message handler called when a suite initializer fails. 164 * The test run is considered in progress when the message handler is called. 165 */ 166 167 typedef void (*CU_SuiteCleanupFailureMessageHandler)(const CU_pSuite pSuite); 168 /**< Message handler called when a suite cleanup function fails. 169 * The test run is considered in progress when the message handler is called. 170 */ 171 172 /*-------------------------------------------------------------------- 173 * Get/Set functions for Message Handlers 174 *--------------------------------------------------------------------*/ 175 CU_EXPORT void CU_set_suite_start_handler(CU_SuiteStartMessageHandler pSuiteStartMessage); 176 /**< Sets the message handler to call before each suite is run. */ 177 CU_EXPORT void CU_set_test_start_handler(CU_TestStartMessageHandler pTestStartMessage); 178 /**< Sets the message handler to call before each test is run. */ 179 CU_EXPORT void CU_set_test_complete_handler(CU_TestCompleteMessageHandler pTestCompleteMessage); 180 /**< Sets the message handler to call after each test is run. */ 181 CU_EXPORT void CU_set_suite_complete_handler(CU_SuiteCompleteMessageHandler pSuiteCompleteMessage); 182 /**< Sets the message handler to call after each suite is run. */ 183 CU_EXPORT void CU_set_all_test_complete_handler(CU_AllTestsCompleteMessageHandler pAllTestsCompleteMessage); 184 /**< Sets the message handler to call after all tests have been run. */ 185 CU_EXPORT void CU_set_suite_init_failure_handler(CU_SuiteInitFailureMessageHandler pSuiteInitFailureMessage); 186 /**< Sets the message handler to call when a suite initialization function returns an error. */ 187 CU_EXPORT void CU_set_suite_cleanup_failure_handler(CU_SuiteCleanupFailureMessageHandler pSuiteCleanupFailureMessage); 188 /**< Sets the message handler to call when a suite cleanup function returns an error. */ 189 190 CU_EXPORT CU_SuiteStartMessageHandler CU_get_suite_start_handler(void); 191 /**< Retrieves the message handler called before each suite is run. */ 192 CU_EXPORT CU_TestStartMessageHandler CU_get_test_start_handler(void); 193 /**< Retrieves the message handler called before each test is run. */ 194 CU_EXPORT CU_TestCompleteMessageHandler CU_get_test_complete_handler(void); 195 /**< Retrieves the message handler called after each test is run. */ 196 CU_EXPORT CU_SuiteCompleteMessageHandler CU_get_suite_complete_handler(void); 197 /**< Retrieves the message handler called after each suite is run. */ 198 CU_EXPORT CU_AllTestsCompleteMessageHandler CU_get_all_test_complete_handler(void); 199 /**< Retrieves the message handler called after all tests are run. */ 200 CU_EXPORT CU_SuiteInitFailureMessageHandler CU_get_suite_init_failure_handler(void); 201 /**< Retrieves the message handler called when a suite initialization error occurs. */ 202 CU_EXPORT CU_SuiteCleanupFailureMessageHandler CU_get_suite_cleanup_failure_handler(void); 203 /**< Retrieves the message handler called when a suite cleanup error occurs. */ 204 205 /*-------------------------------------------------------------------- 206 * Functions for running registered tests and suites. 207 *--------------------------------------------------------------------*/ 208 CU_EXPORT CU_ErrorCode CU_run_all_tests(void); 209 /**< 210 * Runs all tests in all suites registered in the test registry. 211 * The suites are run in the order registered in the test registry. 212 * For each suite, it is first checked to make sure it is active. 213 * Any initialization function is then called, the suite is run 214 * using run_single_suite(), and finally any suite cleanup function 215 * is called. If an error condition (other than CUE_NOREGISTRY) 216 * occurs during the run, the action depends on the current error 217 * action (see CU_set_error_action()). An inactive suite is not 218 * considered an error for this function. Note that the run 219 * statistics (counts of tests, successes, failures) are cleared 220 * each time this function is run, even if it is unsuccessful. 221 * 222 * @return A CU_ErrorCode indicating the first error condition 223 * encountered while running the tests. 224 * @see CU_run_suite() to run the tests in a specific suite. 225 * @see CU_run_test() for run a specific test only. 226 */ 227 228 CU_EXPORT CU_ErrorCode CU_run_suite(CU_pSuite pSuite); 229 /**< 230 * Runs all tests in a specified suite. 231 * The suite need not be registered in the test registry to be 232 * run. It does, however, need to have its fActive flag set to 233 * CU_TRUE.<br /><br /> 234 * 235 * Any initialization function for the suite is first called, 236 * then the suite is run using run_single_suite(), and any suite 237 * cleanup function is called. Note that the run statistics 238 * (counts of tests, successes, failures) are initialized each 239 * time this function is called even if it is unsuccessful. If 240 * an error condition occurs during the run, the action depends 241 * on the current error action (see CU_set_error_action()). 242 * 243 * @param pSuite The suite containing the test (non-NULL) 244 * @return A CU_ErrorCode indicating the first error condition 245 * encountered while running the suite. CU_run_suite() 246 * sets and returns CUE_NOSUITE if pSuite is NULL, or 247 * CUE_SUITE_INACTIVE if the requested suite is not 248 * activated. Other error codes can be set during suite 249 * initialization or cleanup or during test runs. 250 * @see CU_run_all_tests() to run all suites. 251 * @see CU_run_test() to run a single test in a specific suite. 252 */ 253 254 CU_EXPORT CU_ErrorCode CU_run_test(CU_pSuite pSuite, CU_pTest pTest); 255 /**< 256 * Runs a specific test in a specified suite. 257 * The suite need not be registered in the test registry to be run, 258 * although the test must be registered in the specified suite. 259 * Any initialization function for the suite is first 260 * called, then the test is run using run_single_test(), and 261 * any suite cleanup function is called. Note that the 262 * run statistics (counts of tests, successes, failures) 263 * will be initialized each time this function is called even 264 * if it is not successful. Both the suite and test specified 265 * must be active for the test to be run. The suite is not 266 * considered to be run, although it may be counted as a failed 267 * suite if the intialization or cleanup functions fail. 268 * 269 * @param pSuite The suite containing the test (non-NULL) 270 * @param pTest The test to run (non-NULL) 271 * @return A CU_ErrorCode indicating the first error condition 272 * encountered while running the suite. CU_run_test() 273 * sets and returns CUE_NOSUITE if pSuite is NULL, 274 * CUE_NOTEST if pTest is NULL, CUE_SUITE_INACTIVE if 275 * pSuite is not active, CUE_TEST_NOT_IN_SUITE 276 * if pTest is not registered in pSuite, and CU_TEST_INACTIVE 277 * if pTest is not active. Other error codes can be set during 278 * suite initialization or cleanup or during the test run. 279 * @see CU_run_all_tests() to run all tests/suites. 280 * @see CU_run_suite() to run all tests in a specific suite. 281 */ 282 283 /*-------------------------------------------------------------------- 284 * Functions for setting runtime behavior. 285 *--------------------------------------------------------------------*/ 286 CU_EXPORT void CU_set_fail_on_inactive(CU_BOOL new_inactive); 287 /**< 288 * Sets whether an inactive suite or test is treated as a failure. 289 * If CU_TRUE, then failure records will be generated for inactive 290 * suites or tests encountered during a test run. The default is 291 * CU_TRUE so that the client is reminded that the framewrork 292 * contains inactive suites/tests. Set to CU_FALSE to turn off 293 * this behavior. 294 * 295 * @param new_inactive New setting for whether to treat inactive 296 * suites and tests as failures during a test 297 * run (CU_TRUE) or not (CU_FALSE). 298 * @see CU_get_fail_on_failure() 299 */ 300 301 CU_EXPORT CU_BOOL CU_get_fail_on_inactive(void); 302 /**< 303 * Retrieves the current setting for whether inactive suites/tests 304 * are treated as failures. If CU_TRUE then failure records will 305 * be generated for inactive suites encountered during a test run. 306 * 307 * @return CU_TRUE if inactive suites/tests are failures, CU_FALSE if not. 308 * @see CU_set_fail_on_inactive() 309 */ 310 311 /*-------------------------------------------------------------------- 312 * Functions for getting information about the previous test run. 313 *--------------------------------------------------------------------*/ 314 CU_EXPORT unsigned int CU_get_number_of_suites_run(void); 315 /**< Retrieves the number of suites completed during the previous run (reset each run). */ 316 CU_EXPORT unsigned int CU_get_number_of_suites_failed(void); 317 /**< Retrieves the number of suites which failed to initialize during the previous run (reset each run). */ 318 CU_EXPORT unsigned int CU_get_number_of_suites_inactive(void); 319 /**< Retrieves the number of inactive suites found during the previous run (reset each run). */ 320 CU_EXPORT unsigned int CU_get_number_of_tests_run(void); 321 /**< Retrieves the number of tests completed during the previous run (reset each run). */ 322 CU_EXPORT unsigned int CU_get_number_of_tests_failed(void); 323 /**< Retrieves the number of tests containing failed assertions during the previous run (reset each run). */ 324 CU_EXPORT unsigned int CU_get_number_of_tests_inactive(void); 325 /**< Retrieves the number of inactive tests found during the previous run (reset each run). */ 326 CU_EXPORT unsigned int CU_get_number_of_asserts(void); 327 /**< Retrieves the number of assertions processed during the last run (reset each run). */ 328 CU_EXPORT unsigned int CU_get_number_of_successes(void); 329 /**< Retrieves the number of successful assertions during the last run (reset each run). */ 330 CU_EXPORT unsigned int CU_get_number_of_failures(void); 331 /**< Retrieves the number of failed assertions during the last run (reset each run). */ 332 CU_EXPORT unsigned int CU_get_number_of_failure_records(void); 333 /**< 334 * Retrieves the number failure records created during the previous run (reset each run). 335 * Note that this may be more than the number of failed assertions, since failure 336 * records may also be created for failed suite initialization and cleanup. 337 */ 338 CU_EXPORT double CU_get_elapsed_time(void); 339 /**< 340 * Retrieves the elapsed time for the last run in seconds (reset each run). 341 * This function will calculate the current elapsed time if the test run has not 342 * yet completed. This is in contrast to the run summary returned by 343 * CU_get_run_summary(), for which the elapsed time is not updated until the 344 * end of the run. 345 */ 346 CU_EXPORT CU_pFailureRecord CU_get_failure_list(void); 347 /**< 348 * Retrieves the head of the linked list of failures which occurred during the 349 * last run (reset each run). Note that the pointer returned is invalidated 350 * when the client initiates a run using CU_run_all_tests(), CU_run_suite(), 351 * or CU_run_test(). 352 */ 353 CU_EXPORT CU_pRunSummary CU_get_run_summary(void); 354 /**< 355 * Retrieves the entire run summary for the last test run (reset each run). 356 * The run counts and stats contained in the run summary are updated 357 * throughout a test run. Note, however, that the elapsed time is not 358 * updated until after all suites/tests are run but before the "all tests 359 * complete" message handler is called (if any). To get the elapsed 360 * time during a test run, use CU_get_elapsed_time() instead. 361 */ 362 363 CU_EXPORT char * CU_get_run_results_string(void); 364 /**< 365 * Creates a string and fills it with a summary of the current run results. 366 * The run summary presents data for the suites, tests, and assertions 367 * encountered during the run, as well as the elapsed time. The data 368 * presented include the number of registered, run, passed, failed, and 369 * inactive entities for each, as well as the elapsed time. This function 370 * can be called at any time, although the test registry must have been 371 * initialized (checked by assertion). The returned string is owned by 372 * the caller and should be deallocated using CU_FREE(). NULL is returned 373 * if there is an error allocating the new string. 374 * 375 * @return A new string containing the run summary (owned by caller). 376 */ 377 378 CU_EXPORT void CU_print_run_results(FILE *file); 379 /**< 380 * Prints a summary of the current run results to file. 381 * The run summary is the same as returned by CU_get_run_results_string(). 382 * Note that no newlines are printed before or after the report, so any 383 * positioning must be performed before/after calling this function. The 384 * report itself extends over several lines broken by '\n' characters. 385 * file may not be NULL (checked by assertion). 386 * 387 * @param file Pointer to stream to receive the printed summary (non-NULL). 388 */ 389 390 /*-------------------------------------------------------------------- 391 * Functions for internal & testing use. 392 *--------------------------------------------------------------------*/ 393 CU_EXPORT CU_pSuite CU_get_current_suite(void); 394 /**< Retrieves a pointer to the currently-running suite (NULL if none). */ 395 CU_EXPORT CU_pTest CU_get_current_test(void); 396 /**< Retrievea a pointer to the currently-running test (NULL if none). */ 397 CU_EXPORT CU_BOOL CU_is_test_running(void); 398 /**< Returns <CODE>CU_TRUE</CODE> if a test run is in progress, 399 * <CODE>CU_TRUE</CODE> otherwise. 400 */ 401 402 CU_EXPORT void CU_clear_previous_results(void); 403 /**< 404 * Initializes the run summary information stored from the previous test run. 405 * Resets the run counts to zero, and frees any memory associated with 406 * failure records. Calling this function multiple times, while inefficient, 407 * will not cause an error condition. 408 * @see clear_previous_results() 409 */ 410 411 CU_EXPORT CU_BOOL CU_assertImplementation(CU_BOOL bValue, 412 unsigned int uiLine, 413 const char *strCondition, 414 const char *strFile, 415 const char *strFunction, 416 CU_BOOL bFatal); 417 /**< 418 * Assertion implementation function. 419 * All CUnit assertions reduce to a call to this function. It should only be 420 * called during an active test run (checked by assertion). This means that CUnit 421 * assertions should only be used in registered test functions during a test run. 422 * 423 * @param bValue Value of the assertion (CU_TRUE or CU_FALSE). 424 * @param uiLine Line number of failed test statement. 425 * @param strCondition String containing logical test that failed. 426 * @param strFile Source file where test statement failed. 427 * @param strFunction Function where test statement failed. 428 * @param bFatal CU_TRUE to abort test (via longjmp()), CU_FALSE to continue test. 429 * @return As a convenience, returns the value of the assertion (i.e. bValue). 430 */ 431 432 #ifdef USE_DEPRECATED_CUNIT_NAMES 433 typedef CU_FailureRecord _TestResult; /**< @deprecated Use CU_FailureRecord. */ 434 typedef CU_pFailureRecord PTestResult; /**< @deprecated Use CU_pFailureRecord. */ 435 #endif /* USE_DEPRECATED_CUNIT_NAMES */ 436 437 #ifdef CUNIT_BUILD_TESTS 438 void test_cunit_TestRun(void); 439 #endif 440 441 #ifdef __cplusplus 442 } 443 #endif 444 #endif /* CUNIT_TESTRUN_H_SEEN */ 445 /** @} */ 446