Welcome to c2unit, Chul-woong's CUnit

* Introduction

This is yet another C unit testing framework.
Why bother? To meet exact my need:
(1) I'm trying to convert a legacy software into managable one.
    If I'm in starting fresh projects, I'd rather pick up 'check' or
    other existing unit testing platform.
    However, LEGACY SOFTWARE is the one I'm facing.
(2) I need a view on how much portion of software is tested:
    "200 funcs of 300 are tested"
    "1200 asserts of 1200 asserts are passed"
(3) I want to a embed total testsuite into executables.
    In other words, I want my software to be able to self-test,
    and it should be simple.
    If your executable is a.out then:
      $ a.out -t              # run all tests
      $ a.out -t -p 2         # run tests T, where pri(T) <= 2
      $ a.out -t -P "session" # run all tests with path prefix "session"

Hope this helps me and you. 
   
* How to Run

$ make

After make, you get following components:
(1) c2unit.h -- main headerfile
(2) libc2unit.a
(3) firstlink.o

Then you should build your binary with following sequences:
$(LINKER) firstlink.o $(YOUR_OBJS) $(OTHER_LIBS) lilbc2unit.a

Then try run the executable with tests!

* Quick-Start

 (1) Situation

 Say your target function foo() resides in foo.c like:

 #include <foo.h>
 
 int foo(int a, int b) {
         return a + b;    
 }

 Then,


 (2) Instrument Original Source

 #include <foo.h>

 #define C2UNIT_TEST_PATH   // optional.
 #include "c2unit.h"        // should be in include-path

 FUNC_BEGIN(foo, NORMAL)    // FUNC_BEGIN(func_name, func_level)
 int foo(int a, int b) {
         return a + b;    
 }
 FUNC_END(foo)

 ...

 #include "foo_test.c"      // recommend to put at the end of foo.c

 Instrument original source file like the above.

 C2UNIT_TEST_PATH provides a way to group tests.
 When there is over thousands of tests and you may want to
 test only your working tests for a while. Then define
 C2UNIT_TEST_PATH to unique identifier and use the identifier
 in running test cases to designate test group.

 It is not mandatory to keep test code as a file included to 
 the original source file. It's just my test-code grouping style.
 I looked the content of source directory and be glad when 
 each of source code file has accompanying _test.c file.

 (3) Code tests

 foo_test.c:

 #include "c2unit.h"                       // if needed

 TEST(foo, 1, "this is a test for foo()")  // name, no, desc
 {
         ok(foo(1,2) == 3);         /* or c2_assert(foo(1,2) == 3); */
         ok(foo(2,5) == 7);         /* or  c2_assert(foo(2,5) == 7); */
 }
 TEST_END(foo, 1)                          // name, no

 TEST(foo, 2, "another test for foo()")
 {
         ok(foo(0,0) == 0);
 }
 TEST_END(foo, 2)

 // name, no, desc, pri
 TEST_FUNC(foo, 3, "priority 2 test for foo(), it takes a long time")
 {
         sleep(1000);
         ok(foo(-1, 1) == 0);
 }
 TEST_END(foo, 3)

 A test function is a pair between TEST (or TEST_FUNC) and TEST_END.
 TEST, TEST_FUNC, and TEST_END macros need arguments: 
  - name: name of function to test
  - no  : serial number of the test. 
  - desc: description of the test. It is showed in test-run results.
  - pri : test priority. This is another mechansim for designating
          a group of tests to run.
 Note that (name, no) pair should be unique in a source file.


 (4) Do code to call test-runner from main()

 test_run(argc, argv) function is provided to as entry point.
 So, if you want to run test codes, call it.
 As test_run() parses additional command line option, it would be
 convinient to pass argc and argv from main() to test_run().
 (refer example.c)

 Following options are supported:
   -P <test_path_prefix>   test path prefix
   -p <test_priority>      test priority (1~3)
   -d                      dump test and function information and exit
   -c                      dump core when assert fails
   -v                      be verbose

 (5) Test, code, and repeat!

                               20 April 2010
                             - Chul-Woong Yang (cwyang at gmail.com)