| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file unit-tests.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Oct 28, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page unittest "Unit test"
|
|---|
| 17 | *
|
|---|
| 18 | * Unit tests are done via the CppUnit framework (http://cppunit.sourceforge.net/doc/1.8.0/).
|
|---|
| 19 | *
|
|---|
| 20 | * \section unittest-structure Directory structure
|
|---|
| 21 | *
|
|---|
| 22 | * Unit tests are always located in a subfolder \b unittests of the component
|
|---|
| 23 | * that they test, e.g. if checking one of the Parsers, then its unit test
|
|---|
| 24 | * resides in \b src/Parser/unittests.
|
|---|
| 25 | *
|
|---|
| 26 | * \section unittest-launch-all Launching all tests
|
|---|
| 27 | *
|
|---|
| 28 | * All unit tests can be launched as follows:
|
|---|
| 29 | * -# Enter the build directory
|
|---|
| 30 | * -# Enter \b src/unittests
|
|---|
| 31 | * -# Run
|
|---|
| 32 | * \code make check
|
|---|
| 33 | * \endcode
|
|---|
| 34 | *
|
|---|
| 35 | * This will run all present unit tests one after the other.
|
|---|
| 36 | *
|
|---|
| 37 | * \section unittest-launch-some Launching some tests
|
|---|
| 38 | *
|
|---|
| 39 | * If only some of the tests should be checked, then they have to be launched by
|
|---|
| 40 | * hand via entering the same directory as in the section before and e.g.
|
|---|
| 41 | * \code
|
|---|
| 42 | * ./AnalysisBondsUnitTest
|
|---|
| 43 | * \endcode
|
|---|
| 44 | * Note that to allow for debugging of the unit tests, one has to prepend the
|
|---|
| 45 | * executable as follows:
|
|---|
| 46 | * \code
|
|---|
| 47 | * libtool --mode=execute gdb --args ./AnalysisBondsUnitTest
|
|---|
| 48 | * \endcode
|
|---|
| 49 | * As we use libtool to take care of shared libraries the executables in
|
|---|
| 50 | * \b src/unittests are just scripts. The true executables hide in another
|
|---|
| 51 | * subfolder \b .libs. The scripts set environment variables such that shared
|
|---|
| 52 | * libraries, which have not been installed so far, are found.
|
|---|
| 53 | *
|
|---|
| 54 | * \section unittest-results Inspecting results
|
|---|
| 55 | *
|
|---|
| 56 | * Results of the test are shown during run. An \a Ok(2) indicates that
|
|---|
| 57 | * two tests for the single launched testsuite passed.
|
|---|
| 58 | *
|
|---|
| 59 | * \section unittest-add Adding new tests
|
|---|
| 60 | *
|
|---|
| 61 | * \attention Name convention of files, (no spaces, use CamelCase) e.g.
|
|---|
| 62 | * \b AnalysisBondsUnitTest
|
|---|
| 63 | * - the unit test module should be called as follows:
|
|---|
| 64 | * -# either the name of the component or the module
|
|---|
| 65 | * -# followed by UnitTest.
|
|---|
| 66 | * - the test class should be called as follows:
|
|---|
| 67 | * -# the name of the class it tests
|
|---|
| 68 | * -# followed by Test.
|
|---|
| 69 | *
|
|---|
| 70 | * Adding a new test is as easy as this:
|
|---|
| 71 | * -# Create a new module for declaration and definition of the unit test
|
|---|
| 72 | * in a suitable \b unittests subfolder (see above on policy and naming).
|
|---|
| 73 | * Check out one of the present unit tests and rename, but beware of
|
|---|
| 74 | * copy&paste errors!
|
|---|
| 75 | * -# Add the test to the \b Makefile.am contained in \b unittests.
|
|---|
| 76 | *
|
|---|
| 77 | * Writing a new unit test then consists of writing the source and the header
|
|---|
| 78 | * file, where you should guide yourself by the already present files. Naming
|
|---|
| 79 | * convention is usually to suffix the name with UnitTest, e.g.
|
|---|
| 80 | * \b SingletonUnitTest.cpp.
|
|---|
| 81 | *
|
|---|
| 82 | * The test class should be named in a similar manner and has the following
|
|---|
| 83 | * look:
|
|---|
| 84 | * \code
|
|---|
| 85 | * class SingletonTest : public CppUnit::TestFixture
|
|---|
| 86 | * {
|
|---|
| 87 | * CPPUNIT_TEST_SUITE( SingletonTest );
|
|---|
| 88 | * CPPUNIT_TEST ( blaTest );
|
|---|
| 89 | * CPPUNIT_TEST ( blablaTest );
|
|---|
| 90 | * CPPUNIT_TEST_SUITE_END();
|
|---|
| 91 | *
|
|---|
| 92 | * public:
|
|---|
| 93 | * void setUp();
|
|---|
| 94 | * void tearDown();
|
|---|
| 95 | *
|
|---|
| 96 | * void blaTest();
|
|---|
| 97 | * void blablaTest();
|
|---|
| 98 | * };
|
|---|
| 99 | * \endcode
|
|---|
| 100 | * It inherits CppUnit::TestFixture and defines it as a TEST_SUITE via the
|
|---|
| 101 | * initial macros which also give the test functions to call. Below the test
|
|---|
| 102 | * functions are defined along with setUp() and tearDown() which embrace the
|
|---|
| 103 | * call of each test function, i.e. which create a common test environment for
|
|---|
| 104 | * each test function, by allocating some memory, setting some stuff and
|
|---|
| 105 | * cleaning up in the end again.
|
|---|
| 106 | *
|
|---|
| 107 | * If there is not yet a \b unittests folder:
|
|---|
| 108 | * -# Create a new \b Makefile.am, check out one of the present ones to get
|
|---|
| 109 | * an idea, below is a small list of contained elements. Note that the
|
|---|
| 110 | * variable must begin with a unique name as all Makefile.am on unit tests
|
|---|
| 111 | * are included into one big Makefile.am in \b src/unittests.
|
|---|
| 112 | * -# Add your ...SOURCES and ...HEADERS to TESTSOURCES and TESTHEADERS.
|
|---|
| 113 | * -# Add an include directive to \b src/unittests/Makefile.am of this
|
|---|
| 114 | * newly created \b Makefile.am.
|
|---|
| 115 | *
|
|---|
| 116 | * What's contained in the \b Makefile.am:
|
|---|
| 117 | * -# ...SOURCES and ...HEADERS gathering all source and header files in this
|
|---|
| 118 | * \b unittests folder (this is needed for the test program that contains
|
|---|
| 119 | * all unit test in one executable).
|
|---|
| 120 | * -# ...TESTS gathering all test programs in this \b unittests folder.
|
|---|
| 121 | * -# ...TESTS is added to TESTS, check_PROGRAMS, noinst_PROGRAMS such that
|
|---|
| 122 | * it is known that they are just tests, programs for \a make \a check and
|
|---|
| 123 | * are not to be installed.
|
|---|
| 124 | * -# ...LIBS gathers general libs that all of the tests in this \b unittests
|
|---|
| 125 | * folder share.
|
|---|
| 126 | * -# for each unit test:
|
|---|
| 127 | * -# ...SOURCES gathers all source files that are required for the test.
|
|---|
| 128 | * -# ...LDADD gathers all libs that are required for compilation.
|
|---|
| 129 | *
|
|---|
| 130 | * \section unittest-failures Marking tests as expected to fail
|
|---|
| 131 | *
|
|---|
| 132 | * If a unit tests fails for a given commit but this is expected because the
|
|---|
| 133 | * failure is repaired after some other implementation lateron, it is useful
|
|---|
| 134 | * and required to mark the test as expected to fail.
|
|---|
| 135 | *
|
|---|
| 136 | * To do this, add a variable \b XFAIL_TESTS if not present to the Makefile.am
|
|---|
| 137 | * in which the failing unit test is contained as follows
|
|---|
| 138 | * \code
|
|---|
| 139 | * XFAIL_TESTS = SingletonUnitTest
|
|---|
| 140 | * \endcode
|
|---|
| 141 | * This will mark \b SingletonUnitTest as expected to fail and continue testing
|
|---|
| 142 | * even though the test is not passed.
|
|---|
| 143 | *
|
|---|
| 144 | *
|
|---|
| 145 | * \date 2012-04-12
|
|---|
| 146 | *
|
|---|
| 147 | */
|
|---|
