---
name: "CUnit"
section: "3"
platform: "linux"
package: "cunit"
version: "2.1.3-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/CUnit"
---

# CUnit(3)

A unit testing framework for C

## NAME

CUnit - A unit testing framework for C

## SYNOPSIS

- **#include \<CUnit/CUnit.h\>**

  ASSERT definitions, test management.

- **#include \<CUnit/Automated.h\>**

  Automated interface with xml output.

- **#include \<CUnit/Basic.h\>**

  Basic interface with console output.

- **#include \<CUnit/Console.h\>**

  Interactive console interface.

- **#include \<CUnit/CUCurses.h\>**

  Interactive curses interface.

## 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.

## 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.

The basic hierarchichal organization of CUnit is depicted here:

                  Test Registry\
                         \|\
            \-----------------------------\
            \|                           \|\
         Suite '1'      . . . .      Suite 'N'\
            \|                           \|\
      \---------------             ---------------\
      \|             \|             \|             \|\
   Test '11' ... Test '1M'     Test 'N1' ... Test 'NM'\

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.

The typical usage of CUnit is:

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 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 **USE\_DEPRECATED\_CUNIT\_NAMES** defined.

## WRITING TEST FUNCTIONS

A "test" is a C function having the signature: **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.

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.

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. **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.

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.

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.

The assertions defined by CUnit are:

**#include \<CUnit/CUnit.h\>**

**CU\_ASSERT(int expression)**\
 **CU\_ASSERT\_FATAL(int expression)**\
 **CU\_TEST(int expression)**\
 **CU\_TEST\_FATAL(int expression)**

Assert that expression is CU\_TRUE (non-zero).

**CU\_ASSERT\_TRUE(value)**\
 **CU\_ASSERT\_TRUE\_FATAL(value)**

Assert that value is CU\_TRUE (non-zero).

**CU\_ASSERT\_FALSE(value)**\
 **CU\_ASSERT\_FALSE\_FATAL(value)**

Assert that value is CU\_FALSE (zero).

**CU\_ASSERT\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_EQUAL\_FATAL(actual, expected)**

Assert that actual == expected.

**CU\_ASSERT\_NOT\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_NOT\_EQUAL\_FATAL(actual, expected)**

Assert that actual != expected.

**CU\_ASSERT\_PTR\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_PTR\_EQUAL\_FATAL(actual, expected)**

Assert that pointers actual == expected.

**CU\_ASSERT\_PTR\_NOT\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_PTR\_NOT\_EQUAL\_FATAL(actual, expected)**

Assert that pointers actual != expected.

**CU\_ASSERT\_PTR\_NULL(value)**\
 **CU\_ASSERT\_PTR\_NULL\_FATAL(value)**

Assert that pointer value == NULL.

**CU\_ASSERT\_PTR\_NOT\_NULL(value)**\
 **CU\_ASSERT\_PTR\_NOT\_NULL\_FATAL(value)**

Assert that pointer value != NULL.

**CU\_ASSERT\_STRING\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_STRING\_EQUAL\_FATAL(actual, expected)**

Assert that strings actual and expected are equivalent.

**CU\_ASSERT\_STRING\_NOT\_EQUAL(actual, expected)**\
 **CU\_ASSERT\_STRING\_NOT\_EQUAL\_FATAL(actual, expected)**

Assert that strings actual and expected differ.

**CU\_ASSERT\_NSTRING\_EQUAL(actual, expected, count)**\
 **CU\_ASSERT\_NSTRING\_EQUAL\_FATAL(actual, expected, count)**

Assert that 1st count chars of actual and expected are the same.

**CU\_ASSERT\_NSTRING\_NOT\_EQUAL(actual, expected, count)**\
 **CU\_ASSERT\_NSTRING\_NOT\_EQUAL\_FATAL(actual, expected, count)**

Assert that 1st count chars of actual and expected differ.

**CU\_ASSERT\_DOUBLE\_EQUAL(actual, expected, granularity)**\
 **CU\_ASSERT\_DOUBLE\_EQUAL\_FATAL(actual, expected, granularity)**

Assert that \|actual - expected\| \<= \|granularity\|.\
 Math library must be linked in for this assertion.

**CU\_ASSERT\_DOUBLE\_NOT\_EQUAL(actual, expected, granularity)**\
 **CU\_ASSERT\_DOUBLE\_NOT\_EQUAL\_FATAL(actual, expected, granularity)**

Assert that \|actual - expected\| \> \|granularity\|.\
 Math library must be linked in for this assertion.

**CU\_PASS(message)**

Register a success without performing a logical test.

**CU\_FAIL(message)**\
 **CU\_FAIL\_FATAL(message)**

Register a failure without performing a logical test.

## 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.

The main functions needed by clients are:

**#include \<CUnit/TestDB.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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:

  - CUE\_SUCCESS

    if initialization is successful.

  - CUE\_NOMEMORY

    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 CUnit 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.

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:

- **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 **CU\_cleanup\_registry()** or **CU\_initialize\_registry()** .

- **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.

## 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.

### 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 may be used to reference the suite.  Therefore, it is recommended (but not required) that each registered suite have a  unique name.  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.

**#include \<CUnit/TestDB.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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:

  - CUE\_SUCCESS

    The suite was successfully created and registered.

  - CUE\_NOREGISTRY

    Error: Test Registry is not initialized.

  - CUE\_NO\_SUITENAME

    Error: Suite name is not specified or NULL.

  - CUE\_DUP\_SUITE

    Warning: The registry already has a suite with this name.

  - CUE\_NOMEMORY

    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\_add\_suite().**

### Adding Tests to Suites

Tests are created and added to suites.  Each test has a name which may be  used to reference the test later.  Therefore, it is recommended (but not required) that the name 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.

**#include \<CUnit/TestDB.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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:

  - CUE\_SUCCESS

    The test was successfully created and added.

  - CUE\_NOREGISTRY

    Error: Test Registry is not initialized.

  - CUE\_NOSUITE

    Error: Specified suite is NULL or invalid.

  - CUE\_NO\_TESTNAME

    Error: Test name is not specified or NULL.

  - CUE\_NOTEST

    Error: Test function is not specified or NULL.

  - CUE\_DUP\_TEST

    Warning: The suite already has a test with this name.

  - CUE\_NOMEMORY

    Error: Memory allocation failed.

### Activation of Suites and Tests

A suite or test must be active to be executed during a test run (all suites and tests are active by default upon creation).  The active  state of a suite or test is available as pSuite-\>fActive and pTest-\>fActive,  respectively.  The flag will be CU\_TRUE when the entity is active, CU\_FALSE otherwise.  Use the following functions to selectively deactivate suites and  tests to choose subsets of tests to run dynamically.  Note that it is a  framework error to deactivate a test or suite and then specifically request  that it be run.

**#include \<CUnit/TestDB.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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.

### Modifying Other Attributes of Suites and Tests

Normally the attributes of suites and tests are set at creation time.  In some cases, a client may wish to manipulate these to modify the test structure   dynamically.  The following functions are provided for this purpose, and should be used instead of directly setting the value of the data structure members.  All return CUE\_SUCCESS on success, and the indicated error code on failure.

**CU\_ErrorCode CU\_set\_suite\_name(CU\_pSuite pSuite, const char \*strNewName)**

- **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.

### Lookup of Individual Suites and Tests

In most cases, clients will have references to registered suites and tests as  pointers returned from  **CU\_add\_suite()** and  **CU\_add\_test().** Occassionally, a client may need to be able to retrieve a reference to a suite or test.   The following functions are provided to assist clients with this when the client has  some information about the entity (name or order of registration).  In cases where  nothing is known about the suite or test, the client will need to iterate the internal  data structures to enumerate the suites and tests.  This is not directly supported in  the client API.

**CU\_pSuite CU\_get\_suite(const char\* strName)** **CU\_pSuite CU\_get\_suite\_at\_pos(unsigned int pos)** **unsigned int CU\_get\_suite\_pos(CU\_pSuite pSuite)** **unsigned int CU\_get\_suite\_pos\_by\_name(const char\* strName)** \</P\> These functions facilitate lookup of suites registered in the active test registry.   The first 2 functions allow lookup of the suite by name or position and return NULL  if the suite cannot be found.  The position is a 1-based index in the range  \[1 ..  **CU\_get\_registry()** -\>uiNumberOfSuites\].  This may be helpful when suites having duplicate names are  registered, in which case lookup by name can only retrieve the 1st suite having that  name.  The second 2 functions help the client identify the position of a registered suite.   These return 0 if the suite cannot be found.  In addition, all these functions set the  CUnit error state to CUE\_NOREGISTRY\> if the registry is not initialized.  As appropriate,  CUE\_NO\_SUITENAME is set if strName is NULL, and CUE\_NOSUITE is set if pSuite is NULL.

**CU\_pTest CU\_get\_test(CU\_pSuite pSuite, const char \*strName)** **CU\_pTest CU\_get\_test\_at\_pos\<(CU\_pSuite pSuite, unsigned int pos)** **unsigned int CU\_get\_test\_pos\<(CU\_pSuite pSuite, CU\_pTest pTest)** **unsigned int CU\_get\_test\_pos\_by\_name(CU\_pSuite pSuite, const char \*strName)** These functions facilitate lookup of tests registered in suites.  The first  2 functions allow lookup of the test by name or position and return NULL if the  test cannot found.  The position is a 1-based index in the range  \[1 .. pSuite-\>uiNumberOfSuites\].  This may be helpful when tests having duplicate names  are registered, in which case lookup by name can only retrieve the 1st test having that  name.  The second 2 functions help the client identify the position of a test in a suite.   These return 0 if the test cannot be found.  In addition, all these functions set the  CUnit error state to CUE\_NOREGISTRY if the registry is not initialized, and to CUE\_NOSUITE  if pSuite is NULL.  As appropriate, CUE\_NO\_TESTNAME is set if strName is NULL, and  CUE\_NOTEST is set if pTest is NULL.

## 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 previous results are cleared each time a test run is initiated  (even if it fails).

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 **\<CUnit/testRun.h\>.**

### 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:

**#include \<CUnit/TestRun.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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 CUnit 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  **\<CUnit/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  **\<CUnit/TestRun.h\>** and includes the following fields:\

  **unsigned int uiLineNumber**\
   **char\*        strFileName**\
   **char\*        strCondition**\
   **CU\_pTest     pTest**\
   **CU\_pSuite    pSuite**

### 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:

**#include \<CUnit/Automated.h\>**

- **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 '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.

- **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 '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.

- **void CU\_set\_output\_filename(const char\* szFilenameRoot)**

  Set the filename root to use for automated results and listing files.

### 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:

**#include \<CUnit/Basic.h\>**

- **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:

  - CU\_BRM\_NORMAL

    Failures and run summary are printed.

  - CU\_BRM\_SILENT

    No output is printed except error messages.

  - CU\_BRM\_VERBOSE

    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.

### 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.

**#include \<CUnit/Console.h\>**

- **void CU\_console\_run\_tests(void)**

  Initiate an interactive test run in the console.

### 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.

**#include \<CUnit/CUCurses.h\>**

- **void CU\_curses\_run\_tests(void)**

  Initiate an interactive test run in curses.

## ERROR HANDLING

### CUnit Error Status Codes

Many CUnit functions set a framework error code when an exception occurs. The error codes are an *enum* named  **CU\_ErrorCode** declared in header file **\<CUnit/CUError.h\>** (included automatically by **\<CUnit/CUnit.h\>** ).  The following functions are provided for retrieving the framework error status:

**#include \<CUnit/CUError.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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.

### Error Actions

By default, CUnit continues running tests when a framework error occurs. In this context, failed assertions are not considered "framework errors".   All other error conditions including suite initialization or cleanup failures,  inactive suites or tests which are run explicitly, etc. are included. This 'error action' can be changed by the user if desired.  The following functions are provided:

**#include \<CUnit/CUError.h\>** (included automatically by \<CUnit/CUnit.h\>)

- **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.

The error actions are defined in **enum CU\_ErrorAction** in header file **\<CUnit/CUError.h\>** (included automatically by **\<CUnit/CUnit.h\>** ) as follows:

- CUEA\_IGNORE

  Continue test runs on framework errors (default).

- CUEA\_FAIL

  Stop test runs on a framework error.

- CUEA\_ABORT

  Exit the application on a framework error.

## AUTHORS

Anil Kumar     \<anilsaharan@users.sourceforge.net\>\
 Jerry St.Clair \<jds2@users.sourceforge.net\>

## WEBSITE

http://cunit.sourceforge.net
