source: src/documentation/tests/unit-tests.dox@ 72e40d0

/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file unit-tests.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/**
 * \page unittest "Unit test"
 *
 * Unit tests are done via the CppUnit framework (http://cppunit.sourceforge.net/doc/1.8.0/).
 *
 * \section unittest-structure Directory structure
 *
 *  Unit tests are always located in a subfolder \b unittests of the component
 *  that they test, e.g. if checking one of the Parsers, then its unit test
 *  resides in \b src/Parser/unittests.
 *
 * \section unittest-launch-all Launching all tests
 *
 *  All unit tests can be launched as follows:
 *  -# Enter the build directory
 *  -# Enter \b src/unittests
 *  -# Run
 *  \code make check
 *  \endcode
 *
 * This will run all present unit tests one after the other.
 *
 * \section unittest-launch-some Launching some tests
 *
 *  If only some of the tests should be checked, then they have to be launched by
 *  hand via entering the same directory as in the section before and e.g.
 *  \code
 *  ./AnalysisBondsUnitTest
 *  \endcode
 *  Note that to allow for debugging of the unit tests, one has to prepend the
 *  executable as follows:
 *  \code
 *  libtool --mode=execute gdb --args ./AnalysisBondsUnitTest
 *  \endcode
 *  As we use libtool to take care of shared libraries the executables in
 *  \b src/unittests are just scripts. The true executables hide in another
 *  subfolder \b .libs. The scripts set environment variables such that shared
 *  libraries, which have not been installed so far, are found.
 *
 * \section unittest-results Inspecting results
 *
 *  Results of the test are shown during run. An \a Ok(2) indicates that
 *  two tests for the single launched testsuite passed.
 *
 * \section unittest-add Adding new tests
 *
 *  \attention Name convention of files, (no spaces, use CamelCase) e.g.
 *  \b AnalysisBondsUnitTest
 *  - the unit test module should be called as follows:
 *    -# either the name of the component or the module
 *    -# followed by UnitTest.
 *  - the test class should be called as follows:
 *    -# the name of the class it tests
 *    -# followed by Test.
 *
 *  Adding a new test is as easy as this:
 *  -# Create a new module for declaration and definition of the unit test
 *    in a suitable \b unittests subfolder (see above on policy and naming).
 *    Check out one of the present unit tests and rename, but beware of
 *    copy&paste errors!
 *  -# Add the test to the \b Makefile.am contained in \b unittests.
 *
 * Writing a new unit test then consists of writing the source and the header
 * file, where you should guide yourself by the already present files. Naming
 * convention is usually to suffix the name with UnitTest, e.g.
 * \b SingletonUnitTest.cpp.
 *
 * The test class should be named in a similar manner and has the following
 * look:
 * \code
 * class SingletonTest : public CppUnit::TestFixture
 * {
 *   CPPUNIT_TEST_SUITE( SingletonTest );
 *   CPPUNIT_TEST ( blaTest );
 *   CPPUNIT_TEST ( blablaTest );
 *   CPPUNIT_TEST_SUITE_END();
 *
 * public:
 *   void setUp();
 *   void tearDown();
 *
 *   void blaTest();
 *   void blablaTest();
 * };
 * \endcode
 * It inherits CppUnit::TestFixture and defines it as a TEST_SUITE via the
 * initial macros which also give the test functions to call. Below the test
 * functions are defined along with setUp() and tearDown() which embrace the
 * call of each test function, i.e. which create a common test environment for
 * each test function, by allocating some memory, setting some stuff and
 * cleaning up in the end again.
 *
 *  If there is not yet a \b unittests folder:
 *  -# Create a new \b Makefile.am, check out one of the present ones to get
 *    an idea, below is a small list of contained elements. Note that the
 *    variable must begin with a unique name as all Makefile.am on unit tests
 *    are included into one big Makefile.am in \b src/unittests.
 *  -# Add your ...SOURCES and ...HEADERS to TESTSOURCES and TESTHEADERS.
 *  -# Add an include directive to \b src/unittests/Makefile.am of this
 *    newly created \b Makefile.am.
 *
 *  What's contained in the \b Makefile.am:
 *  -# ...SOURCES and ...HEADERS gathering all source and header files in this
 *    \b unittests folder (this is needed for the test program that contains
 *    all unit test in one executable).
 *  -# ...TESTS gathering all test programs in this \b unittests folder.
 *  -# ...TESTS is added to TESTS, check_PROGRAMS, noinst_PROGRAMS such that
 *    it is known that they are just tests, programs for \a make \a check and
 *    are not to be installed.
 *  -# ...LIBS gathers general libs that all of the tests in this \b unittests
 *    folder share.
 *  -# for each unit test:
 *    -# ...SOURCES gathers all source files that are required for the test.
 *    -# ...LDADD gathers all libs that are required for compilation.
 *
 * \section unittest-failures Marking tests as expected to fail
 *
 * If a unit tests fails for a given commit but this is expected because the
 * failure is repaired after some other implementation lateron, it is useful
 * and required to mark the test as expected to fail.
 *
 * To do this, add a variable \b XFAIL_TESTS if not present to the Makefile.am
 * in which the failing unit test is contained as follows
 * \code
 *   XFAIL_TESTS = SingletonUnitTest
 * \endcode
 * This will mark \b SingletonUnitTest as expected to fail and continue testing
 * even though the test is not passed.
 *
 *
 * \date 2012-04-12
 *
 */