Unit tests for C
================

About
-----

The `sigscheme/test-c/` directory is existing for unit testing for C. The tests
are currently using privately-customized version of
http://www.cozmixng.org/~rwiki/?cmd=view;name=Cutter%3A%3AREADME.en[Cutter]
testing framework. Although it is a quick-hacked product, sufficiently works
for SigScheme.

The private patch can be used and redistributed under the original license of
Cutter.

How to use
----------

  1. Check out Cutter revision 20

    svn co -r20 http://www.cozmixng.org/repos/c/cutter/trunk cutter

  2. Apply http://websvn.freedesktop.org/uim/branches/r5rs/sigscheme/test-c/cutter-r20-yamaken-extension.diff?view=markup[the private patch] for SigScheme

  3. Install pached version of Cutter

  4. Build and run tests

    $ make all test

How to write new test
---------------------

  1. Copy the template

    $ cp test_template.c test_foo.c

    The filename must be test_*.c

  2. Add following lines into Makefile.am and re-configure

    TEST_SRCS               += test_foo.c
    noinst_LTLIBRARIES      += libtest_foo.la
    libtest_foo_la_SOURCES  = test_foo.c cutter-sscm.h
    libtest_foo_la_LIBADD   = $(top_builddir)/src/libsscm.la

  3. Write your own tests into test_foo.c likewise test_template.c

    UT_DEF2("my test")
    {
        UT_ASSERT_EQUAL_XINT(0, ~0);
    }
    
    UT_REGISTER_BEGIN("my testsuite")
    UT_REGISTER_END

    See cutter/assersions.h to find appropriate assertion macros.

  4. Configure testsuite

    $ make update-suites

    This makes test_foo.c as follows:

    UT_DEF2(test_1, "my test")
    {
        UT_ASSERT_EQUAL_XINT(0, ~0);
    }
    
    UT_REGISTER_BEGIN("my testsuite")
    UT_REGISTER(test_1, "my test")
    UT_REGISTER_END

    There is no need to remove the auto-generated fragments on re-update.

  5. Build and run tests

    $ make all test

Requirements for testing framework
----------------------------------

I had tried to use the famous http://cunit.sf.net/[CUnit] at first to test
SigScheme, but it did not met my requirements and needs long way to modify to
fit to SigScheme. So I searched for other testing frameworks and decided to
modify
http://www.cozmixng.org/~rwiki/?cmd=view;name=Cutter%3A%3AREADME.en[Cutter].
Please let me know better solutions if you know.

  - Written in pure C

    * To avoid C++-specific interferences especially stacks, frames
      and exceptions with GC

    * To allow running tests on platforms that has poor or no C++ support

  - Don't terminate a test even if an assertion is failed

  - Prints the expected and actual values when an assertion failed, as follows

----------------------------------------------------------------
./test_format.c:64: - format ~D - 
expected: \<0>
 but was: \<2147483647>
----------------------------------------------------------------

  - Standalone test runner

    i.e. There is no need to write the main function for each test.

  - Automatic testsuite configuration

    i.e. There is no need to register all tests into a testsuite by hand.

  - It can be inserted SCM_GC_PROTECTED_CALL() on each tests


And some recommendations:

  - Small and Simple

  - Assertions macro names are short

  - Assertions have assert(expected, actual) form instead of
    assert(actual, expected)
