/*
 * 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 code-tests.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */


/**
 * \page codetest "Code tests"
 *
 * Code tests enforce certain principles which the programmer must follow.
 *
 * At this moment these are:
 * -# Every .cpp files must include \b config.h and \b CodePatterns/MemDebug.hpp
 * -# Every .hpp files must include \b config.h
 * -# Every .dox file contains a (correctly formatted: YYYY-MM-DD) date stamp.
 *
 * These make sure that the memory debugger is catching every movement on the
 * heap and that every module knows about the behavior controling \e #define's that
 * are checked by autoconf and written to \b config.h in the build directory. And
 * also that for every documentation file it is known when it was current.
 *
 * \section codetest-structure Directory structure
 *
 * The code tests are contained in \b tests/CodeChecks. Therein are all test
 * scripts gathered that use autotest (http://www.gnu.org/s/hello/manual/autoconf/Using-Autotest.html#Using-Autotest).
 * Mostly, these look through files
 *
 * \section codetest-launch-all Launching all tests
 *
 *  In order to launch all tests, simply do:
 *  -# Enter \b tests/CodeChecks in your build directory
 *  -# Run
 *    \code make check \endcode
 *    there
 *
 * \section codetest-launch-some Launching some tests
 *
 *  Launching a single or just some of the tests is only a little bit more
 *  complicated. Proceed as follows:
 *  -# Enter \b tests/CodeChecks in your build directory
 *  -# Run
 *  \code ../../../tests/CodeChecks/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
 *  where \a <option> is explained in the subsections below and \a <buildpath> is
 *  the build path (i.e. the variable \a AUTOTEST_PATH should contain the path to
 *  the executable).
 *
 *  \subsection regressiontest-launch-by-number ... by number
 *
 *    Tests can be launched by specifying their test number, e.g. then \a <option>
 *    might be \a 1 or \a 1-2 or just nothing for all of them.
 *
 *  \subsection regressiontest-launch-by-keyword .. by keyword
 *
 *    Tests may as well be launched by some keywords, e.g. each code check has
 *    a specific keyword which is given via \b AT_KEYWORD directive of Autotest.
 *    I.e. we may launch the test on \b config.h presence via the \a <option>
 *    \a -k \a config_h. Also multiple keywords may be given.
 *
 * \section codetest-results Inspecting results
 *
 *  The testsuite can be launched with the additional option of \a -d which leaves the
 *  directory of the test present even though the test has passed for inspection.
 *
 *  If a test fails, in whatever way it was launched, will leave in the build directory
 *  a folder \b tests/CodeChecks/testsuite.dir/<nr> where \a <nr> is the number of the
 *  test (padded maybe with some zeros).
 *
 *  In the current state tests will fail because one file does not include \b
 *  config.h or \b MemDebug.hpp. Hence, check the testsuite's log to get the file
 *  name of the culprit at its very bottom.
 *
 * \section unittest-add Adding new tests
 *
 *  \attention Name convention of files, (no spaces, use underscore) e.g.
 *  \b testsuite-config_h.at
 *  - the test script file should be called as follows:
 *    -# testsuite-...
 *    -# followed by the construct that is tested.
 *
 *  In order to add a new test, you have to do the following:
 *  -# Add a new \b testsuite-....at script to the folder \b tests/CodeChecks
 *    (have a look at the present ones and see above for help on the commands
 *    recognized by Autotest. \e Mind \e giving it a suitable \e keyword!).
 *  -# Add the file to Makefile.am such that the testsuite is re-created when
 *    you change the test script.
 *  -# Add the file as an \e m4_include directive to testsuite.at.
 *
 *
 * \date 2011-10-31
 *
 */