.TH CUnit 3 "August 2004" "CUnit-2.0-1" "CUnit Programmer's Manual"

.SH NAME
CUnit - A unit testing framework for C

.SH SYNOPSIS
.PD 0.4v
.TP 30
.B #include <CUnit/CUnit.h>
ASSERT definitions, test management.
.TP 30
.B #include <CUnit/Automated.h>
Automated interface with xml output.
.TP 30
.B #include <CUnit/Basic.h>
Basic interface with console output.       
.TP 30
.B #include <CUnit/Console.h>
Interactive console interface.
.TP 30
.B #include <CUnit/CUCurses.h>
Interactive curses interface.
.PD 2v

.SH DESCRIPTION
CUnit is a system for writing, administering, and running unit tests in C.
It uses a simple framework for building test structures, and provides a
rich set of assertions for testing common data types.  CUnit is built as
a static library which is linked with the user's testing code.

.SH "STRUCTURE & GENERAL USAGE"
CUnit is a combination of a platform-independent framework with various
user interfaces. The core framework provides basic support for managing
a test registry, suites, and test cases. The user interfaces facilitate
interaction with the framework to run tests and view results.
.P
The basic hierarchichal organization of CUnit is depicted here:
.P
.br
                  Test Registry
                        |
           -----------------------------
           |                           |
        Suite '1'      . . . .      Suite 'N'
           |                           |
     ---------------             ---------------
     |             |             |             |
  Test '11' ... Test '1M'     Test 'N1' ... Test 'NM'
.br
.P
Individual test cases are packaged into suites, which are registered
with the active test registry.  Suites can have setup and teardown
functions which are automatically called before and after running the
suite's tests. All suites/tests in the registry may be run using a
single function call, or selected suites or tests can be run.
.P
The typical usage of CUnit is:
.HP 3
.PD 0.2v
1. Write functions for tests (and suite init/cleanup if necessary).
.HP 3
2. Initialize the test registry using
.B CU_initialize_registry()
.HP 3
3. Add test suites to the registry using
.B CU_add_suite()
.HP 3
4. Add test cases to the suites using
.B CU_add_test()
.TP 3
5. Run tests using the desired interface, e.g.
.B CU_console_run_tests()
to use the interactive console.
.HP 3
6. Cleanup the test registry using
.B CU_cleanup_registry()
.PD 2v
.P
All public names in CUnit are prefixed with 'CU_'.  This helps
minimize clashes with names in user code.  Note that earlier versions
CUnit 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
.B USE_DEPRECATED_CUNIT_NAMES
defined.

.SH "WRITING TEST FUNCTIONS"
A "test" is a C function having the signature:
.B "void test_func(void)."
There are no restrictions on the content of a test function, except
that it should not modify the CUnit framework (e.g. add suites or tests,
modify the test registry, or initiate a test run).  A test function may
call other functions (which also may not modify the framework).
Registering a test will cause it's function to be run when the
test is run.
.P
CUnit provides a set of assertions for testing logical conditions.  The
success or failure of these assertions is tracked by the framework,
and can be viewed when a test run is complete.  Each assertion tests a
single logical condition, and fails if the condition evaluates to CU_FALSE.
Upon failure, the test continues unless the user chooses the 'xxx_FATAL'
version of an assertion.  In that case, the test function returns
immediately.

CUnit provides a set of assertions for testing logical conditions.  The
success or failure of these assertions is tracked by the framework,
and can be viewed when a test run is complete.
.P
Each assertion tests a single logical condition, and fails if the
condition evaluates to CU_FALSE.  Upon failure, the test function 
continues unless the user chooses the 'xxx_FATAL' version of an 
assertion.  In that case, the test function is aborted and returns 
immediately.
.B "FATAL versions of assertions should be used with caution!"
There is no opportunity for the test function to clean up after 
itself once a FATAL assertion fails.  The normal suite cleanup 
function is not affected, however.
.P
There are also special "assertions" for registering a pass or fail with
the framework without performing a logical test.  These are useful for 
testing flow of control or other conditions not requiring a logical test.
.P
Other functions called by a registered test function may use the CUnit
assertions freely.  These assertions will be counted for the calling
function.  They may also use FATAL versions of assertions - failure
will abort the original test function and its entire call chain.
.P
The assertions defined by CUnit are:
.P
.B #include <CUnit/CUnit.h>

.P
.B CU_ASSERT(int expression)
.br
.B CU_ASSERT_FATAL(int expression)
.br
.B CU_TEST(int expression)
.br
.B CU_TEST_FATAL(int expression)
.RS 5
Assert that expression is CU_TRUE (non-zero).
.RE

.P
.B CU_ASSERT_TRUE(value)
.br
.B CU_ASSERT_TRUE_FATAL(value)
.RS 5
Assert that value is CU_TRUE (non-zero).
.RE

.P
.B CU_ASSERT_FALSE(value)
.br
.B CU_ASSERT_FALSE_FATAL(value)
.RS 5
Assert that value is CU_FALSE (zero).
.RE

.P
.B CU_ASSERT_EQUAL(actual, expected)
.br
.B CU_ASSERT_EQUAL_FATAL(actual, expected)
.RS 5
Assert that actual == expected.
.RE

.P
.B CU_ASSERT_NOT_EQUAL(actual, expected)
.br
.B CU_ASSERT_NOT_EQUAL_FATAL(actual, expected)
.RS 5
Assert that actual != expected.
.RE

.P
.B CU_ASSERT_PTR_EQUAL(actual, expected)
.br
.B CU_ASSERT_PTR_EQUAL_FATAL(actual, expected)
.RS 5
Assert that pointers actual == expected.
.RE

.P
.B CU_ASSERT_PTR_NOT_EQUAL(actual, expected)
.br
.B CU_ASSERT_PTR_NOT_EQUAL_FATAL(actual, expected)
.RS 5
Assert that pointers actual != expected.
.RE

.P
.B CU_ASSERT_PTR_NULL(value)
.br
.B CU_ASSERT_PTR_NULL_FATAL(value)
.RS 5
Assert that pointer value == NULL.
.RE

.P
.B CU_ASSERT_PTR_NOT_NULL(value)
.br
.B CU_ASSERT_PTR_NOT_NULL_FATAL(value)
.RS 5
Assert that pointer value != NULL.
.RE

.P
.B CU_ASSERT_STRING_EQUAL(actual, expected)
.br
.B CU_ASSERT_STRING_EQUAL_FATAL(actual, expected)
.RS 5
Assert that strings actual and expected are equivalent.
.RE

.P
.B CU_ASSERT_STRING_NOT_EQUAL(actual, expected)
.br
.B CU_ASSERT_STRING_NOT_EQUAL_FATAL(actual, expected)
.RS 5
Assert that strings actual and expected differ.
.RE

.P
.B CU_ASSERT_NSTRING_EQUAL(actual, expected, count)
.br
.B CU_ASSERT_NSTRING_EQUAL_FATAL(actual, expected, count)
.RS 5
Assert that 1st count chars of actual and expected are the same.
.RE

.P
.B CU_ASSERT_NSTRING_NOT_EQUAL(actual, expected, count)
.br
.B CU_ASSERT_NSTRING_NOT_EQUAL_FATAL(actual, expected, count)
.RS 5
Assert that 1st count chars of actual and expected differ.
.RE

.P
.B CU_ASSERT_DOUBLE_EQUAL(actual, expected, granularity)
.br
.B CU_ASSERT_DOUBLE_EQUAL_FATAL(actual, expected, granularity)
.RS 5
Assert that |actual - expected| <= |granularity|.
.br
Math library must be linked in for this assertion.
.RE

.P
.B CU_ASSERT_DOUBLE_NOT_EQUAL(actual, expected, granularity)
.br
.B CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL(actual, expected, granularity)
.RS 5
Assert that |actual - expected| > |granularity|.
.br
Math library must be linked in for this assertion.
.RE

.P
.B CU_PASS(message)
.RS 5
Register a success without performing a logical test.
.RE

.P
.B CU_FAIL(message)
.br
.B CU_FAIL_FATAL(message)
.RS 5
Register a failure without performing a logical test.
.RE

.SH "THE TEST REGISTRY"
The test registry is the repository for suites and associated tests.
The user normally only needs to initialize the registry before use and
clean up afterwards.  However, other functions are provided to
manipulate the registry when necessary.
.P
The main functions needed by clients are:
.P
.B #include <CUnit/TestDB.h>
(included automatically by <CUnit/CUnit.h>)
.TP 5
.B "CU_ErrorCode CU_initialize_registry(void)"
Initializes the framework.  This function should be called before any
other CUnit functions.  Failure to do so will likely result in a crash.
An error status code is returned:
.RS 5
.TP 15
CUE_SUCCESS
if initialization is successful.
.TP 15
CUE_NOMEMORY
if memory allocation failed.
.RE

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

.TP 5
.B "void CU_cleanup_registry(void)"
Cleans up and releases memory used by the framework.  No CUnit functions
(other than
.B CU_initialize_registry()
) should be called after this function.  Failure to call
.B CU_cleanup_registry()
will result in memory leaks.  Note also that this function will destroy
all suites (and associated tests) in the registry.
.P
Other registry functions are primarily for internal and testing purposes.
However, general users may find use for them and should be aware of them.
These include:
.TP 5
.B "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 <CUnit/TestDB.h>).
Note that the returned pointer will be invalidated by a call to
.B CU_cleanup_registry()
or
.B CU_initialize_registry()
\.

.TP 5
.B "CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)"
Replace the active registry with the specified one.  A pointer to the
previous registry is returned.
.B "It is the caller's responsibility to destroy the old registry."
This can be accomplished using
.B CU_destroy_existing_registry()
on the returned pointer.  Alternatively, the old registry can be
set as the active one.  A subsequent call to
.B 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.
.TP 5
.B "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.