aMule/unittests

UnitTests provide an easy way to perform automated testing (including)
regression-testing and are desbribed in depth at
http://c2.com/cgi/wiki?UnitTest

The UnitTest framework MuleUnit is a minimalistic UnitTesting-framework
based on the EasyUnit framework, with the goal of making testing of the
aMule codebase easier.


How to use:
 This section describes the step-by-step of creating a new testcase.

 It is recommended that each test-case (a collection of tests) is
 placed in a separate .cpp file, in general, one test-case per class.

 In the following examples, I will test a non-existing stack template
 class which has the member-functions push (back) and pop (front).


 1) Creating the test skeleton:
    Test-cases exist in two flavors: With a fixture and without.
    A fixture is a way to ease the preparation before and after
    each test and consists of (optionally) a setUp function which
    is run before each unittest, a tearDown function which is run
    after each unittest and any number of member-variables and
    helper-functions.


    A simple testcase (in this case for the Stack class) is declared
    like this, though the name "StackTest" may be anything.

      #include <muleunit/test.h>

      DECLARE_SIMPLE(StackTest);


    If we wanted to have a default stack-object created before each test
    and deleted afterwards, we could use a fixture, which is done like so:

      #include <muleunit/test.h>

      DECLARE(StackTest);
        Stack<int>* m_stack;

        //! Called before each test.
        void setUp() {
            m_stack = new Stack<int>();
        }

        //! Called after each test
        void tearDown() {
            delete m_stack;
        }
      END_DECLARE();


    Both DECLARE statements creates a base-class from which the unittests
    are derived, and the section between DECLARE(..) and END_DECLARE() are
    used verbatim in the definition of said baseclass.


 2) Writing Tests
    To add an actual test to the test-case, the following is done:

      TEST(StackTest, AStackTest)
      {
        <test here>
      }


    This will create and register a unittest to the StackTest
    test-case which has the name "AStackTest". An simple example
    of this can be seen here:

      TEST(StackTest, PushAndPop)
      {
        m_stack->push(10);

        ASSERT_EQUALS(10, m_stack->pop());
      }


    A test-case can have any number of unittests associated with it,
    but each test in a test-case must be uniquely named.


  3) Building the test
    Assuming that the testcase described above has been placed in
    tests/StackTest.cpp, the follow entry needs to be added to the
    Makefile.am file in tests/:

      StackTest_SOURCES = StackTest.cpp
      StackTest_CXXFLAGS = $(CXXFLAGS)
      StackTest_LDADD = $(LDADD)

    And the TESTS variable must be updated to contain an entry for
    the stack testcase: "StackTest"

    At the moment, in order for the makefile to be updated with the
    next test-case you need to execute the following from the
    amule-dev/ dir:

      $ automake unittests/tests/Makefile
      $ ./configure <your options>

    This only need to be done when the Makefile.am file has been
    changed, not when test test-cases themselves are changed.


  4) Running the test
    Simply executing the make target check will execute all unittests
    registered in the Makefile ("-s" is used for silent operation):

      $ make -s check

      Making check in tests
      Test case "StackTest" SUCCEEDED with 0 failure(s) and 1 success(es):
        Test "AStackTest" SUCCEEDED!

      PASS: StackTest

      ==================
      All 1 tests passed
      ==================


	Should a test fail, the output will be like the following:

      $ make -s check

      Making check in tests
      Test case "StackTest" FAILED with 1 failure(s) and 0 success(es):
        Test "Foo" FAILED :
          Failure: "Test failed." line 11 in StackTest.cpp


      FAIL: StackTest
      ================================
      1 of 1 tests failed
      Please report to admin@amule.org
      ================================

  5) More
    More information about available test-macros can be found in the
    muleunit/test.h header-file.