1BCUnit(3) BCUnit Programmer's Manual BCUnit(3)
2
6 BCUnit - A unit testing framework for C
7
10 #include <BCUnit/BCUnit.h> ASSERT definitions, test management.
11 #include <BCUnit/Automated.h> Automated interface with xml output.
12 #include <BCUnit/Basic.h> Basic interface with console output.
13 #include <BCUnit/Console.h> Interactive console interface.
14 #include <BCUnit/CUCurses.h> Interactive curses interface.
15
19 BCUnit is a system for writing, administering, and running unit tests
20 in C. It uses a simple framework for building test structures, and
21 provides a rich set of assertions for testing common data types. BCU‐
22 nit is built as a static library which is linked with the user's test‐
23 ing code.
24
28 BCUnit is a combination of a platform-independent framework with vari‐
29 ous user interfaces. The core framework provides basic support for man‐
30 aging a test registry, suites, and test cases. The user interfaces fa‐
31 cilitate interaction with the framework to run tests and view results.
32 The basic hierarchichal organization of BCUnit is depicted here:
35 Test Registry
38 |
39 -----------------------------
40 | |
41 Suite '1' . . . . Suite 'N'
42 | |
43 --------------- ---------------
44 | | | |
45 Test '11' ... Test '1M' Test 'N1' ... Test 'NM'
46 Individual test cases are packaged into suites, which are registered
49 with the active test registry. Suites can have setup and teardown
50 functions which are automatically called before and after running the
51 suite's tests. All suites/tests in the registry may be run using a sin‐
52 gle function call, or selected suites or tests can be run.
53 The typical usage of BCUnit is:
56 1. Write functions for tests (and suite init/cleanup if necessary).
59 2. Initialize the test registry using CU_initialize_registry()
60 3. Add test suites to the registry using CU_add_suite()
61 4. Add test cases to the suites using CU_add_test()
62 5. Run tests using the desired interface, e.g.
63 CU_console_run_tests() to use the interactive console.
64 6. Cleanup the test registry using CU_cleanup_registry()
65 All public names in BCUnit are prefixed with 'CU_'. This helps mini‐
68 mize clashes with names in user code. Note that earlier versions BCU‐
69 nit used different names without this prefix. The older API names are
70 deprecated but still supported. To use the older names, user code must
71 now be compiled with USE_DEPRECATED_BCUNIT_NAMES defined.
72
76 A "test" is a C function having the signature: void test_func(void).
77 There are no restrictions on the content of a test function, except
78 that it should not modify the BCUnit framework (e.g. add suites or
79 tests, modify the test registry, or initiate a test run). A test func‐
80 tion may call other functions (which also may not modify the frame‐
81 work). Registering a test will cause it's function to be run when the
82 test is run.
83 BCUnit provides a set of assertions for testing logical conditions.
86 The success or failure of these assertions is tracked by the framework,
87 and can be viewed when a test run is complete. Each assertion tests a
88 single logical condition, and fails if the condition evaluates to
89 CU_FALSE. Upon failure, the test continues unless the user chooses the
90 'xxx_FATAL' version of an assertion. In that case, the test function
91 returns immediately.
92 BCUnit provides a set of assertions for testing logical conditions.
94 The success or failure of these assertions is tracked by the framework,
95 and can be viewed when a test run is complete.
96 Each assertion tests a single logical condition, and fails if the con‐
99 dition evaluates to CU_FALSE. Upon failure, the test function contin‐
100 ues unless the user chooses the 'xxx_FATAL' version of an assertion.
101 In that case, the test function is aborted and returns immediately.
102 FATAL versions of assertions should be used with caution! There is no
103 opportunity for the test function to clean up after itself once a FATAL
104 assertion fails. The normal suite cleanup function is not affected,
105 however.
106 There are also special "assertions" for registering a pass or fail with
109 the framework without performing a logical test. These are useful for
110 testing flow of control or other conditions not requiring a logical
111 test.
112 Other functions called by a registered test function may use the BCUnit
115 assertions freely. These assertions will be counted for the calling
116 function. They may also use FATAL versions of assertions - failure
117 will abort the original test function and its entire call chain.
118 The assertions defined by BCUnit are:
121 #include <BCUnit/BCUnit.h>
124 CU_ASSERT(int expression)
128 CU_ASSERT_FATAL(int expression)
129 CU_TEST(int expression)
130 CU_TEST_FATAL(int expression)
131 Assert that expression is CU_TRUE (non-zero).
132 CU_ASSERT_TRUE(value)
136 CU_ASSERT_TRUE_FATAL(value)
137 Assert that value is CU_TRUE (non-zero).
138 CU_ASSERT_FALSE(value)
142 CU_ASSERT_FALSE_FATAL(value)
143 Assert that value is CU_FALSE (zero).
144 CU_ASSERT_EQUAL(actual, expected)
148 CU_ASSERT_EQUAL_FATAL(actual, expected)
149 Assert that actual == expected.
150 CU_ASSERT_NOT_EQUAL(actual, expected)
154 CU_ASSERT_NOT_EQUAL_FATAL(actual, expected)
155 Assert that actual != expected.
156 CU_ASSERT_PTR_EQUAL(actual, expected)
160 CU_ASSERT_PTR_EQUAL_FATAL(actual, expected)
161 Assert that pointers actual == expected.
162 CU_ASSERT_PTR_NOT_EQUAL(actual, expected)
166 CU_ASSERT_PTR_NOT_EQUAL_FATAL(actual, expected)
167 Assert that pointers actual != expected.
168 CU_ASSERT_PTR_NULL(value)
172 CU_ASSERT_PTR_NULL_FATAL(value)
173 Assert that pointer value == NULL.
174 CU_ASSERT_PTR_NOT_NULL(value)
178 CU_ASSERT_PTR_NOT_NULL_FATAL(value)
179 Assert that pointer value != NULL.
180 CU_ASSERT_STRING_EQUAL(actual, expected)
184 CU_ASSERT_STRING_EQUAL_FATAL(actual, expected)
185 Assert that strings actual and expected are equivalent.
186 CU_ASSERT_STRING_NOT_EQUAL(actual, expected)
190 CU_ASSERT_STRING_NOT_EQUAL_FATAL(actual, expected)
191 Assert that strings actual and expected differ.
192 CU_ASSERT_NSTRING_EQUAL(actual, expected, count)
196 CU_ASSERT_NSTRING_EQUAL_FATAL(actual, expected, count)
197 Assert that 1st count chars of actual and expected are the same.
198 CU_ASSERT_NSTRING_NOT_EQUAL(actual, expected, count)
202 CU_ASSERT_NSTRING_NOT_EQUAL_FATAL(actual, expected, count)
203 Assert that 1st count chars of actual and expected differ.
204 CU_ASSERT_DOUBLE_EQUAL(actual, expected, granularity)
208 CU_ASSERT_DOUBLE_EQUAL_FATAL(actual, expected, granularity)
209 Assert that |actual - expected| <= |granularity|.
210 Math library must be linked in for this assertion.
211 CU_ASSERT_DOUBLE_NOT_EQUAL(actual, expected, granularity)
215 CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL(actual, expected, granularity)
216 Assert that |actual - expected| > |granularity|.
217 Math library must be linked in for this assertion.
218 CU_PASS(message)
222 Register a success without performing a logical test.
223 CU_FAIL(message)
227 CU_FAIL_FATAL(message)
228 Register a failure without performing a logical test.
229
233 The test registry is the repository for suites and associated tests.
234 The user normally only needs to initialize the registry before use and
235 clean up afterwards. However, other functions are provided to manipu‐
236 late the registry when necessary.
237 The main functions needed by clients are:
240 #include <BCUnit/TestDB.h> (included automatically by <BCUnit/BCU‐
243 nit.h>)
244 CU_ErrorCode CU_initialize_registry(void)
247 Initializes the framework. This function should be called before
248 any other BCUnit functions. Failure to do so will likely result
249 in a crash. An error status code is returned:
250 CUE_SUCCESS if initialization is successful.
253 CUE_NOMEMORY if memory allocation failed.
256 CU_BOOL CU_registry_initialized(void)
260 Checks whether the framework has been initialized. This may be
261 useful if the registry setup is distributed over multiple files
262 that need to make sure the registry is ready for test registra‐
263 tion.
264 void CU_cleanup_registry(void)
268 Cleans up and releases memory used by the framework. No BCUnit
269 functions (other than CU_initialize_registry() ) should be called
270 after this function. Failure to call CU_cleanup_registry() will
271 result in memory leaks. Note also that this function will destroy
272 all suites (and associated tests) in the registry.
273 Other registry functions are primarily for internal and testing pur‐
276 poses. However, general users may find use for them and should be
277 aware of them. These include:
278 CU_pTestRegistry CU_get_registry(void)
281 Retrieve a pointer to the active test registry. The registry is a
282 variable of data type CU_Testregistry (declared in <BCU‐
283 nit/TestDB.h>). Note that the returned pointer will be invali‐
284 dated by a call to CU_cleanup_registry() or CU_initialize_reg‐
285 istry()
286 CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)
290 Replace the active registry with the specified one. A pointer to
291 the previous registry is returned. It is the caller's responsi‐
292 bility to destroy the old registry. This can be accomplished us‐
293 ing CU_destroy_existing_registry() on the returned pointer. Al‐
294 ternatively, the old registry can be set as the active one. A
295 subsequent call to CU_cleanup_registry() will then destroy it au‐
296 tomatically. Care should be taken not to explicitly destroy a
297 registry that is set as the active one. This will result in mul‐
298 tiple frees of the same memory and a likely crash.
299 CU_pTestRegistry CU_create_new_registry(void)
302 Create a new registry and return a pointer to it. The new reg‐
303 istry will not contain any suites or tests. It is the caller's
304 responsibility to destroy the new registry by one of the mecha‐
305 nisms described previously.
306 void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
309 Destroy the specified test registry, including any registered
310 suites. This function should not be called for a registry which
311 is set as the active test registry. This will result in a multi‐
312 ple free of the same memory when CU_cleanup_registry() is called.
313 ppRegistry may not be NULL, but the pointer it points to may be.
314 Note that *ppRegistry will be NULL on return.
315
319 In order for a test to be run by BCUnit, it must be added to a test
320 collection (suite) which is registered with the test registry.
321 Adding Suites to the Registry
324 The first step in setting up a test system is creating and registering
325 one or more test collections (suites). Each suite has a name which may
326 be used to reference the suite. Therefore, it is recommended (but not
327 required) that each registered suite have a unique name. The current
328 implementation does not support the creation of suites independent of
329 the test registry. Suites are simultaneously created and added to the
330 active registry as follows.
331 #include <BCUnit/TestDB.h> (included automatically by <BCUnit/BCU‐
334 nit.h>)
335 CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit,
338 CU_CleanupFunc pClean)" This creates and registers a new suite
339 having the specified name, initialization function, and cleanup
340 function. A pointer to the new suite is returned for use in
341 adding tests to the suite. This pointer will be NULL if a fatal
342 error occurs. In addition, the framework error status is set as
343 follows:
344 CUE_SUCCESS The suite was successfully created and regis‐
347 tered.
348 CUE_NOREGISTRY Error: Test Registry is not initialized.
351 CUE_NO_SUITENAME Error: Suite name is not specified or NULL.
354 CUE_DUP_SUITE Warning: The registry already has a suite with
357 this name.
358 CUE_NOMEMORY Error: Memory allocation failed.
361 The initialization and cleanup functions are optional. Both are C
364 functions having the signature int func_name(void). These func‐
365 tions can perform setup and teardown operations needed to support
366 the suite's tests. They are called before and after the suite's
367 tests are run, even if only 1 of the suite's tests is run. They
368 take no arguments, and should return NULL if they complete suc‐
369 cessfully (non-NULL otherwise). If either function is not re‐
370 quired for a particular suite, pass NULL to CU_add_suite().
371 Adding Tests to Suites
375 Tests are created and added to suites. Each test has a name which may
376 be used to reference the test later. Therefore, it is recommended (but
377 not required) that the name be unique among all tests added to a single
378 suite. The current implementation does not support the creation of
379 tests independent of registered suites. Tests are simultaneously cre‐
380 ated and added to a suite as follows.
381 #include <BCUnit/TestDB.h> (included automatically by <BCUnit/BCU‐
384 nit.h>)
385 CU_pTest CU_add_test(CU_pSuite pSuite, const char* strName, CU_Test‐
388 Func
389 pTestFunc)" This creates a new test having the specified name and
390 test function, and adds it to the indicated suite. The suite
391 should have been previously created using CU_add_suite(). A
392 pointer to the new test is returned, which will be NULL if a fatal
393 error occurred. In addition, the framework error status is set as
394 follows:
395 CUE_SUCCESS The test was successfully created and added.
398 CUE_NOREGISTRY Error: Test Registry is not initialized.
401 CUE_NOSUITE Error: Specified suite is NULL or invalid.
404 CUE_NO_TESTNAME Error: Test name is not specified or NULL.
407 CUE_NOTEST Error: Test function is not specified or NULL.
410 CUE_DUP_TEST Warning: The suite already has a test with this
413 name.
414 CUE_NOMEMORY Error: Memory allocation failed.
417 Activation of Suites and Tests
421 A suite or test must be active to be executed during a test run (all
422 suites and tests are active by default upon creation). The active
423 state of a suite or test is available as pSuite->fActive and
424 pTest->fActive, respectively. The flag will be CU_TRUE when the entity
425 is active, CU_FALSE otherwise. Use the following functions to selec‐
426 tively deactivate suites and tests to choose subsets of tests to run
427 dynamically. Note that it is a framework error to deactivate a test or
428 suite and then specifically request that it be run.
429 #include <BCUnit/TestDB.h> (included automatically by <BCUnit/BCU‐
432 nit.h>)
433 CU_ErrorCode CU_set_suite_active(CU_pSuite pSuite, CU_BOOL fNewActive)
436 CU_ErrorCode CU_set_test_active(CU_pTest pTest, CU_BOOL fNewActive)
439 Pass CU_TRUE to these functions to activate a suite/test, CU_FALSE
440 to deactivate it. These functions return CUE_NOSUITE and
441 CUE_NOTEST, respectively, if the specified suite or test is NULL.
442 Modifying Other Attributes of Suites and Tests
446 Normally the attributes of suites and tests are set at creation time.
447 In some cases, a client may wish to manipulate these to modify the test
448 structure dynamically. The following functions are provided for this
449 purpose, and should be used instead of directly setting the value of
450 the data structure members. All return CUE_SUCCESS on success, and the
451 indicated error code on failure.
452 CU_ErrorCode CU_set_suite_name(CU_pSuite pSuite, const char *strNew‐
455 Name)
456 CU_ErrorCode CU_set_test_name(CU_pTest pTest, const char *strNewName)
459 These functions change the name of registered suites and tests.
460 The current names are available as the pSuite->pName</I> and data
461 structure members. If the suite or test is NULL, then CUE_NOSUITE
462 or CUE_NOTEST is returned, respectively. If strNewName is NULL,
463 then CUE_NO_SUITENAME or CUE_NO_TESTNAME is returned, respec‐
464 tively.
465 CU_ErrorCode CU_set_suite_initfunc(CU_pSuite pSuite, CU_InitializeFunc
468 pNewInit)
469 CU_ErrorCode CU_set_suite_cleanupfunc(CU_pSuite pSuite, CU_CleanupFunc
472 pNewClean)
473 These functions change the initialization and cleanup functions
474 for a registered suite. The current functions are available as
475 the pSuite->pInitializeFunc and pSuite->pCleanupFunc data struc‐
476 ture members. If the suite is NULL then CUE_NOSUITE is returned.
477 CU_ErrorCode CU_set_test_func(CU_pTest pTest, CU_TestFunc pNewFunc)
480 This function changes the test function for a registered test.
481 The current test function is available as the pTest->pTestFunc</I>
482 data structure member. If either pTest or pNewFunc is NULL, then
483 CUE_NOTEST is returned.
484 Lookup of Individual Suites and Tests
488 In most cases, clients will have references to registered suites and
489 tests as pointers returned from CU_add_suite() and CU_add_test(). Oc‐
490 cassionally, a client may need to be able to retrieve a reference to a
491 suite or test. The following functions are provided to assist clients
492 with this when the client has some information about the entity (name
493 or order of registration). In cases where nothing is known about the
494 suite or test, the client will need to iterate the internal data struc‐
495 tures to enumerate the suites and tests. This is not directly sup‐
496 ported in the client API.
497 CU_pSuite CU_get_suite(const char* strName) CU_pSuite
500 CU_get_suite_at_pos(unsigned int pos) unsigned int
501 CU_get_suite_pos(CU_pSuite pSuite) unsigned int
502 CU_get_suite_pos_by_name(const char* strName) </P> These functions fa‐
503 cilitate lookup of suites registered in the active test registry. The
504 first 2 functions allow lookup of the suite by name or position and re‐
505 turn NULL if the suite cannot be found. The position is a 1-based in‐
506 dex in the range [1 .. CU_get_registry() ->uiNumberOfSuites]. This
507 may be helpful when suites having duplicate names are registered, in
508 which case lookup by name can only retrieve the 1st suite having that
509 name. The second 2 functions help the client identify the position of
510 a registered suite. These return 0 if the suite cannot be found. In
511 addition, all these functions set the BCUnit error state to CUE_NOREG‐
512 ISTRY> if the registry is not initialized. As appropriate,
513 CUE_NO_SUITENAME is set if strName is NULL, and CUE_NOSUITE is set if
514 pSuite is NULL.
515 CU_pTest CU_get_test(CU_pSuite pSuite, const char *strName) CU_pTest
518 CU_get_test_at_pos<(CU_pSuite pSuite, unsigned int pos) unsigned int
519 CU_get_test_pos<(CU_pSuite pSuite, CU_pTest pTest) unsigned int
520 CU_get_test_pos_by_name(CU_pSuite pSuite, const char *strName) These
521 functions facilitate lookup of tests registered in suites. The first 2
522 functions allow lookup of the test by name or position and return NULL
523 if the test cannot found. The position is a 1-based index in the range
524 [1 .. pSuite->uiNumberOfSuites]. This may be helpful when tests having
525 duplicate names are registered, in which case lookup by name can only
526 retrieve the 1st test having that name. The second 2 functions help
527 the client identify the position of a test in a suite. These return 0
528 if the test cannot be found. In addition, all these functions set the
529 BCUnit error state to CUE_NOREGISTRY if the registry is not initial‐
530 ized, and to CUE_NOSUITE if pSuite is NULL. As appropriate,
531 CUE_NO_TESTNAME is set if strName is NULL, and CUE_NOTEST is set if
532 pTest is NULL.
533
537 BCUnit supports running all tests in all registered suites, but indi‐
538 vidual tests or suites can also be run. During each run, the framework
539 keeps track of the number of suites, tests, and assertions run, passed,
540 and failed. Note that the previous results are cleared each time a
541 test run is initiated (even if it fails).
542 While BCUnit provides primitive functions for running suites and tests,
545 most users will want to use one of the user interfaces. These inter‐
546 faces handle the details of interaction with the framework and provide
547 output of test details and results for the user. For more about the
548 primitive functions, see <BCUnit/testRun.h>.
549 Test Results
553 The interfaces present results of test runs, but client code may some‐
554 times need to access the results directly. These results include vari‐
555 ous run counts, as well as a linked list of failure records holding the
556 failure details. Test results must be retrieved before attempting to
557 run other tests, which resets the result information. Functions for
558 accessing the test results are:
559 #include <BCUnit/TestRun.h> (included automatically by <BCUnit/BCU‐
562 nit.h>)
563 unsigned int CU_get_number_of_suites_run(void)'
566 Retrieve the number of suites run. Suite having initialization
567 functions which fail are not run. To get the total number of reg‐
568 istered suites, use CU_get_registry()->uiNumberOfSuites.
569 unsigned int CU_get_number_of_suites_failed(void)
572 Retrieve the number of suites which had initialization or cleanup
573 functions which failed (returned non-NULL).
574 unsigned int CU_get_number_of_tests_run(void)
577 Retrieve the number of tests run. Tests in suites having initial‐
578 ization functions which fail are not run. To get the total number
579 of registered tests , use CU_get_registry()->uiNumberOfTests.
580 unsigned int CU_get_number_of_tests_failed(void)
583 Retrieve the number of tests which contained at least 1 failed as‐
584 sertion.
585 unsigned int CU_get_number_of_asserts(void)
588 Retrieve the number of BCUnit assertions made during the test run.
589 unsigned int CU_get_number_of_successes(void)
592 Retrieve the number of assertions which passed.
593 unsigned int CU_get_number_of_failures(void)
596 Retrieve the number of assertions which failed.
597 const CU_pRunSummary CU_get_run_summary(void)
600 Retrieve a CU_RunSummary containing all the run count information.
601 This data structure is declared in <BCUnit/TestRun.h> and includes
602 the (self-explanatory) unsigned int fields nSuitesRun, nSuites‐
603 Failed, nTestsRun, nTestsFailed, nAsserts, and nAssertsFailed.
604 const CU_pFailureRecord CU_get_failure_list(void)
607 Retrieve the head of the linked list of failure records for the
608 last run. Each assertion failure or suite init/cleanup function
609 failure is registered in a new CU_FailureRecord in the linked
610 list. This data structure is declared in <BCUnit/TestRun.h> and
611 includes the following fields:
612 unsigned int uiLineNumber
613 char* strFileName
614 char* strCondition
615 CU_pTest pTest
616 CU_pSuite pSuite
617 Automated Interface
621 The automated interface is non-interactive. The current implementation
622 only supports running all registered suites. Results are output to an
623 xml file to be viewed by appropriate external tools. Registered tests
624 can also be listed to an xml file for viewing. The following public
625 functions are available:
626 #include <BCUnit/Automated.h>
629 void CU_automated_run_tests(void)
632 Run all tests in all registered (and active) suites. Results are
633 output to a file named ROOT-Results.xml. The filename 'ROOT' is
634 set using CU_set_output_filename(), or else the default 'BCUnitAu‐
635 tomated' is used. This means that the same filename is used each
636 run (and the results file overwritten) if the user does not ex‐
637 plicitly set the 'ROOT' for each run.
638 CU_ErrorCode CU_list_tests_to_file(void)
641 Lists the registered suites and associated tests to file. The
642 listing file is named ROOT-Listing.xml. The filename 'ROOT' is
643 set using CU_set_output_filename(), or else the default 'BCUnitAu‐
644 tomated' is used. This means that the same filename is used each
645 run (and the listing file overwritten) if the user does not ex‐
646 plicitly set the 'ROOT' for each run.
647 void CU_set_output_filename(const char* szFilenameRoot)
650 Set the filename root to use for automated results and listing
651 files.
652 Basic Interface (non-interactive)
656 The basic interface is also non-interactive, with results output to
657 stdout. This interface supports running individual suites or tests,
658 and allows client code to control the type of output displayed during
659 each run. This interface provides the most flexibility to clients de‐
660 siring simplified access to the BCUnit API. The following public func‐
661 tions are provided:
662 #include <BCUnit/Basic.h>
665 CU_ErrorCode CU_basic_run_tests(void)
668 Run all tests in all registered suites. Only the active suites
669 are run, and it is not considered an error if inactive suites are
670 encountered and skipped. Returns the 1st error code occurring
671 during the test run. The type of output is controlled by the cur‐
672 rent run mode, which can be set using CU_basic_set_mode().
673 CU_ErrorCode CU_basic_run_suite(CU_pSuite pSuite)
676 Run all tests in single specified suite. Returns the 1st error
677 code occurring during the test run. CU_basic_run_suite() itself
678 generates CUE_NOSUITE if pSuite is NULL, and CUE_SUITE_INACTIVE if
679 the requested suite is not active. The type of output is con‐
680 trolled by the current run mode.
681 CU_ErrorCode CU_basic_run_test(CU_pSuite pSuite, CU_pTest pTest)
684 Run a single test in a specified suite. Returns the 1st error
685 code occurring during the test run. BU_basic_run_test() itself
686 generates CUE_NOSUITE of pSuite is NULL; CUE_NOTEST if pTest is
687 NULL; CUE_SUITE_INACTIVE if pSuite is not active for execution,
688 CUE_TEST_NOT_IN_SUITE if pTest is not a registered member of
689 pSuite, and CUE_TEST_INACTIVE if pTest is not active for execu‐
690 tion. The type of output is controlled by the current run mode.
691 void CU_basic_set_mode(CU_BasicRunMode mode)
694 Set the basic run mode, which controls the output during the run.
695 Choices are:
696 CU_BRM_NORMAL Failures and run summary are printed.
699 CU_BRM_SILENT No output is printed except error messages.
700 CU_BRM_VERBOSE Maximum output of run details.
701 CU_BasicRunMode CU_basic_get_mode(void)
704 Retrieve the current basic run mode code.
705 void CU_basic_show_failures(CU_pFailureRecord pFailure)
708 Prints a summary of all failures to stdout. Does not depend on
709 the run mode.
710 Interactive Console Interface
714 The console interface is interactive. All the client needs to do is
715 initiate the console session, and the user controls the test run inter‐
716 actively. This include selection & running of suites and tests, and
717 viewing test results.
718 #include <BCUnit/Console.h>
721 void CU_console_run_tests(void)
724 Initiate an interactive test run in the console.
725 Interactive Curses Interface
728 The curses interface is interactive. All the client needs to do is
729 initiate the curses session, and the user controls the test run inter‐
730 actively. This include selection & running of suites and tests, and
731 viewing test results. Use of this interface requires linking the
732 ncurses library into the application.
733 #include <BCUnit/CUCurses.h>
736 void CU_curses_run_tests(void)
739 Initiate an interactive test run in curses.
740
744 BCUnit Error Status Codes
745 Many BCUnit functions set a framework error code when an exception oc‐
746 curs. The error codes are an enum named CU_ErrorCode declared in
747 header file <BCUnit/CUError.h> (included automatically by <BCUnit/BCU‐
748 nit.h> ). The following functions are provided for retrieving the
749 framework error status:
750 #include <BCUnit/CUError.h> (included automatically by <BCUnit/BCU‐
753 nit.h>)
754 CU_ErrorCode CU_get_error(void)
757 Returns the framework error status code.
758 const char* CU_get_error_msg(void)
761 Returns a message for the current error code.
762 Error Actions
766 By default, BCUnit continues running tests when a framework error oc‐
767 curs. In this context, failed assertions are not considered "framework
768 errors". All other error conditions including suite initialization or
769 cleanup failures, inactive suites or tests which are run explicitly,
770 etc. are included. This 'error action' can be changed by the user if
771 desired. The following functions are provided:
772 #include <BCUnit/CUError.h> (included automatically by <BCUnit/BCU‐
775 nit.h>)
776 void CU_set_error_action(CU_ErrorAction action)
779 Set the framework error action.
780 CU_ErrorAction CU_get_error_action(void)
783 Retrieve the current error action.
784 The error actions are defined in enum CU_ErrorAction in header file
787 <BCUnit/CUError.h> (included automatically by <BCUnit/BCUnit.h> ) as
788 follows:
789 CUEA_IGNORE Continue test runs on framework errors (default).
792 CUEA_FAIL Stop test runs on a framework error.
793 CUEA_ABORT Exit the application on a framework error.
794
798 Anil Kumar <anilsaharan@users.sourceforge.net>
799 Jerry St.Clair <jds2@users.sourceforge.net>
800
804 https://github.com/BelledonneCommunications/bcunit
805BCUnit-2.0-1 August 2004 BCUnit(3)