1CUnit(3)                   CUnit Programmer's Manual                  CUnit(3)
2
3
4

NAME

6       CUnit - A unit testing framework for C
7
8

SYNOPSIS

10       #include <CUnit/CUnit.h>      ASSERT definitions, test management.
11       #include <CUnit/Automated.h>  Automated interface with xml output.
12       #include <CUnit/Basic.h>      Basic interface with console output.
13       #include <CUnit/Console.h>    Interactive console interface.
14       #include <CUnit/CUCurses.h>   Interactive curses interface.
15
16
17

DESCRIPTION

19       CUnit is a system for writing, administering, and running unit tests in
20       C.  It uses a simple framework for building test structures,  and  pro‐
21       vides a rich set of assertions for testing common data types.  CUnit is
22       built as a static library which is linked with the user's testing code.
23
24
25

STRUCTURE & GENERAL USAGE

27       CUnit is a combination of a platform-independent framework with various
28       user interfaces. The core framework provides basic support for managing
29       a test registry, suites, and test cases. The user interfaces facilitate
30       interaction with the framework to run tests and view results.
31
32
33       The basic hierarchichal organization of CUnit is depicted here:
34
35
36                         Test Registry
37                               |
38                  -----------------------------
39                  |                           |
40               Suite '1'      . . . .      Suite 'N'
41                  |                           |
42            ---------------             ---------------
43            |             |             |             |
44         Test '11' ... Test '1M'     Test 'N1' ... Test 'NM'
45
46
47       Individual  test  cases  are packaged into suites, which are registered
48       with the active test registry.  Suites  can  have  setup  and  teardown
49       functions  which  are automatically called before and after running the
50       suite's tests. All suites/tests in the registry may be run using a sin‐
51       gle function call, or selected suites or tests can be run.
52
53
54       The typical usage of CUnit is:
55
56
57       1. Write functions for tests (and suite init/cleanup if necessary).
58       2. Initialize the test registry using CU_initialize_registry()
59       3. Add test suites to the registry using CU_add_suite()
60       4. Add test cases to the suites using CU_add_test()
61       5. Run tests using the desired interface, e.g.
62          CU_console_run_tests() to use the interactive console.
63       6. Cleanup the test registry using CU_cleanup_registry()
64
65
66       All public names in CUnit are prefixed with 'CU_'.  This helps minimize
67       clashes with names in user code.  Note that earlier versions CUnit used
68       different  names  without  this prefix.  The older API names are depre‐
69       cated but still supported.  To use the older names, user code must  now
70       be compiled with USE_DEPRECATED_CUNIT_NAMES defined.
71
72
73

WRITING TEST FUNCTIONS

75       A  "test"  is  a C function having the signature: void test_func(void).
76       There are no restrictions on the content of  a  test  function,  except
77       that  it  should  not  modify  the  CUnit framework (e.g. add suites or
78       tests, modify the test registry, or initiate a test run).  A test func‐
79       tion  may  call  other  functions (which also may not modify the frame‐
80       work).  Registering a test will cause it's function to be run when  the
81       test is run.
82
83
84       CUnit provides a set of assertions for testing logical conditions.  The
85       success or failure of these assertions is tracked by the framework, and
86       can be viewed when a test run is complete.  Each assertion tests a sin‐
87       gle  logical  condition,  and  fails  if  the  condition  evaluates  to
88       CU_FALSE.  Upon failure, the test continues unless the user chooses the
89       'xxx_FATAL' version of an assertion.  In that case, the  test  function
90       returns immediately.
91
92       CUnit provides a set of assertions for testing logical conditions.  The
93       success or failure of these assertions is tracked by the framework, and
94       can be viewed when a test run is complete.
95
96
97       Each  assertion tests a single logical condition, and fails if the con‐
98       dition evaluates to CU_FALSE.  Upon failure, the test function  contin‐
99       ues  unless  the  user chooses the 'xxx_FATAL' version of an assertion.
100       In that case, the test function is  aborted  and  returns  immediately.
101       FATAL  versions of assertions should be used with caution!  There is no
102       opportunity for the test function to clean up after itself once a FATAL
103       assertion  fails.   The  normal suite cleanup function is not affected,
104       however.
105
106
107       There are also special "assertions" for registering a pass or fail with
108       the  framework without performing a logical test.  These are useful for
109       testing flow of control or other conditions  not  requiring  a  logical
110       test.
111
112
113       Other  functions called by a registered test function may use the CUnit
114       assertions freely.  These assertions will be counted  for  the  calling
115       function.   They  may  also  use FATAL versions of assertions - failure
116       will abort the original test function and its entire call chain.
117
118
119       The assertions defined by CUnit are:
120
121
122       #include <CUnit/CUnit.h>
123
124
125
126       CU_ASSERT(int expression)
127       CU_ASSERT_FATAL(int expression)
128       CU_TEST(int expression)
129       CU_TEST_FATAL(int expression)
130            Assert that expression is CU_TRUE (non-zero).
131
132
133       CU_ASSERT_TRUE(value)
134       CU_ASSERT_TRUE_FATAL(value)
135            Assert that value is CU_TRUE (non-zero).
136
137
138
139       CU_ASSERT_FALSE(value)
140       CU_ASSERT_FALSE_FATAL(value)
141            Assert that value is CU_FALSE (zero).
142
143
144
145       CU_ASSERT_EQUAL(actual, expected)
146       CU_ASSERT_EQUAL_FATAL(actual, expected)
147            Assert that actual == expected.
148
149
150
151       CU_ASSERT_NOT_EQUAL(actual, expected)
152       CU_ASSERT_NOT_EQUAL_FATAL(actual, expected)
153            Assert that actual != expected.
154
155
156
157       CU_ASSERT_PTR_EQUAL(actual, expected)
158       CU_ASSERT_PTR_EQUAL_FATAL(actual, expected)
159            Assert that pointers actual == expected.
160
161
162
163       CU_ASSERT_PTR_NOT_EQUAL(actual, expected)
164       CU_ASSERT_PTR_NOT_EQUAL_FATAL(actual, expected)
165            Assert that pointers actual != expected.
166
167
168
169       CU_ASSERT_PTR_NULL(value)
170       CU_ASSERT_PTR_NULL_FATAL(value)
171            Assert that pointer value == NULL.
172
173
174
175       CU_ASSERT_PTR_NOT_NULL(value)
176       CU_ASSERT_PTR_NOT_NULL_FATAL(value)
177            Assert that pointer value != NULL.
178
179
180
181       CU_ASSERT_STRING_EQUAL(actual, expected)
182       CU_ASSERT_STRING_EQUAL_FATAL(actual, expected)
183            Assert that strings actual and expected are equivalent.
184
185
186
187       CU_ASSERT_STRING_NOT_EQUAL(actual, expected)
188       CU_ASSERT_STRING_NOT_EQUAL_FATAL(actual, expected)
189            Assert that strings actual and expected differ.
190
191
192
193       CU_ASSERT_NSTRING_EQUAL(actual, expected, count)
194       CU_ASSERT_NSTRING_EQUAL_FATAL(actual, expected, count)
195            Assert that 1st count chars of actual and expected are the same.
196
197
198
199       CU_ASSERT_NSTRING_NOT_EQUAL(actual, expected, count)
200       CU_ASSERT_NSTRING_NOT_EQUAL_FATAL(actual, expected, count)
201            Assert that 1st count chars of actual and expected differ.
202
203
204
205       CU_ASSERT_DOUBLE_EQUAL(actual, expected, granularity)
206       CU_ASSERT_DOUBLE_EQUAL_FATAL(actual, expected, granularity)
207            Assert that |actual - expected| <= |granularity|.
208            Math library must be linked in for this assertion.
209
210
211
212       CU_ASSERT_DOUBLE_NOT_EQUAL(actual, expected, granularity)
213       CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL(actual, expected, granularity)
214            Assert that |actual - expected| > |granularity|.
215            Math library must be linked in for this assertion.
216
217
218
219       CU_PASS(message)
220            Register a success without performing a logical test.
221
222
223
224       CU_FAIL(message)
225       CU_FAIL_FATAL(message)
226            Register a failure without performing a logical test.
227
228
229

THE TEST REGISTRY

231       The test registry is the repository for suites  and  associated  tests.
232       The  user normally only needs to initialize the registry before use and
233       clean up afterwards.  However, other functions are provided to  manipu‐
234       late the registry when necessary.
235
236
237       The main functions needed by clients are:
238
239
240       #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
241
242
243       CU_ErrorCode CU_initialize_registry(void)
244            Initializes  the framework.  This function should be called before
245            any other CUnit functions.  Failure to do so will likely result in
246            a crash.  An error status code is returned:
247
248
249            CUE_SUCCESS    if initialization is successful.
250
251
252            CUE_NOMEMORY   if memory allocation failed.
253
254
255
256       CU_BOOL CU_registry_initialized(void)
257            Checks  whether  the  framework has been initialized.  This may be
258            useful if the registry setup is distributed  over  multiple  files
259            that  need  to  make sure the registry is ready for test registra‐
260            tion.
261
262
263
264       void CU_cleanup_registry(void)
265            Cleans up and releases memory used by  the  framework.   No  CUnit
266            functions  (other than CU_initialize_registry() ) should be called
267            after this function.  Failure to call  CU_cleanup_registry()  will
268            result in memory leaks.  Note also that this function will destroy
269            all suites (and associated tests) in the registry.
270
271
272       Other registry functions are primarily for internal  and  testing  pur‐
273       poses.   However,  general  users  may  find use for them and should be
274       aware of them.  These include:
275
276
277       CU_pTestRegistry CU_get_registry(void)
278            Retrieve a pointer to the active test registry.  The registry is a
279            variable    of    data    type    CU_Testregistry   (declared   in
280            <CUnit/TestDB.h>).  Note that the returned pointer will be invali‐
281            dated  by  a  call  to CU_cleanup_registry() or CU_initialize_reg‐
282            istry()
283
284
285
286       CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)
287            Replace the active registry with the specified one.  A pointer  to
288            the  previous  registry is returned.  It is the caller's responsi‐
289            bility to destroy the old  registry.   This  can  be  accomplished
290            using  CU_destroy_existing_registry()  on  the  returned  pointer.
291            Alternatively, the old registry can be set as the active  one.   A
292            subsequent  call  to  CU_cleanup_registry()  will  then destroy it
293            automatically.  Care should be taken not to explicitly  destroy  a
294            registry  that is set as the active one.  This will result in mul‐
295            tiple frees of the same memory and a likely crash.
296
297
298       CU_pTestRegistry CU_create_new_registry(void)
299            Create a new registry and return a pointer to it.   The  new  reg‐
300            istry  will  not  contain any suites or tests.  It is the caller's
301            responsibility to destroy the new registry by one  of  the  mecha‐
302            nisms described previously.
303
304
305       void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
306            Destroy  the  specified  test  registry,  including any registered
307            suites.  This function should not be called for a  registry  which
308            is  set as the active test registry.  This will result in a multi‐
309            ple free of the same memory when CU_cleanup_registry() is  called.
310            ppRegistry  may  not be NULL, but the pointer it points to may be.
311            Note that *ppRegistry will be NULL on return.
312
313
314

MANAGING TESTS AND SUITES

316       In order for a test to be run by CUnit, it must be added to a test col‐
317       lection (suite) which is registered with the test registry.
318
319
320   Adding Suites to the Registry
321       The  first step in setting up a test system is creating and registering
322       one or more test collections (suites).  Each suite has a name which may
323       be  used to reference the suite.  Therefore, it is recommended (but not
324       required) that each registered suite have a unique name.   The  current
325       implementation  does  not support the creation of suites independent of
326       the test registry.  Suites are simultaneously created and added to  the
327       active registry as follows.
328
329
330       #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
331
332
333       CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit,
334            CU_CleanupFunc  pClean)"  This  creates  and registers a new suite
335            having the specified name, initialization  function,  and  cleanup
336            function.   A  pointer  to  the  new  suite is returned for use in
337            adding tests to the suite.  This pointer will be NULL if  a  fatal
338            error  occurs.   In addition, the framework error status is set as
339            follows:
340
341
342            CUE_SUCCESS       The suite was successfully  created  and  regis‐
343                              tered.
344
345
346            CUE_NOREGISTRY    Error: Test Registry is not initialized.
347
348
349            CUE_NO_SUITENAME  Error: Suite name is not specified or NULL.
350
351
352            CUE_DUP_SUITE     Warning:  The  registry already has a suite with
353                              this name.
354
355
356            CUE_NOMEMORY      Error: Memory allocation failed.
357
358
359            The initialization and cleanup functions are optional.  Both are C
360            functions  having  the signature int func_name(void).  These func‐
361            tions can perform setup and teardown operations needed to  support
362            the  suite's  tests.  They are called before and after the suite's
363            tests are run, even if only 1 of the suite's tests is  run.   They
364            take  no  arguments,  and should return NULL if they complete suc‐
365            cessfully  (non-NULL  otherwise).   If  either  function  is   not
366            required for a particular suite, pass NULL to CU_add_suite().
367
368
369
370   Adding Tests to Suites
371       Tests  are created and added to suites.  Each test has a name which may
372       be used to reference the test later.  Therefore, it is recommended (but
373       not required) that the name be unique among all tests added to a single
374       suite.  The current implementation does not  support  the  creation  of
375       tests  independent of registered suites.  Tests are simultaneously cre‐
376       ated and added to a suite as follows.
377
378
379       #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
380
381
382       CU_pTest  CU_add_test(CU_pSuite pSuite, const char*  strName,  CU_Test‐
383       Func
384            pTestFunc)"  This creates a new test having the specified name and
385            test function, and adds it to  the  indicated  suite.   The  suite
386            should  have  been  previously  created  using  CU_add_suite().  A
387            pointer to the new test is returned, which will be NULL if a fatal
388            error occurred.  In addition, the framework error status is set as
389            follows:
390
391
392            CUE_SUCCESS       The test was successfully created and added.
393
394
395            CUE_NOREGISTRY    Error: Test Registry is not initialized.
396
397
398            CUE_NOSUITE       Error: Specified suite is NULL or invalid.
399
400
401            CUE_NO_TESTNAME   Error: Test name is not specified or NULL.
402
403
404            CUE_NOTEST        Error: Test function is not specified or NULL.
405
406            CUE_DUP_TEST      Warning: The suite already has a test with  this
407                              name.
408
409
410            CUE_NOMEMORY      Error: Memory allocation failed.
411
412
413
414   Activation of Suites and Tests
415       A  suite  or  test must be active to be executed during a test run (all
416       suites and tests are active by  default  upon  creation).   The  active
417       state   of  a  suite  or  test  is  available  as  pSuite->fActive  and
418       pTest->fActive, respectively.  The flag will be CU_TRUE when the entity
419       is  active,  CU_FALSE otherwise.  Use the following functions to selec‐
420       tively deactivate suites and tests to choose subsets of  tests  to  run
421       dynamically.  Note that it is a framework error to deactivate a test or
422       suite and then specifically request that it be run.
423
424
425       #include <CUnit/TestDB.h> (included automatically by <CUnit/CUnit.h>)
426
427
428       CU_ErrorCode CU_set_suite_active(CU_pSuite pSuite, CU_BOOL fNewActive)
429
430
431       CU_ErrorCode CU_set_test_active(CU_pTest pTest, CU_BOOL fNewActive)
432            Pass CU_TRUE to these functions to activate a suite/test, CU_FALSE
433            to   deactivate   it.   These  functions  return  CUE_NOSUITE  and
434            CUE_NOTEST, respectively, if the specified suite or test is NULL.
435
436
437
438   Modifying Other Attributes of Suites and Tests
439       Normally the attributes of suites and tests are set at  creation  time.
440       In some cases, a client may wish to manipulate these to modify the test
441       structure dynamically.  The following functions are provided  for  this
442       purpose,  and  should  be used instead of directly setting the value of
443       the data structure members.  All return CUE_SUCCESS on success, and the
444       indicated error code on failure.
445
446
447       CU_ErrorCode  CU_set_suite_name(CU_pSuite  pSuite,  const char *strNew‐
448       Name)
449
450
451       CU_ErrorCode CU_set_test_name(CU_pTest pTest, const char *strNewName)
452            These functions change the name of registered  suites  and  tests.
453            The  current names are available as the pSuite->pName</I> and data
454            structure members.  If the suite or test is NULL, then CUE_NOSUITE
455            or  CUE_NOTEST  is returned, respectively.  If strNewName is NULL,
456            then CUE_NO_SUITENAME  or  CUE_NO_TESTNAME  is  returned,  respec‐
457            tively.
458
459
460       CU_ErrorCode  CU_set_suite_initfunc(CU_pSuite pSuite, CU_InitializeFunc
461       pNewInit)
462
463
464       CU_ErrorCode CU_set_suite_cleanupfunc(CU_pSuite pSuite,  CU_CleanupFunc
465       pNewClean)
466            These  functions  change  the initialization and cleanup functions
467            for a registered suite.  The current functions  are  available  as
468            the  pSuite->pInitializeFunc  and pSuite->pCleanupFunc data struc‐
469            ture members.  If the suite is NULL then CUE_NOSUITE is returned.
470
471
472       CU_ErrorCode CU_set_test_func(CU_pTest pTest, CU_TestFunc pNewFunc)
473            This function changes the test function  for  a  registered  test.
474            The current test function is available as the pTest->pTestFunc</I>
475            data structure member.  If either pTest or pNewFunc is NULL,  then
476            CUE_NOTEST is returned.
477
478
479
480   Lookup of Individual Suites and Tests
481       In  most  cases,  clients will have references to registered suites and
482       tests as  pointers  returned  from  CU_add_suite()  and  CU_add_test().
483       Occassionally,  a client may need to be able to retrieve a reference to
484       a suite or test.   The  following  functions  are  provided  to  assist
485       clients with this when the client has some information about the entity
486       (name or order of registration).  In cases where nothing is known about
487       the  suite  or  test, the client will need to iterate the internal data
488       structures to enumerate the suites and tests.   This  is  not  directly
489       supported in the client API.
490
491
492       CU_pSuite      CU_get_suite(const      char*     strName)     CU_pSuite
493       CU_get_suite_at_pos(unsigned      int      pos)      unsigned       int
494       CU_get_suite_pos(CU_pSuite         pSuite)         unsigned         int
495       CU_get_suite_pos_by_name(const  char*  strName)  </P>  These  functions
496       facilitate  lookup  of  suites  registered in the active test registry.
497       The first 2 functions allow lookup of the suite by name or position and
498       return  NULL  if  the suite cannot be found.  The position is a 1-based
499       index in the range [1 ..  CU_get_registry() ->uiNumberOfSuites].   This
500       may  be  helpful  when suites having duplicate names are registered, in
501       which case lookup by name can only retrieve the 1st suite  having  that
502       name.   The second 2 functions help the client identify the position of
503       a registered suite.  These return 0 if the suite cannot be  found.   In
504       addition,  all  these functions set the CUnit error state to CUE_NOREG‐
505       ISTRY>  if  the  registry  is   not   initialized.    As   appropriate,
506       CUE_NO_SUITENAME  is  set if strName is NULL, and CUE_NOSUITE is set if
507       pSuite is NULL.
508
509
510       CU_pTest CU_get_test(CU_pSuite pSuite, const  char  *strName)  CU_pTest
511       CU_get_test_at_pos<(CU_pSuite  pSuite,  unsigned  int pos) unsigned int
512       CU_get_test_pos<(CU_pSuite  pSuite,  CU_pTest   pTest)   unsigned   int
513       CU_get_test_pos_by_name(CU_pSuite  pSuite,  const  char *strName) These
514       functions facilitate lookup of tests registered in suites.  The first 2
515       functions  allow lookup of the test by name or position and return NULL
516       if the test cannot found.  The position is a 1-based index in the range
517       [1 .. pSuite->uiNumberOfSuites].  This may be helpful when tests having
518       duplicate names are registered, in which case lookup by name  can  only
519       retrieve  the  1st  test having that name.  The second 2 functions help
520       the client identify the position of a test in a suite.  These return  0
521       if  the test cannot be found.  In addition, all these functions set the
522       CUnit error state to CUE_NOREGISTRY if the registry is not initialized,
523       and  to CUE_NOSUITE if pSuite is NULL.  As appropriate, CUE_NO_TESTNAME
524       is set if strName is NULL, and CUE_NOTEST is set if pTest is NULL.
525
526
527

RUNNING TESTS

529       CUnit supports running all tests in all registered suites, but individ‐
530       ual  tests  or  suites can also be run.  During each run, the framework
531       keeps track of the number of suites, tests, and assertions run, passed,
532       and  failed.   Note  that  the previous results are cleared each time a
533       test run is initiated (even if it fails).
534
535
536       While CUnit provides primitive functions for running suites and  tests,
537       most  users  will want to use one of the user interfaces.  These inter‐
538       faces handle the details of interaction with the framework and  provide
539       output  of  test  details and results for the user.  For more about the
540       primitive functions, see <CUnit/testRun.h>.
541
542
543
544   Test Results
545       The interfaces present results of test runs, but client code may  some‐
546       times need to access the results directly.  These results include vari‐
547       ous run counts, as well as a linked list of failure records holding the
548       failure  details.   Test results must be retrieved before attempting to
549       run other tests, which resets the result  information.   Functions  for
550       accessing the test results are:
551
552
553       #include <CUnit/TestRun.h> (included automatically by <CUnit/CUnit.h>)
554
555
556       unsigned int CU_get_number_of_suites_run(void)'
557            Retrieve  the  number  of suites run.  Suite having initialization
558            functions which fail are not run.  To get the total number of reg‐
559            istered suites, use CU_get_registry()->uiNumberOfSuites.
560
561
562       unsigned int CU_get_number_of_suites_failed(void)
563            Retrieve  the number of suites which had initialization or cleanup
564            functions which failed (returned non-NULL).
565
566
567       unsigned int CU_get_number_of_tests_run(void)
568            Retrieve the number of tests run.  Tests in suites having initial‐
569            ization functions which fail are not run.  To get the total number
570            of registered tests , use CU_get_registry()->uiNumberOfTests.
571
572
573       unsigned int CU_get_number_of_tests_failed(void)
574            Retrieve the number of tests which contained  at  least  1  failed
575            assertion.
576
577
578       unsigned int CU_get_number_of_asserts(void)
579            Retrieve the number of CUnit assertions made during the test run.
580
581
582       unsigned int CU_get_number_of_successes(void)
583            Retrieve the number of assertions which passed.
584
585
586       unsigned int CU_get_number_of_failures(void)
587            Retrieve the number of assertions which failed.
588
589
590       const CU_pRunSummary CU_get_run_summary(void)
591            Retrieve a CU_RunSummary containing all the run count information.
592            This data structure is declared in <CUnit/TestRun.h> and  includes
593            the  (self-explanatory)  unsigned  int fields nSuitesRun, nSuites‐
594            Failed, nTestsRun, nTestsFailed, nAsserts, and nAssertsFailed.
595
596
597       const CU_pFailureRecord CU_get_failure_list(void)
598            Retrieve the head of the linked list of failure  records  for  the
599            last  run.   Each assertion failure or suite init/cleanup function
600            failure is registered in a  new  CU_FailureRecord  in  the  linked
601            list.   This  data  structure is declared in <CUnit/TestRun.h> and
602            includes the following fields:
603                 unsigned int uiLineNumber
604                 char*        strFileName
605                 char*        strCondition
606                 CU_pTest     pTest
607                 CU_pSuite    pSuite
608
609
610
611   Automated Interface
612       The automated interface is non-interactive.  The current implementation
613       only  supports running all registered suites.  Results are output to an
614       xml file to be viewed by appropriate external tools.  Registered  tests
615       can  also  be  listed to an xml file for viewing.  The following public
616       functions are available:
617
618       #include <CUnit/Automated.h>
619
620
621       void CU_automated_run_tests(void)
622            Run all tests in all registered (and active) suites.  Results  are
623            output  to  a file named ROOT-Results.xml.  The filename 'ROOT' is
624            set using CU_set_output_filename(), or else the default  'CUnitAu‐
625            tomated'  is used.  This means that the same filename is used each
626            run (and the results  file  overwritten)  if  the  user  does  not
627            explicitly set the 'ROOT' for each run.
628
629
630       CU_ErrorCode CU_list_tests_to_file(void)
631            Lists  the  registered  suites  and associated tests to file.  The
632            listing file is named ROOT-Listing.xml.  The  filename  'ROOT'  is
633            set  using CU_set_output_filename(), or else the default 'CUnitAu‐
634            tomated' is used.  This means that the same filename is used  each
635            run  (and  the  listing  file  overwritten)  if  the user does not
636            explicitly set the 'ROOT' for each run.
637
638
639       void CU_set_output_filename(const char* szFilenameRoot)
640            Set the filename root to use for  automated  results  and  listing
641            files.
642
643
644
645   Basic Interface (non-interactive)
646       The  basic  interface  is  also non-interactive, with results output to
647       stdout.  This interface supports running individual  suites  or  tests,
648       and  allows  client code to control the type of output displayed during
649       each run.  This interface provides  the  most  flexibility  to  clients
650       desiring  simplified  access  to  the  CUnit API.  The following public
651       functions are provided:
652
653
654       #include <CUnit/Basic.h>
655
656
657       CU_ErrorCode CU_basic_run_tests(void)
658            Run all tests in all registered suites.  Only  the  active  suites
659            are  run, and it is not considered an error if inactive suites are
660            encountered and skipped.  Returns the  1st  error  code  occurring
661            during the test run.  The type of output is controlled by the cur‐
662            rent run mode, which can be set using CU_basic_set_mode().
663
664
665       CU_ErrorCode CU_basic_run_suite(CU_pSuite pSuite)
666            Run all tests in single specified suite.  Returns  the  1st  error
667            code  occurring  during the test run.  CU_basic_run_suite() itself
668            generates CUE_NOSUITE if pSuite is NULL, and CUE_SUITE_INACTIVE if
669            the  requested  suite  is  not active.  The type of output is con‐
670            trolled by the current run mode.
671
672
673       CU_ErrorCode CU_basic_run_test(CU_pSuite pSuite, CU_pTest pTest)
674            Run a single test in a specified suite.   Returns  the  1st  error
675            code  occurring  during  the test run.  BU_basic_run_test() itself
676            generates CUE_NOSUITE of pSuite is NULL; CUE_NOTEST  if  pTest  is
677            NULL;  CUE_SUITE_INACTIVE  if  pSuite is not active for execution,
678            CUE_TEST_NOT_IN_SUITE if pTest  is  not  a  registered  member  of
679            pSuite,  and  CUE_TEST_INACTIVE  if pTest is not active for execu‐
680            tion. The type of output is controlled by the current run mode.
681
682
683       void CU_basic_set_mode(CU_BasicRunMode mode)
684            Set the basic run mode, which controls the output during the  run.
685            Choices are:
686
687
688                 CU_BRM_NORMAL  Failures and run summary are printed.
689                 CU_BRM_SILENT  No output is printed except error messages.
690                 CU_BRM_VERBOSE Maximum output of run details.
691
692       CU_BasicRunMode CU_basic_get_mode(void)
693            Retrieve the current basic run mode code.
694
695
696       void CU_basic_show_failures(CU_pFailureRecord pFailure)
697            Prints  a  summary  of all failures to stdout.  Does not depend on
698            the run mode.
699
700
701
702   Interactive Console Interface
703       The console interface is interactive.  All the client needs  to  do  is
704       initiate the console session, and the user controls the test run inter‐
705       actively.  This include selection & running of suites  and  tests,  and
706       viewing test results.
707
708
709       #include <CUnit/Console.h>
710
711
712       void CU_console_run_tests(void)
713            Initiate an interactive test run in the console.
714
715
716
717   Interactive Curses Interface
718       The  curses  interface  is  interactive.  All the client needs to do is
719       initiate the curses session, and the user controls the test run  inter‐
720       actively.   This  include  selection & running of suites and tests, and
721       viewing test results.  Use  of  this  interface  requires  linking  the
722       ncurses library into the application.
723
724
725       #include <CUnit/CUCurses.h>
726
727
728       void CU_curses_run_tests(void)
729            Initiate an interactive test run in curses.
730
731
732

ERROR HANDLING

734   CUnit Error Status Codes
735       Many  CUnit  functions  set  a  framework  error code when an exception
736       occurs.  The error codes are an enum  named  CU_ErrorCode  declared  in
737       header    file    <CUnit/CUError.h>    (included    automatically    by
738       <CUnit/CUnit.h> ).  The following functions are provided for retrieving
739       the framework error status:
740
741
742       #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
743
744
745       CU_ErrorCode CU_get_error(void)
746            Returns the framework error status code.
747
748
749       const char* CU_get_error_msg(void)
750            Returns a message for the current error code.
751
752
753
754   Error Actions
755       By  default,  CUnit  continues  running  tests  when  a framework error
756       occurs.  In this context, failed assertions are not considered  "frame‐
757       work  errors".   All other error conditions including suite initializa‐
758       tion or cleanup failures,  inactive  suites  or  tests  which  are  run
759       explicitly,  etc.  are included.  This 'error action' can be changed by
760       the user if desired.  The following functions are provided:
761
762
763       #include <CUnit/CUError.h> (included automatically by <CUnit/CUnit.h>)
764
765
766       void CU_set_error_action(CU_ErrorAction action)
767            Set the framework error action.
768
769
770       CU_ErrorAction CU_get_error_action(void)
771            Retrieve the current error action.
772
773
774       The error actions are defined in enum  CU_ErrorAction  in  header  file
775       <CUnit/CUError.h>  (included automatically by <CUnit/CUnit.h> ) as fol‐
776       lows:
777
778
779            CUEA_IGNORE    Continue test runs on framework errors (default).
780            CUEA_FAIL      Stop test runs on a framework error.
781            CUEA_ABORT     Exit the application on a framework error.
782
783
784

AUTHORS

786       Anil Kumar     <anilsaharan@users.sourceforge.net>
787       Jerry St.Clair <jds2@users.sourceforge.net>
788
789
790

WEBSITE

792       http://cunit.sourceforge.net
793
794
795
796
797CUnit-2.0-1                       August 2004                         CUnit(3)
Impressum