|BCUnit(3)||BCUnit Programmer's Manual||BCUnit(3)|
- #include <BCUnit/BCUnit.h>
- ASSERT definitions, test management.
- #include <BCUnit/Automated.h>
- Automated interface with xml output.
- #include <BCUnit/Basic.h>
- Basic interface with console output.
- #include <BCUnit/Console.h>
- Interactive console interface.
- #include <BCUnit/CUCurses.h>
- Interactive curses interface.
Suite '1' . . . . Suite 'N'
| | | |
Test '11' ... Test '1M' Test 'N1' ... Test 'NM'
1. Write functions for tests (and suite init/cleanup if necessary).
2. Initialize the test registry using CU_initialize_registry()
3. Add test suites to the registry using CU_add_suite()
4. Add test cases to the suites using CU_add_test()
- 5. Run tests using the desired interface, e.g.
- CU_console_run_tests() to use the interactive console.
6. Cleanup the test registry using CU_cleanup_registry()All public names in BCUnit are prefixed with 'CU_'. This helps minimize clashes with names in user code. Note that earlier versions BCUnit used different names without this prefix. The older API names are deprecated but still supported. To use the older names, user code must now be compiled with USE_DEPRECATED_BCUNIT_NAMES defined.
Assert that expression is CU_TRUE (non-zero).
Assert that value is CU_TRUE (non-zero).
Assert that value is CU_FALSE (zero).
Assert that actual == expected.
Assert that actual != expected.
Assert that pointers actual == expected.
Assert that pointers actual != expected.
Assert that pointer value == NULL.
Assert that pointer value != NULL.
Assert that strings actual and expected are equivalent.
Assert that strings actual and expected differ.
Assert that 1st count chars of actual and expected are the same.
Assert that 1st count chars of actual and expected differ.
Assert that |actual - expected| <= |granularity|.Math library must be linked in for this assertion.
Assert that |actual - expected| > |granularity|.Math library must be linked in for this assertion.
Register a success without performing a logical test.
Register a failure without performing a logical test.
- CU_ErrorCode CU_initialize_registry(void)
- Initializes the framework. This function should be called before any other BCUnit functions. Failure to do so will likely result in a crash. An error status code is returned:
- if initialization is successful.
- if memory allocation failed.
- CU_BOOL CU_registry_initialized(void)
- Checks whether the framework has been initialized. This may
be useful if the registry setup is distributed over multiple files that
need to make sure the registry is ready for test registration.
- void CU_cleanup_registry(void)
- Cleans up and releases memory used by the framework. No BCUnit functions (other than CU_initialize_registry() ) should be called after this function. Failure to call CU_cleanup_registry() will result in memory leaks. Note also that this function will destroy all suites (and associated tests) in the registry.
- CU_pTestRegistry CU_get_registry(void)
- Retrieve a pointer to the active test registry. The
registry is a variable of data type CU_Testregistry (declared in
<BCUnit/TestDB.h>). Note that the returned pointer will be
invalidated by a call to CU_cleanup_registry() or
- CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)
- Replace the active registry with the specified one. A pointer to the previous registry is returned. It is the caller's responsibility to destroy the old registry. This can be accomplished using CU_destroy_existing_registry() on the returned pointer. Alternatively, the old registry can be set as the active one. A subsequent call to CU_cleanup_registry() will then destroy it automatically. Care should be taken not to explicitly destroy a registry that is set as the active one. This will result in multiple frees of the same memory and a likely crash.
- CU_pTestRegistry CU_create_new_registry(void)
- Create a new registry and return a pointer to it. The new registry will not contain any suites or tests. It is the caller's responsibility to destroy the new registry by one of the mechanisms described previously.
- void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
- Destroy the specified test registry, including any
registered suites. This function should not be called for a registry which
is set as the active test registry. This will result in a multiple free of
the same memory when CU_cleanup_registry() is called. ppRegistry
may not be NULL, but the pointer it points to may be. Note that
*ppRegistry will be NULL on return.
- CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit,
- CU_CleanupFunc pClean)" This creates and registers a new suite having the specified name, initialization function, and cleanup function. A pointer to the new suite is returned for use in adding tests to the suite. This pointer will be NULL if a fatal error occurs. In addition, the framework error status is set as follows:
- The suite was successfully created and registered.
- Error: Test Registry is not initialized.
- Error: Suite name is not specified or NULL.
- Warning: The registry already has a suite with this name.
- Error: Memory allocation failed.
- The initialization and cleanup functions are optional. Both
are C functions having the signature int func_name(void). These
functions can perform setup and teardown operations needed to support the
suite's tests. They are called before and after the suite's tests are run,
even if only 1 of the suite's tests is run. They take no arguments, and
should return NULL if they complete successfully (non-NULL otherwise). If
either function is not required for a particular suite, pass NULL to
- CU_pTest CU_add_test(CU_pSuite pSuite, const char* strName, CU_TestFunc
- pTestFunc)" This creates a new test having the specified name and test function, and adds it to the indicated suite. The suite should have been previously created using CU_add_suite(). A pointer to the new test is returned, which will be NULL if a fatal error occurred. In addition, the framework error status is set as follows:
- The test was successfully created and added.
- Error: Test Registry is not initialized.
- Error: Specified suite is NULL or invalid.
- Error: Test name is not specified or NULL.
- Error: Test function is not specified or NULL.
- Warning: The suite already has a test with this name.
- Error: Memory allocation failed.
- CU_ErrorCode CU_set_suite_active(CU_pSuite pSuite, CU_BOOL fNewActive)
- CU_ErrorCode CU_set_test_active(CU_pTest pTest, CU_BOOL fNewActive)
- Pass CU_TRUE to these functions to activate a suite/test,
CU_FALSE to deactivate it. These functions return CUE_NOSUITE and
CUE_NOTEST, respectively, if the specified suite or test is NULL.
- CU_ErrorCode CU_set_test_name(CU_pTest pTest, const char *strNewName)
- These functions change the name of registered suites and tests. The current names are available as the pSuite->pName</I> and data structure members. If the suite or test is NULL, then CUE_NOSUITE or CUE_NOTEST is returned, respectively. If strNewName is NULL, then CUE_NO_SUITENAME or CUE_NO_TESTNAME is returned, respectively.
- CU_ErrorCode CU_set_suite_initfunc(CU_pSuite pSuite, CU_InitializeFunc pNewInit)
- CU_ErrorCode CU_set_suite_cleanupfunc(CU_pSuite pSuite, CU_CleanupFunc pNewClean)
- These functions change the initialization and cleanup functions for a registered suite. The current functions are available as the pSuite->pInitializeFunc and pSuite->pCleanupFunc data structure members. If the suite is NULL then CUE_NOSUITE is returned.
- CU_ErrorCode CU_set_test_func(CU_pTest pTest, CU_TestFunc pNewFunc)
- This function changes the test function for a registered
test. The current test function is available as the
pTest->pTestFunc</I> data structure member. If either
pTest or pNewFunc is NULL, then CUE_NOTEST is returned.
- unsigned int CU_get_number_of_suites_run(void)'
- Retrieve the number of suites run. Suite having initialization functions which fail are not run. To get the total number of registered suites, use CU_get_registry()->uiNumberOfSuites.
- unsigned int CU_get_number_of_suites_failed(void)
- Retrieve the number of suites which had initialization or cleanup functions which failed (returned non-NULL).
- unsigned int CU_get_number_of_tests_run(void)
- Retrieve the number of tests run. Tests in suites having initialization functions which fail are not run. To get the total number of registered tests , use CU_get_registry()->uiNumberOfTests.
- unsigned int CU_get_number_of_tests_failed(void)
- Retrieve the number of tests which contained at least 1 failed assertion.
- unsigned int CU_get_number_of_asserts(void)
- Retrieve the number of BCUnit assertions made during the test run.
- unsigned int CU_get_number_of_successes(void)
- Retrieve the number of assertions which passed.
- unsigned int CU_get_number_of_failures(void)
- Retrieve the number of assertions which failed.
- const CU_pRunSummary CU_get_run_summary(void)
- Retrieve a CU_RunSummary containing all the run count information. This data structure is declared in <BCUnit/TestRun.h> and includes the (self-explanatory) unsigned int fields nSuitesRun, nSuitesFailed, nTestsRun, nTestsFailed, nAsserts, and nAssertsFailed.
- const CU_pFailureRecord CU_get_failure_list(void)
- Retrieve the head of the linked list of failure records for
the last run. Each assertion failure or suite init/cleanup function
failure is registered in a new CU_FailureRecord in the linked list.
This data structure is declared in <BCUnit/TestRun.h> and
includes the following fields:
unsigned int uiLineNumberchar* strFileNamechar* strConditionCU_pTest pTestCU_pSuite pSuite
- void CU_automated_run_tests(void)
- Run all tests in all registered (and active) suites. Results are output to a file named ROOT-Results.xml. The filename 'ROOT' is set using CU_set_output_filename(), or else the default 'BCUnitAutomated' is used. This means that the same filename is used each run (and the results file overwritten) if the user does not explicitly set the 'ROOT' for each run.
- CU_ErrorCode CU_list_tests_to_file(void)
- Lists the registered suites and associated tests to file. The listing file is named ROOT-Listing.xml. The filename 'ROOT' is set using CU_set_output_filename(), or else the default 'BCUnitAutomated' is used. This means that the same filename is used each run (and the listing file overwritten) if the user does not explicitly set the 'ROOT' for each run.
- void CU_set_output_filename(const char* szFilenameRoot)
- Set the filename root to use for automated results and
- CU_ErrorCode CU_basic_run_tests(void)
- Run all tests in all registered suites. Only the active suites are run, and it is not considered an error if inactive suites are encountered and skipped. Returns the 1st error code occurring during the test run. The type of output is controlled by the current run mode, which can be set using CU_basic_set_mode().
- CU_ErrorCode CU_basic_run_suite(CU_pSuite pSuite)
- Run all tests in single specified suite. Returns the 1st error code occurring during the test run. CU_basic_run_suite() itself generates CUE_NOSUITE if pSuite is NULL, and CUE_SUITE_INACTIVE if the requested suite is not active. The type of output is controlled by the current run mode.
- CU_ErrorCode CU_basic_run_test(CU_pSuite pSuite, CU_pTest pTest)
- Run a single test in a specified suite. Returns the 1st error code occurring during the test run. BU_basic_run_test() itself generates CUE_NOSUITE of pSuite is NULL; CUE_NOTEST if pTest is NULL; CUE_SUITE_INACTIVE if pSuite is not active for execution, CUE_TEST_NOT_IN_SUITE if pTest is not a registered member of pSuite, and CUE_TEST_INACTIVE if pTest is not active for execution. The type of output is controlled by the current run mode.
- void CU_basic_set_mode(CU_BasicRunMode mode)
- Set the basic run mode, which controls the output during the run. Choices are:
- Failures and run summary are printed.
- No output is printed except error messages.
- Maximum output of run details.
- CU_BasicRunMode CU_basic_get_mode(void)
- Retrieve the current basic run mode code.
- void CU_basic_show_failures(CU_pFailureRecord pFailure)
- Prints a summary of all failures to stdout. Does not depend
on the run mode.
- void CU_console_run_tests(void)
- Initiate an interactive test run in the console.
- void CU_curses_run_tests(void)
- Initiate an interactive test run in curses.
- CU_ErrorCode CU_get_error(void)
- Returns the framework error status code.
- const char* CU_get_error_msg(void)
- Returns a message for the current error code.
- void CU_set_error_action(CU_ErrorAction action)
- Set the framework error action.
- CU_ErrorAction CU_get_error_action(void)
- Retrieve the current error action.
- Continue test runs on framework errors (default).
- Stop test runs on a framework error.
- Exit the application on a framework error.