cunit.3

cunit

.TP 5
.B "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
.B 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.

.SH "MANAGING TESTS AND SUITES"
In order for a test to be run by CUnit, it must be added to a
test collection (suite) which is registered with the test registry.
.SS "Adding Suites to the Registry"
The first step in setting up a test system is creating and
registering one or more test collections (suites).  Each suite has
a name which must be unique among all suites registered with the
test registry.  The current implementation does not support the
creation of suites independent of the test registry.  Suites are
simultaneously created and added to the active registry as follows.
.P
.B #include <CUnit/TestDB.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "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.  If an error
occurs during the operation, NULL is returned and the framework error
status is set as follows:
.RS 5
.TP 18
CUE_NOREGISTRY
Test Registry is not initialized.
.TP 18
CUE_NO_SUITENAME
Suite name is not specified or NULL.
.TP 18
CUE_DUP_SUITE
The registry already has a suite with this name.
.TP 18
CUE_NOMEMORY
Memory allocation failed.
.RE
.IP "" 5
The initialization and cleanup functions are optional.  Both are C
functions having the signature
.B "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
.B CU_add_suite().

.SS "Adding Tests to Suites"
Tests are created and added to suites.  Each test has a name which must be
unique among all tests added to a single suite.  The current implementation
does not support the creation of tests independent of registered suites.
Tests are simultaneously created and added to a suite as follows.
.P
.B #include <CUnit/TestDB.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "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
.B CU_add_suite().
A pointer to the new test is returned.  If an error occurs during the
operation, NULL is returned and the framework error status is set as follows:
.RS 5
.TP 18
CUE_NOSUITE
Specified suite is NULL or invalid.
.TP 18
CUE_NO_TESTNAME
Test name is not specified or NULL.
.TP 18
CUE_NOTEST
Test function is not specified or NULL.
.TP 18
CUE_DUP_TEST
The suite already has a test with this name.
.TP 18
CUE_NOMEMORY
Memory allocation failed.

.SH "RUNNING TESTS"
CUnit supports running all tests in all registered suites, but individual tests
or suites can also be run.  During each run, the framework keeps track of the 
number of suites, tests, and assertions run, passed, and failed.  Note that the
results are cleared each time a test run is initiated (even if it fails).
.P
While CUnit provides primitive functions for running suites and tests, most
users will want to use one of the user interfaces.  These interfaces handle
the details of interaction with the framework and provide output of test
details and results for the user.  For more about the primitive functions, see
.B <CUnit/testRun.h>.

.SS "Test Results"
The interfaces present results of test runs, but client code may sometimes need
to access the results directly.  These results include various run counts, as
well as a linked list of failure records holding the failure details.  Test
results must be retrieved before attempting to run other tests, which
resets the result information.  Functions for accessing the test results are:
.P
.B #include <CUnit/TestRun.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "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
.B "CU_get_registry()->uiNumberOfSuites."
.TP 5
.B "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).
.TP 5
.B "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
.B "CU_get_registry()->uiNumberOfTests."
.TP 5
.B "unsigned int CU_get_number_of_tests_failed(void)"
Retrieve the number of tests which contained at least 1 failed assertion.
.TP 5
.B "unsigned int CU_get_number_of_asserts(void)"
Retrieve the number of CUnit assertions made during the test run.
.TP 5
.B "unsigned int CU_get_number_of_successes(void)"
Retrieve the number of assertions which passed.
.TP 5
.B "unsigned int CU_get_number_of_failures(void)"
Retrieve the number of assertions which failed.
.TP 5
.B "const CU_pRunSummary CU_get_run_summary(void)"
Retrieve a
.B CU_RunSummary
containing all the run count information.  This data structure is
declared in 
.B <CUnit/TestRun.h>
and includes the (self-explanatory)
.I "unsigned int"
fields nSuitesRun, nSuitesFailed, nTestsRun, nTestsFailed, nAsserts,
and nAssertsFailed.
.TP 5
.B "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
.B CU_FailureRecord
in the linked list.  This data structure is declared in 
.B <CUnit/TestRun.h>
and includes the following fields:
.br
.RS 10
.B "unsigned int uiLineNumber"
.br
.B "char*        strFileName"
.br
.B "char*        strCondition"
.br
.B "CU_pTest     pTest"
.br
.B "CU_pSuite    pSuite"
.RE

.SS "Automated Interface"
The automated interface is non-interactive.  The current implementation only 
supports running all registered suites.  Results are output to an xml file to
be viewed by appropriate external tools.  Registered tests can also be listed
to
an xml file for viewing.  The following public functions are available:
.P
.B #include <CUnit/Automated.h>
.TP 5
.B "void CU_automated_run_tests(void)"
Run all tests in all registered suites.  Results are output to a file named
.I "ROOT-Results.xml."
The filename 'ROOT' is set using 
.B CU_set_output_filename(),
or else the default 'CUnitAutomated' 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.
.TP 5
.B "CU_ErrorCode CU_list_tests_to_file(void)"
Lists the registered suites and associated tests to file.  The listing file is
named
.I "ROOT-Listing.xml."
The filename 'ROOT' is set using
.B CU_set_output_filename(),
or else the default 'CUnitAutomated' 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.
.TP 5
.B "void CU_set_output_filename(const char* szFilenameRoot)"
Set the filename root to use for automated results and listing files.

.SS "Basic Interface (non-interactive)"
The basic interface is also non-interactive, with results output to stdout.
This
interface supports running individual suites or tests, and allows client code
to 
control the type of output displayed during each run.  This interface provides
the
most flexibility to clients desiring simplified access to the CUnit API.  The
following public functions are provided:
.P
.B #include <CUnit/Basic.h>
.TP 5
.B "CU_ErrorCode CU_basic_run_tests(void)"
Run all tests in all registered suites.  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
.B CU_basic_set_mode().
.TP 5
.B "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.  The type of output is controlled by the current run mode.
.TP 5
.B "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.  The type of output is controlled by the current run mode.
.TP 5
.B "void CU_basic_set_mode(CU_BasicRunMode mode)"
Set the basic run mode, which controls the output during the run.  Choices are:
.RS 10
.TP 15
CU_BRM_NORMAL
Failures and run summary are printed.
.PD 0.4v
.TP 15
CU_BRM_SILENT
No output is printed except error messages.
.TP 15
CU_BRM_VERBOSE
Maximum output of run details.
.RE
.PD 2v
.TP 5
.B "CU_BasicRunMode CU_basic_get_mode(void)"
Retrieve the current basic run mode code.
.TP 5
.B "void CU_basic_show_failures(CU_pFailureRecord pFailure)"
Prints a summary of all failures to stdout.  Does not depend on the run mode.

.SS "Interactive Console Interface"
The console interface is interactive.  All the client needs to do is initiate
the
console session, and the user controls the test run interactively.  This
include
selection & running of suites and tests, and viewing test results.
.P
.B #include <CUnit/Console.h>
.TP 5
.B "void CU_console_run_tests(void)"
Initiate an interactive test run in the console.

.SS "Interactive Curses Interface"
The curses interface is interactive.  All the client needs to do is initiate
the
curses session, and the user controls the test run interactively.  This include 
selection & running of suites and tests, and viewing test results.  Use of this
interface requires linking the ncurses library into the application.
.P
.B #include <CUnit/CUCurses.h>
.TP 5
.B "void CU_curses_run_tests(void)"
Initiate an interactive test run in curses.

.SH ERROR HANDLING
.SS CUnit Error Status Codes
Many CUnit functions set a framework error code when an exception occurs.
The error codes are an
.I enum
named 
.B CU_ErrorCode
declared in header file
.B <CUnit/CUError.h>
(included automatically by
.B <CUnit/CUnit.h>
).  The following functions are provided for retrieving the framework
error status:
.P
.B #include <CUnit/CUError.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "CU_ErrorCode CU_get_error(void)"
Returns the framework error status code.
.TP 5
.B "const char* CU_get_error_msg(void)"
Returns a message for the current error code.

.SS Error Actions
By default, CUnit continues running tests when a framework error occurs.
This 'error action' can be changed by the user if desired.  The following
functions are provided:
.P
.B #include <CUnit/CUError.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "void CU_set_error_action(CU_ErrorAction action)"
Set the framework error action.
.TP 5
.B "CU_ErrorAction CU_get_error_action(void)"
Retrieve the current error action.
.P
The error actions are defined in
.B "enum CU_ErrorAction"
in header file
.B <CUnit/CUError.h>
(included automatically by
.B <CUnit/CUnit.h>
) as follows:
.RS 5
.TP 15
CUEA_IGNORE
Continue test runs on framework errors (default).
.PD 0.4v
.TP 15
CUEA_FAIL
Stop test runs on a framework error.
.TP 15
CUEA_ABORT
Exit the application on a framework error.
.PD 2v
.RE

.SH AUTHORS
Anil Kumar     <[e-mail]>
.br
Jerry St.Clair <[e-mail]>

.SH WEBSITE
http://cunit.sourceforge.net