1CUnit(3) CUnit Programmer's Manual CUnit(3)
2
6 CUnit - A unit testing framework for C
7
10 #include <CUnit/CUnit.h> ASSERT definitions, test management.
11 #include <CUnit/Automated.h> Automated interface with xml output.
12 #include <CUnit/Basic.h> Basic interface with console output.
13 #include <CUnit/Console.h> Interactive console interface.
14 #include <CUnit/CUCurses.h> Interactive curses interface.
15
19 CUnit is a system for writing, administering, and running unit tests in
20 C. It uses a simple framework for building test structures, and pro‐
21 vides a rich set of assertions for testing common data types. CUnit is
22 built as a static library which is linked with the user's testing code.
23
27 CUnit is a combination of a platform-independent framework with various
28 user interfaces. The core framework provides basic support for managing
29 a test registry, suites, and test cases. The user interfaces facilitate
30 interaction with the framework to run tests and view results.
31 The basic hierarchichal organization of CUnit is depicted here:
34 Test Registry
37 |
38 -----------------------------
39 | |
40 Suite '1' . . . . Suite 'N'
41 | |
42 --------------- ---------------
43 | | | |
44 Test '11' ... Test '1M' Test 'N1' ... Test 'NM'
45 Individual test cases are packaged into suites, which are registered
48 with the active test registry. Suites can have setup and teardown
49 functions which are automatically called before and after running the
50 suite's tests. All suites/tests in the registry may be run using a sin‐
51 gle function call, or selected suites or tests can be run.
52 The typical usage of CUnit is:
55 1. Write functions for tests (and suite init/cleanup if necessary).
58 2. Initialize the test registry using CU_initialize_registry()
59 3. Add test suites to the registry using CU_add_suite()
60 4. Add test cases to the suites using CU_add_test()
61 5. Run tests using the desired interface, e.g.
62 CU_console_run_tests() to use the interactive console.
63 6. Cleanup the test registry using CU_cleanup_registry()
64 All public names in CUnit are prefixed with 'CU_'. This helps minimize
67 clashes with names in user code. Note that earlier versions CUnit used
68 different names without this prefix. The older API names are depre‐
69 cated but still supported. To use the older names, user code must now
70 be compiled with USE_DEPRECATED_CUNIT_NAMES defined.
71
75 A "test" is a C function having the signature: void test_func(void).
76 There are no restrictions on the content of a test function, except
77 that it should not modify the CUnit framework (e.g. add suites or
78 tests, modify the test registry, or initiate a test run). A test func‐
79 tion may call other functions (which also may not modify the frame‐
80 work). Registering a test will cause it's function to be run when the
81 test is run.
82 CUnit provides a set of assertions for testing logical conditions. The
85 success or failure of these assertions is tracked by the framework, and
86 can be viewed when a test run is complete. Each assertion tests a sin‐
87 gle logical condition, and fails if the condition evaluates to
88 CU_FALSE. Upon failure, the test continues unless the user chooses the
89 'xxx_FATAL' version of an assertion. In that case, the test function
90 returns immediately.
91 CUnit provides a set of assertions for testing logical conditions. The
93 success or failure of these assertions is tracked by the framework, and
94 can be viewed when a test run is complete.
95 Each assertion tests a single logical condition, and fails if the con‐
98 dition evaluates to CU_FALSE. Upon failure, the test function contin‐
99 ues unless the user chooses the 'xxx_FATAL' version of an assertion.
100 In that case, the test function is aborted and returns immediately.
101 FATAL versions of assertions should be used with caution! There is no
102 opportunity for the test function to clean up after itself once a FATAL
103 assertion fails. The normal suite cleanup function is not affected,
104 however.
105 There are also special "assertions" for registering a pass or fail with
108 the framework without performing a logical test. These are useful for
109 testing flow of control or other conditions not requiring a logical
110 test.
111 Other functions called by a registered test function may use the CUnit
114 assertions freely. These assertions will be counted for the calling
115 function. They may also use FATAL versions of assertions - failure
116 will abort the original test function and its entire call chain.
117 The assertions defined by CUnit are:
120 #include <CUnit/CUnit.h>
123 CU_ASSERT(int expression)
127 CU_ASSERT_FATAL(int expression)
128 CU_TEST(int expression)
129 CU_TEST_FATAL(int expression)
130 Assert that expression is CU_TRUE (non-zero).
131 CU_ASSERT_TRUE(value)
134 CU_ASSERT_TRUE_FATAL(value)
135 Assert that value is CU_TRUE (non-zero).
136 CU_ASSERT_FALSE(value)
140 CU_ASSERT_FALSE_FATAL(value)
141 Assert that value is CU_FALSE (zero).
142 CU_ASSERT_EQUAL(actual, expected)
146 CU_ASSERT_EQUAL_FATAL(actual, expected)
147 Assert that actual == expected.
148 CU_ASSERT_NOT_EQUAL(actual, expected)
152 CU_ASSERT_NOT_EQUAL_FATAL(actual, expected)
153 Assert that actual != expected.
154 CU_ASSERT_PTR_EQUAL(actual, expected)
158 CU_ASSERT_PTR_EQUAL_FATAL(actual, expected)
159 Assert that pointers actual == expected.
160 CU_ASSERT_PTR_NOT_EQUAL(actual, expected)
164 CU_ASSERT_PTR_NOT_EQUAL_FATAL(actual, expected)
165 Assert that pointers actual != expected.
166 CU_ASSERT_PTR_NULL(value)
170 CU_ASSERT_PTR_NULL_FATAL(value)
171 Assert that pointer value == NULL.
172 CU_ASSERT_PTR_NOT_NULL(value)
176 CU_ASSERT_PTR_NOT_NULL_FATAL(value)
177 Assert that pointer value != NULL.
178 CU_ASSERT_STRING_EQUAL(actual, expected)
182 CU_ASSERT_STRING_EQUAL_FATAL(actual, expected)
183 Assert that strings actual and expected are equivalent.
184 CU_ASSERT_STRING_NOT_EQUAL(actual, expected)
188 CU_ASSERT_STRING_NOT_EQUAL_FATAL(actual, expected)
189 Assert that strings actual and expected differ.
190 CU_ASSERT_NSTRING_EQUAL(actual, expected, count)
194 CU_ASSERT_NSTRING_EQUAL_FATAL(actual, expected, count)
195 Assert that 1st count chars of actual and expected are the same.
196 CU_ASSERT_NSTRING_NOT_EQUAL(actual, expected, count)
200 CU_ASSERT_NSTRING_NOT_EQUAL_FATAL(actual, expected, count)
201 Assert that 1st count chars of actual and expected differ.
202 CU_ASSERT_DOUBLE_EQUAL(actual, expected, granularity)
206 CU_ASSERT_DOUBLE_EQUAL_FATAL(actual, expected, granularity)
207 Assert that |actual - expected| <= |granularity|.
208 Math library must be linked in for this assertion.
209 CU_ASSERT_DOUBLE_NOT_EQUAL(actual, expected, granularity)
213 CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL(actual, expected, granularity)
214 Assert that |actual - expected| > |granularity|.
215 Math library must be linked in for this assertion.
216 CU_PASS(message)
220 Register a success without performing a logical test.
221 CU_FAIL(message)
225 CU_FAIL_FATAL(message)
226 Register a failure without performing a logical test.
227
231 The test registry is the repository for suites and associated tests.
232 The user normally only needs to initialize the registry before use and
233 clean up afterwards. However, other functions are provided to manipu‐
234 late the registry when necessary.
235 The main functions needed by clients are:
238 #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
241 CU_ErrorCode CU_initialize_registry(void)
244 Initializes the framework. This function should be called before
245 any other CUnit functions. Failure to do so will likely result in
246 a crash. An error status code is returned:
247 CUE_SUCCESS if initialization is successful.
250 CUE_NOMEMORY if memory allocation failed.
253 CU_BOOL CU_registry_initialized(void)
257 Checks whether the framework has been initialized. This may be
258 useful if the registry setup is distributed over multiple files
259 that need to make sure the registry is ready for test registra‐
260 tion.
261 void CU_cleanup_registry(void)
265 Cleans up and releases memory used by the framework. No CUnit
266 functions (other than CU_initialize_registry() ) should be called
267 after this function. Failure to call CU_cleanup_registry() will
268 result in memory leaks. Note also that this function will destroy
269 all suites (and associated tests) in the registry.
270 Other registry functions are primarily for internal and testing pur‐
273 poses. However, general users may find use for them and should be
274 aware of them. These include:
275 CU_pTestRegistry CU_get_registry(void)
278 Retrieve a pointer to the active test registry. The registry is a
279 variable of data type CU_Testregistry (declared in
280 <CUnit/TestDB.h>). Note that the returned pointer will be invali‐
281 dated by a call to CU_cleanup_registry() or CU_initialize_reg‐
282 istry()
283 CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)
287 Replace the active registry with the specified one. A pointer to
288 the previous registry is returned. It is the caller's responsi‐
289 bility to destroy the old registry. This can be accomplished
290 using CU_destroy_existing_registry() on the returned pointer.
291 Alternatively, the old registry can be set as the active one. A
292 subsequent call to CU_cleanup_registry() will then destroy it
293 automatically. Care should be taken not to explicitly destroy a
294 registry that is set as the active one. This will result in mul‐
295 tiple frees of the same memory and a likely crash.
296 CU_pTestRegistry CU_create_new_registry(void)
299 Create a new registry and return a pointer to it. The new reg‐
300 istry will not contain any suites or tests. It is the caller's
301 responsibility to destroy the new registry by one of the mecha‐
302 nisms described previously.
303 void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
306 Destroy the specified test registry, including any registered
307 suites. This function should not be called for a registry which
308 is set as the active test registry. This will result in a multi‐
309 ple free of the same memory when CU_cleanup_registry() is called.
310 ppRegistry may not be NULL, but the pointer it points to may be.
311 Note that *ppRegistry will be NULL on return.
312
316 In order for a test to be run by CUnit, it must be added to a test col‐
317 lection (suite) which is registered with the test registry.
318 Adding Suites to the Registry
321 The first step in setting up a test system is creating and registering
322 one or more test collections (suites). Each suite has a name which may
323 be used to reference the suite. Therefore, it is recommended (but not
324 required) that each registered suite have a unique name. The current
325 implementation does not support the creation of suites independent of
326 the test registry. Suites are simultaneously created and added to the
327 active registry as follows.
328 #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
331 CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit,
334 CU_CleanupFunc pClean)" This creates and registers a new suite
335 having the specified name, initialization function, and cleanup
336 function. A pointer to the new suite is returned for use in
337 adding tests to the suite. This pointer will be NULL if a fatal
338 error occurs. In addition, the framework error status is set as
339 follows:
340 CUE_SUCCESS The suite was successfully created and regis‐
343 tered.
344 CUE_NOREGISTRY Error: Test Registry is not initialized.
347 CUE_NO_SUITENAME Error: Suite name is not specified or NULL.
350 CUE_DUP_SUITE Warning: The registry already has a suite with
353 this name.
354 CUE_NOMEMORY Error: Memory allocation failed.
357 The initialization and cleanup functions are optional. Both are C
360 functions having the signature int func_name(void). These func‐
361 tions can perform setup and teardown operations needed to support
362 the suite's tests. They are called before and after the suite's
363 tests are run, even if only 1 of the suite's tests is run. They
364 take no arguments, and should return NULL if they complete suc‐
365 cessfully (non-NULL otherwise). If either function is not
366 required for a particular suite, pass NULL to CU_add_suite().
367 Adding Tests to Suites
371 Tests are created and added to suites. Each test has a name which may
372 be used to reference the test later. Therefore, it is recommended (but
373 not required) that the name be unique among all tests added to a single
374 suite. The current implementation does not support the creation of
375 tests independent of registered suites. Tests are simultaneously cre‐
376 ated and added to a suite as follows.
377 #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
380 CU_pTest CU_add_test(CU_pSuite pSuite, const char* strName, CU_Test‐
383 Func
384 pTestFunc)" This creates a new test having the specified name and
385 test function, and adds it to the indicated suite. The suite
386 should have been previously created using CU_add_suite(). A
387 pointer to the new test is returned, which will be NULL if a fatal
388 error occurred. In addition, the framework error status is set as
389 follows:
390 CUE_SUCCESS The test was successfully created and added.
393 CUE_NOREGISTRY Error: Test Registry is not initialized.
396 CUE_NOSUITE Error: Specified suite is NULL or invalid.
399 CUE_NO_TESTNAME Error: Test name is not specified or NULL.
402 CUE_NOTEST Error: Test function is not specified or NULL.
405 CUE_DUP_TEST Warning: The suite already has a test with this
407 name.
408 CUE_NOMEMORY Error: Memory allocation failed.
411 Activation of Suites and Tests
415 A suite or test must be active to be executed during a test run (all
416 suites and tests are active by default upon creation). The active
417 state of a suite or test is available as pSuite->fActive and
418 pTest->fActive, respectively. The flag will be CU_TRUE when the entity
419 is active, CU_FALSE otherwise. Use the following functions to selec‐
420 tively deactivate suites and tests to choose subsets of tests to run
421 dynamically. Note that it is a framework error to deactivate a test or
422 suite and then specifically request that it be run.
423 #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
426 CU_ErrorCode CU_set_suite_active(CU_pSuite pSuite, CU_BOOL fNewActive)
429 CU_ErrorCode CU_set_test_active(CU_pTest pTest, CU_BOOL fNewActive)
432 Pass CU_TRUE to these functions to activate a suite/test, CU_FALSE
433 to deactivate it. These functions return CUE_NOSUITE and
434 CUE_NOTEST, respectively, if the specified suite or test is NULL.
435 Modifying Other Attributes of Suites and Tests
439 Normally the attributes of suites and tests are set at creation time.
440 In some cases, a client may wish to manipulate these to modify the test
441 structure dynamically. The following functions are provided for this
442 purpose, and should be used instead of directly setting the value of
443 the data structure members. All return CUE_SUCCESS on success, and the
444 indicated error code on failure.
445 CU_ErrorCode CU_set_suite_name(CU_pSuite pSuite, const char *strNew‐
448 Name)
449 CU_ErrorCode CU_set_test_name(CU_pTest pTest, const char *strNewName)
452 These functions change the name of registered suites and tests.
453 The current names are available as the pSuite->pName</I> and data
454 structure members. If the suite or test is NULL, then CUE_NOSUITE
455 or CUE_NOTEST is returned, respectively. If strNewName is NULL,
456 then CUE_NO_SUITENAME or CUE_NO_TESTNAME is returned, respec‐
457 tively.
458 CU_ErrorCode CU_set_suite_initfunc(CU_pSuite pSuite, CU_InitializeFunc
461 pNewInit)
462 CU_ErrorCode CU_set_suite_cleanupfunc(CU_pSuite pSuite, CU_CleanupFunc
465 pNewClean)
466 These functions change the initialization and cleanup functions
467 for a registered suite. The current functions are available as
468 the pSuite->pInitializeFunc and pSuite->pCleanupFunc data struc‐
469 ture members. If the suite is NULL then CUE_NOSUITE is returned.
470 CU_ErrorCode CU_set_test_func(CU_pTest pTest, CU_TestFunc pNewFunc)
473 This function changes the test function for a registered test.
474 The current test function is available as the pTest->pTestFunc</I>
475 data structure member. If either pTest or pNewFunc is NULL, then
476 CUE_NOTEST is returned.
477 Lookup of Individual Suites and Tests
481 In most cases, clients will have references to registered suites and
482 tests as pointers returned from CU_add_suite() and CU_add_test().
483 Occassionally, a client may need to be able to retrieve a reference to
484 a suite or test. The following functions are provided to assist
485 clients with this when the client has some information about the entity
486 (name or order of registration). In cases where nothing is known about
487 the suite or test, the client will need to iterate the internal data
488 structures to enumerate the suites and tests. This is not directly
489 supported in the client API.
490 CU_pSuite CU_get_suite(const char* strName) CU_pSuite
493 CU_get_suite_at_pos(unsigned int pos) unsigned int
494 CU_get_suite_pos(CU_pSuite pSuite) unsigned int
495 CU_get_suite_pos_by_name(const char* strName) </P> These functions
496 facilitate lookup of suites registered in the active test registry.
497 The first 2 functions allow lookup of the suite by name or position and
498 return NULL if the suite cannot be found. The position is a 1-based
499 index in the range [1 .. CU_get_registry() ->uiNumberOfSuites]. This
500 may be helpful when suites having duplicate names are registered, in
501 which case lookup by name can only retrieve the 1st suite having that
502 name. The second 2 functions help the client identify the position of
503 a registered suite. These return 0 if the suite cannot be found. In
504 addition, all these functions set the CUnit error state to CUE_NOREG‐
505 ISTRY> if the registry is not initialized. As appropriate,
506 CUE_NO_SUITENAME is set if strName is NULL, and CUE_NOSUITE is set if
507 pSuite is NULL.
508 CU_pTest CU_get_test(CU_pSuite pSuite, const char *strName) CU_pTest
511 CU_get_test_at_pos<(CU_pSuite pSuite, unsigned int pos) unsigned int
512 CU_get_test_pos<(CU_pSuite pSuite, CU_pTest pTest) unsigned int
513 CU_get_test_pos_by_name(CU_pSuite pSuite, const char *strName) These
514 functions facilitate lookup of tests registered in suites. The first 2
515 functions allow lookup of the test by name or position and return NULL
516 if the test cannot found. The position is a 1-based index in the range
517 [1 .. pSuite->uiNumberOfSuites]. This may be helpful when tests having
518 duplicate names are registered, in which case lookup by name can only
519 retrieve the 1st test having that name. The second 2 functions help
520 the client identify the position of a test in a suite. These return 0
521 if the test cannot be found. In addition, all these functions set the
522 CUnit error state to CUE_NOREGISTRY if the registry is not initialized,
523 and to CUE_NOSUITE if pSuite is NULL. As appropriate, CUE_NO_TESTNAME
524 is set if strName is NULL, and CUE_NOTEST is set if pTest is NULL.
525
529 CUnit supports running all tests in all registered suites, but individ‐
530 ual tests or suites can also be run. During each run, the framework
531 keeps track of the number of suites, tests, and assertions run, passed,
532 and failed. Note that the previous results are cleared each time a
533 test run is initiated (even if it fails).
534 While CUnit provides primitive functions for running suites and tests,
537 most users will want to use one of the user interfaces. These inter‐
538 faces handle the details of interaction with the framework and provide
539 output of test details and results for the user. For more about the
540 primitive functions, see <CUnit/testRun.h>.
541 Test Results
545 The interfaces present results of test runs, but client code may some‐
546 times need to access the results directly. These results include vari‐
547 ous run counts, as well as a linked list of failure records holding the
548 failure details. Test results must be retrieved before attempting to
549 run other tests, which resets the result information. Functions for
550 accessing the test results are:
551 #include <CUnit/TestRun.h> (included automatically by <CUnit/CUnit.h>)
554 unsigned int CU_get_number_of_suites_run(void)'
557 Retrieve the number of suites run. Suite having initialization
558 functions which fail are not run. To get the total number of reg‐
559 istered suites, use CU_get_registry()->uiNumberOfSuites.
560 unsigned int CU_get_number_of_suites_failed(void)
563 Retrieve the number of suites which had initialization or cleanup
564 functions which failed (returned non-NULL).
565 unsigned int CU_get_number_of_tests_run(void)
568 Retrieve the number of tests run. Tests in suites having initial‐
569 ization functions which fail are not run. To get the total number
570 of registered tests , use CU_get_registry()->uiNumberOfTests.
571 unsigned int CU_get_number_of_tests_failed(void)
574 Retrieve the number of tests which contained at least 1 failed
575 assertion.
576 unsigned int CU_get_number_of_asserts(void)
579 Retrieve the number of CUnit assertions made during the test run.
580 unsigned int CU_get_number_of_successes(void)
583 Retrieve the number of assertions which passed.
584 unsigned int CU_get_number_of_failures(void)
587 Retrieve the number of assertions which failed.
588 const CU_pRunSummary CU_get_run_summary(void)
591 Retrieve a CU_RunSummary containing all the run count information.
592 This data structure is declared in <CUnit/TestRun.h> and includes
593 the (self-explanatory) unsigned int fields nSuitesRun, nSuites‐
594 Failed, nTestsRun, nTestsFailed, nAsserts, and nAssertsFailed.
595 const CU_pFailureRecord CU_get_failure_list(void)
598 Retrieve the head of the linked list of failure records for the
599 last run. Each assertion failure or suite init/cleanup function
600 failure is registered in a new CU_FailureRecord in the linked
601 list. This data structure is declared in <CUnit/TestRun.h> and
602 includes the following fields:
603 unsigned int uiLineNumber
604 char* strFileName
605 char* strCondition
606 CU_pTest pTest
607 CU_pSuite pSuite
608 Automated Interface
612 The automated interface is non-interactive. The current implementation
613 only supports running all registered suites. Results are output to an
614 xml file to be viewed by appropriate external tools. Registered tests
615 can also be listed to an xml file for viewing. The following public
616 functions are available:
617 #include <CUnit/Automated.h>
619 void CU_automated_run_tests(void)
622 Run all tests in all registered (and active) suites. Results are
623 output to a file named ROOT-Results.xml. The filename 'ROOT' is
624 set using CU_set_output_filename(), or else the default 'CUnitAu‐
625 tomated' is used. This means that the same filename is used each
626 run (and the results file overwritten) if the user does not
627 explicitly set the 'ROOT' for each run.
628 CU_ErrorCode CU_list_tests_to_file(void)
631 Lists the registered suites and associated tests to file. The
632 listing file is named ROOT-Listing.xml. The filename 'ROOT' is
633 set using CU_set_output_filename(), or else the default 'CUnitAu‐
634 tomated' is used. This means that the same filename is used each
635 run (and the listing file overwritten) if the user does not
636 explicitly set the 'ROOT' for each run.
637 void CU_set_output_filename(const char* szFilenameRoot)
640 Set the filename root to use for automated results and listing
641 files.
642 Basic Interface (non-interactive)
646 The basic interface is also non-interactive, with results output to
647 stdout. This interface supports running individual suites or tests,
648 and allows client code to control the type of output displayed during
649 each run. This interface provides the most flexibility to clients
650 desiring simplified access to the CUnit API. The following public
651 functions are provided:
652 #include <CUnit/Basic.h>
655 CU_ErrorCode CU_basic_run_tests(void)
658 Run all tests in all registered suites. Only the active suites
659 are run, and it is not considered an error if inactive suites are
660 encountered and skipped. Returns the 1st error code occurring
661 during the test run. The type of output is controlled by the cur‐
662 rent run mode, which can be set using CU_basic_set_mode().
663 CU_ErrorCode CU_basic_run_suite(CU_pSuite pSuite)
666 Run all tests in single specified suite. Returns the 1st error
667 code occurring during the test run. CU_basic_run_suite() itself
668 generates CUE_NOSUITE if pSuite is NULL, and CUE_SUITE_INACTIVE if
669 the requested suite is not active. The type of output is con‐
670 trolled by the current run mode.
671 CU_ErrorCode CU_basic_run_test(CU_pSuite pSuite, CU_pTest pTest)
674 Run a single test in a specified suite. Returns the 1st error
675 code occurring during the test run. BU_basic_run_test() itself
676 generates CUE_NOSUITE of pSuite is NULL; CUE_NOTEST if pTest is
677 NULL; CUE_SUITE_INACTIVE if pSuite is not active for execution,
678 CUE_TEST_NOT_IN_SUITE if pTest is not a registered member of
679 pSuite, and CUE_TEST_INACTIVE if pTest is not active for execu‐
680 tion. The type of output is controlled by the current run mode.
681 void CU_basic_set_mode(CU_BasicRunMode mode)
684 Set the basic run mode, which controls the output during the run.
685 Choices are:
686 CU_BRM_NORMAL Failures and run summary are printed.
689 CU_BRM_SILENT No output is printed except error messages.
690 CU_BRM_VERBOSE Maximum output of run details.
691 CU_BasicRunMode CU_basic_get_mode(void)
693 Retrieve the current basic run mode code.
694 void CU_basic_show_failures(CU_pFailureRecord pFailure)
697 Prints a summary of all failures to stdout. Does not depend on
698 the run mode.
699 Interactive Console Interface
703 The console interface is interactive. All the client needs to do is
704 initiate the console session, and the user controls the test run inter‐
705 actively. This include selection & running of suites and tests, and
706 viewing test results.
707 #include <CUnit/Console.h>
710 void CU_console_run_tests(void)
713 Initiate an interactive test run in the console.
714 Interactive Curses Interface
718 The curses interface is interactive. All the client needs to do is
719 initiate the curses session, and the user controls the test run inter‐
720 actively. This include selection & running of suites and tests, and
721 viewing test results. Use of this interface requires linking the
722 ncurses library into the application.
723 #include <CUnit/CUCurses.h>
726 void CU_curses_run_tests(void)
729 Initiate an interactive test run in curses.
730
734 CUnit Error Status Codes
735 Many CUnit functions set a framework error code when an exception
736 occurs. The error codes are an enum named CU_ErrorCode declared in
737 header file <CUnit/CUError.h> (included automatically by
738 <CUnit/CUnit.h> ). The following functions are provided for retrieving
739 the framework error status:
740 #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
743 CU_ErrorCode CU_get_error(void)
746 Returns the framework error status code.
747 const char* CU_get_error_msg(void)
750 Returns a message for the current error code.
751 Error Actions
755 By default, CUnit continues running tests when a framework error
756 occurs. In this context, failed assertions are not considered "frame‐
757 work errors". All other error conditions including suite initializa‐
758 tion or cleanup failures, inactive suites or tests which are run
759 explicitly, etc. are included. This 'error action' can be changed by
760 the user if desired. The following functions are provided:
761 #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
764 void CU_set_error_action(CU_ErrorAction action)
767 Set the framework error action.
768 CU_ErrorAction CU_get_error_action(void)
771 Retrieve the current error action.
772 The error actions are defined in enum CU_ErrorAction in header file
775 <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h> ) as fol‐
776 lows:
777 CUEA_IGNORE Continue test runs on framework errors (default).
780 CUEA_FAIL Stop test runs on a framework error.
781 CUEA_ABORT Exit the application on a framework error.
782
786 Anil Kumar <anilsaharan@users.sourceforge.net>
787 Jerry St.Clair <jds2@users.sourceforge.net>
788
792 http://cunit.sourceforge.net
793CUnit-2.0-1 August 2004 CUnit(3)