unittests/README

   1 UnitTests provide an easy way to perform automated testing (including)
   2 regression-testing and are desbribed in depth at
   3 http://c2.com/cgi/wiki?UnitTest
   4
   5 The UnitTest framework MuleUnit is a minimalistic UnitTesting-framework
   6 based on the EasyUnit framework, with the goal of making testing of the
   7 aMule codebase easier.
   8
   9
  10 How to use:
  11  This section describes the step-by-step of creating a new testcase.
  12
  13  It is recommended that each test-case (a collection of tests) is
  14  placed in a seperate .cpp file, in general, one test-case per class.
  15
  16  In the following examples, I will test a non-existing stack template
  17  class which has the member-functions push (back) and pop (front).
  18
  19
  20  1) Creating the test skeleton:
  21     Test-cases exist in two flavors: With a fixture and without.
  22     A fixture is a way to ease the preparation before and after
  23     each test and consists of (optionally) a setUp function which
  24     is run before each unittest, a tearDown function wich is run
  25     after each unittest and any number of member-variables and
  26     helper-functions.
  27
  28
  29     A simple testcase (in this case for the Stack class) is declared
  30     like this, though the name "StackTest" may be anything.
  31
  32       #include <muleunit/test.h>
  33
  34       DECLARE_SIMPLE(StackTest);
  35
  36
  37     If we wanted to have a default stack-object created before each test
  38     and deleted afterwards, we could use a fixture, which is done like so:
  39
  40       #include <muleunit/test.h>
  41
  42       DECLARE(StackTest);
  43         Stack<int>* m_stack;
  44
  45         //! Called before each test.
  46         void setUp() {
  47             m_stack = new Stack<int>();
  48         }
  49
  50         //! Called after each test
  51         void tearDown() {
  52             delete m_stack;
  53         }
  54       END_DECLARE();
  55
  56
  57     Both DECLARE statements creates a base-class from which the unittests
  58     are derived, and the section between DECLARE(..) and END_DECLARE() are
  59     used verbatim in the definition of said baseclass.
  60
  61
  62  2) Writing Tests
  63     To add an actual test to the test-case, the following is done:
  64
  65       TEST(StackTest, AStackTest)
  66       {
  67         <test here>
  68       }
  69
  70
  71     This will create and register a unittest to the StackTest
  72     test-case which has the name "AStackTest". An simple example
  73     of this can be seen here:
  74
  75       TEST(StackTest, PushAndPop)
  76       {
  77         m_stack->push(10);
  78
  79         ASSERT_EQUALS(10, m_stack->pop());
  80       }
  81
  82
  83     A test-case can have any number of unittests assosiated with it,
  84     but each test in a test-case must be uniquely named.
  85
  86
  87   3) Building the test
  88     Assuming that the testcase described above has been placed in
  89     tests/StackTest.cpp, the follow entry needs to be added to the
  90     Makefile.am file in tests/:
  91
  92       StackTest_SOURCES = StackTest.cpp
  93       StackTest_CXXFLAGS = $(CXXFLAGS)
  94       StackTest_LDADD = $(LDADD)
  95
  96     And the TESTS variable must be updated to contain an entry for
  97     the stack testcase: "StackTest"
  98
  99     At the moment, in order for the makefile to be updated with the
 100     next test-case you need to execute the following from the
 101     amule-dev/ dir:
 102
 103       $ automake unittests/tests/Makefile
 104       $ ./configure <your options>
 105
 106     This only need to be done when the Makefile.am file has been
 107     changed, not when test test-cases themselves are changed.
 108
 109
 110   4) Running the test
 111     Simply executing the make target check will execute all unittests
 112     registered in the Makefile ("-s" is used for silent operation):
 113
 114       $ make -s check
 115
 116       Making check in tests
 117       Test case "StackTest" SUCCEEDED with 0 failure(s) and 1 success(es):
 118         Test "AStackTest" SUCCEEDED!
 119
 120       PASS: StackTest
 121
 122       ==================
 123       All 1 tests passed
 124       ==================
 125
 126
 127         Should a test fail, the output will be like the following:
 128
 129       $ make -s check
 130
 131       Making check in tests
 132       Test case "StackTest" FAILED with 1 failure(s) and 0 success(es):
 133         Test "Foo" FAILED :
 134           Failure: "Test failed." line 11 in StackTest.cpp
 135
 136
 137       FAIL: StackTest
 138       ================================
 139       1 of 1 tests failed
 140       Please report to admin@amule.org
 141       ================================
 142
 143   5) More
 144     More information about available test-macros can be found in the
 145     muleunit/test.h header-file.
 146