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
454 pTest->pName data structure members. If the suite or test is
455 NULL, then CUE_NOSUITE or CUE_NOTEST is returned, respectively.
456 If strNewName is NULL, then CUE_NO_SUITENAME or CUE_NO_TESTNAME is
457 returned, respectively.
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)
493 CU_pSuite CU_get_suite_at_pos(unsigned int pos)
496 unsigned int CU_get_suite_pos(CU_pSuite pSuite)
499 unsigned int CU_get_suite_pos_by_name(const char* strName)
502 </P> These functions facilitate lookup of suites registered in the
503 active test registry. The first 2 functions allow lookup of the
504 suite by name or position and return NULL if the suite cannot be
505 found. The position is a 1-based index in the range [1 ..
506 CU_get_registry() ->uiNumberOfSuites]. This may be helpful when
507 suites having duplicate names are registered, in which case lookup
508 by name can only retrieve the 1st suite having that name. The
509 second 2 functions help the client identify the position of a reg‐
510 istered suite. These return 0 if the suite cannot be found. In
511 addition, all these functions set the CUnit error state to
512 CUE_NOREGISTRY> if the registry is not initialized. As appropri‐
513 ate, CUE_NO_SUITENAME is set if strName is NULL, and CUE_NOSUITE
514 is set if pSuite is NULL.
515 CU_pTest CU_get_test(CU_pSuite pSuite, const char *strName)
518 CU_pTest CU_get_test_at_pos<(CU_pSuite pSuite, unsigned int pos)
521 unsigned int CU_get_test_pos<(CU_pSuite pSuite, CU_pTest pTest)
524 unsigned int CU_get_test_pos_by_name(CU_pSuite pSuite, const char *str‐
527 Name)
528 These functions facilitate lookup of tests registered in suites.
529 The first 2 functions allow lookup of the test by name or position
530 and return NULL if the test cannot found. The position is a
531 1-based index in the range [1 .. pSuite->uiNumberOfSuites]. This
532 may be helpful when tests having duplicate names are registered,
533 in which case lookup by name can only retrieve the 1st test having
534 that name. The second 2 functions help the client identify the
535 position of a test in a suite. These return 0 if the test cannot
536 be found. In addition, all these functions set the CUnit error
537 state to CUE_NOREGISTRY if the registry is not initialized, and to
538 CUE_NOSUITE if pSuite is NULL. As appropriate, CUE_NO_TESTNAME is
539 set if strName is NULL, and CUE_NOTEST is set if pTest is NULL.
540
544 CUnit supports running all tests in all registered suites, but individ‐
545 ual tests or suites can also be run. During each run, the framework
546 keeps track of the number of suites, tests, and assertions run, passed,
547 and failed. Note that the previous results are cleared each time a
548 test run is initiated (even if it fails).
549 While CUnit provides primitive functions for running suites and tests,
552 most users will want to use one of the user interfaces. These inter‐
553 faces handle the details of interaction with the framework and provide
554 output of test details and results for the user. For more about the
555 primitive functions, see <CUnit/testRun.h>.
556 Test Results
560 The interfaces present results of test runs, but client code may some‐
561 times need to access the results directly. These results include vari‐
562 ous run counts, as well as a linked list of failure records holding the
563 failure details. Test results must be retrieved before attempting to
564 run other tests, which resets the result information. Functions for
565 accessing the test results are:
566 #include <CUnit/TestRun.h> (included automatically by <CUnit/CUnit.h>)
569 unsigned int CU_get_number_of_suites_run(void)'
572 Retrieve the number of suites run. Suite having initialization
573 functions which fail are not run. To get the total number of reg‐
574 istered suites, use CU_get_registry()->uiNumberOfSuites.
575 unsigned int CU_get_number_of_suites_failed(void)
578 Retrieve the number of suites which had initialization or cleanup
579 functions which failed (returned non-NULL).
580 unsigned int CU_get_number_of_tests_run(void)
583 Retrieve the number of tests run. Tests in suites having initial‐
584 ization functions which fail are not run. To get the total number
585 of registered tests , use CU_get_registry()->uiNumberOfTests.
586 unsigned int CU_get_number_of_tests_failed(void)
589 Retrieve the number of tests which contained at least 1 failed
590 assertion.
591 unsigned int CU_get_number_of_asserts(void)
594 Retrieve the number of CUnit assertions made during the test run.
595 unsigned int CU_get_number_of_successes(void)
598 Retrieve the number of assertions which passed.
599 unsigned int CU_get_number_of_failures(void)
602 Retrieve the number of assertions which failed.
603 const CU_pRunSummary CU_get_run_summary(void)
606 Retrieve a CU_RunSummary containing all the run count information.
607 This data structure is declared in <CUnit/TestRun.h> and includes
608 the (self-explanatory) unsigned int fields nSuitesRun, nSuites‐
609 Failed, nTestsRun, nTestsFailed, nAsserts, and nAssertsFailed.
610 const CU_pFailureRecord CU_get_failure_list(void)
613 Retrieve the head of the linked list of failure records for the
614 last run. Each assertion failure or suite init/cleanup function
615 failure is registered in a new CU_FailureRecord in the linked
616 list. This data structure is declared in <CUnit/TestRun.h> and
617 includes the following fields:
618 unsigned int uiLineNumber
619 char* strFileName
620 char* strCondition
621 CU_pTest pTest
622 CU_pSuite pSuite
623 Automated Interface
627 The automated interface is non-interactive. The current implementation
628 only supports running all registered suites. Results are output to an
629 xml file to be viewed by appropriate external tools. Registered tests
630 can also be listed to an xml file for viewing. The following public
631 functions are available:
632 #include <CUnit/Automated.h>
635 void CU_automated_run_tests(void)
638 Run all tests in all registered (and active) suites. Results are
639 output to a file named ROOT-Results.xml. The filename 'ROOT' is
640 set using CU_set_output_filename(), or else the default 'CUnitAu‐
641 tomated' is used. This means that the same filename is used each
642 run (and the results file overwritten) if the user does not
643 explicitly set the 'ROOT' for each run.
644 CU_ErrorCode CU_list_tests_to_file(void)
647 Lists the registered suites and associated tests to file. The
648 listing file is named ROOT-Listing.xml. The filename 'ROOT' is
649 set using CU_set_output_filename(), or else the default 'CUnitAu‐
650 tomated' is used. This means that the same filename is used each
651 run (and the listing file overwritten) if the user does not
652 explicitly set the 'ROOT' for each run.
653 void CU_set_output_filename(const char* szFilenameRoot)
656 Set the filename root to use for automated results and listing
657 files.
658 Basic Interface (non-interactive)
662 The basic interface is also non-interactive, with results output to
663 stdout. This interface supports running individual suites or tests,
664 and allows client code to control the type of output displayed during
665 each run. This interface provides the most flexibility to clients
666 desiring simplified access to the CUnit API. The following public
667 functions are provided:
668 #include <CUnit/Basic.h>
671 CU_ErrorCode CU_basic_run_tests(void)
674 Run all tests in all registered suites. Only the active suites
675 are run, and it is not considered an error if inactive suites are
676 encountered and skipped. Returns the 1st error code occurring
677 during the test run. The type of output is controlled by the cur‐
678 rent run mode, which can be set using CU_basic_set_mode().
679 CU_ErrorCode CU_basic_run_suite(CU_pSuite pSuite)
682 Run all tests in single specified suite. Returns the 1st error
683 code occurring during the test run. CU_basic_run_suite() itself
684 generates CUE_NOSUITE if pSuite is NULL, and CUE_SUITE_INACTIVE if
685 the requested suite is not active. The type of output is con‐
686 trolled by the current run mode.
687 CU_ErrorCode CU_basic_run_test(CU_pSuite pSuite, CU_pTest pTest)
690 Run a single test in a specified suite. Returns the 1st error
691 code occurring during the test run. BU_basic_run_test() itself
692 generates CUE_NOSUITE of pSuite is NULL; CUE_NOTEST if pTest is
693 NULL; CUE_SUITE_INACTIVE if pSuite is not active for execution,
694 CUE_TEST_NOT_IN_SUITE if pTest is not a registered member of
695 pSuite, and CUE_TEST_INACTIVE if pTest is not active for execu‐
696 tion. The type of output is controlled by the current run mode.
697 void CU_basic_set_mode(CU_BasicRunMode mode)
700 Set the basic run mode, which controls the output during the run.
701 Choices are:
702 CU_BRM_NORMAL Failures and run summary are printed.
705 CU_BRM_SILENT No output is printed except error messages.
706 CU_BRM_VERBOSE Maximum output of run details.
707 CU_BasicRunMode CU_basic_get_mode(void)
710 Retrieve the current basic run mode code.
711 void CU_basic_show_failures(CU_pFailureRecord pFailure)
714 Prints a summary of all failures to stdout. Does not depend on
715 the run mode.
716 Interactive Console Interface
720 The console interface is interactive. All the client needs to do is
721 initiate the console session, and the user controls the test run inter‐
722 actively. This include selection & running of suites and tests, and
723 viewing test results.
724 #include <CUnit/Console.h>
727 void CU_console_run_tests(void)
730 Initiate an interactive test run in the console.
731 Interactive Curses Interface
735 The curses interface is interactive. All the client needs to do is
736 initiate the curses session, and the user controls the test run inter‐
737 actively. This include selection & running of suites and tests, and
738 viewing test results. Use of this interface requires linking the
739 ncurses library into the application.
740 #include <CUnit/CUCurses.h>
743 void CU_curses_run_tests(void)
746 Initiate an interactive test run in curses.
747
751 CUnit Error Status Codes
752 Many CUnit functions set a framework error code when an exception
753 occurs. The error codes are an enum named CU_ErrorCode declared in
754 header file <CUnit/CUError.h> (included automatically by
755 <CUnit/CUnit.h> ). The following functions are provided for retrieving
756 the framework error status:
757 #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
760 CU_ErrorCode CU_get_error(void)
763 Returns the framework error status code.
764 const char* CU_get_error_msg(void)
767 Returns a message for the current error code.
768 Error Actions
772 By default, CUnit continues running tests when a framework error
773 occurs. In this context, failed assertions are not considered "frame‐
774 work errors". All other error conditions including suite initializa‐
775 tion or cleanup failures, inactive suites or tests which are run
776 explicitly, etc. are included. This 'error action' can be changed by
777 the user if desired. The following functions are provided:
778 #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
781 void CU_set_error_action(CU_ErrorAction action)
784 Set the framework error action.
785 CU_ErrorAction CU_get_error_action(void)
788 Retrieve the current error action.
789 The error actions are defined in enum CU_ErrorAction in header file
792 <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h> ) as fol‐
793 lows:
794 CUEA_IGNORE Continue test runs on framework errors (default).
797 CUEA_FAIL Stop test runs on a framework error.
798 CUEA_ABORT Exit the application on a framework error.
799
803 Anil Kumar <anilsaharan@users.sourceforge.net>
804 Jerry St.Clair <jds2@users.sourceforge.net>
805
809 http://cunit.sourceforge.net
810CUnit-2.0-1 August 2004 CUnit(3)