Test System Macros - SeqAn API Documentation

# Group Test System Macros
Macros for the test system.

## Grouped Macros Overview

`SEQAN_BEGIN_TESTSUITE(name)` Expand to a test suite beginning.
`SEQAN_CALL_TEST(test_name);` Expand to calling a test.
`SEQAN_DEFINE_TEST(test_name)` Expand to test definition.
`SEQAN_ENABLE_DEBUG` Indicates whether debugging is enabled.
`SEQAN_ENABLE_TESTING` Indicates whether testing is enabled.
`SEQAN_END_TESTSUITE` Expand to test suite ending.
`SEQAN_SKIP_TEST;` Force the test to return without failing and mark it as skipped.
`SEQAN_TYPEDE_FOR_DEBUG` When using typedefs that are only used in debug mode then they have to be marked with macro.

## Grouped Macros Detail

### TestSystemMacros#SEQAN_BEGIN_TESTSUITE

Defined in
  <seqan/basic.h>

`SEQAN_BEGIN_TESTSUITE(name)`
Expand to a test suite beginning.

Parameters
  `name` (in) - The name of the test suite.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro expands to a `main()` function and some initialization code that sets up the test system.

#### Examples

    #include <seqan/basic.h>

    SEQAN_BEGIN_TESTSUITE(test_foo)
    {
       SEQAN_CALL_TEST(test_foo_my_test);
    }
    SEQAN_END_TESTSUITE

### TestSystemMacros#SEQAN_CALL_TEST

Defined in
  <seqan/basic.h>

`SEQAN_CALL_TEST(test_name);`
Expand to calling a test.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This expects the test to be defined with SEQAN_DEFINE_TEST. This macro will expand to code that calls the code inside a try/catch block. Use this macro within a test suite, only.

#### Examples

    // Within a test suite.
    SEQAN_CALL_TEST(test_name);

### TestSystemMacros#SEQAN_DEFINE_TEST

Defined in
  <seqan/basic.h>

`SEQAN_DEFINE_TEST(test_name)`
Expand to test definition.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro expands to the definition of a $void$ function with `SEQAN_TEST_ + test_name` as its name.

#### Example

    SEQAN_DEFINE_TEST(test_name)
    {
        SEQAN_ASSERT_LT(0, 3);
    }

### TestSystemMacros#SEQAN_ENABLE_DEBUG

Defined in
  <seqan/basic.h>

`SEQAN_ENABLE_DEBUG`
Indicates whether debugging is enabled.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  SEQAN_ENABLE_TESTING

When enabled (set to 1) then debugging is enabled. This means the assertion macros are expanded to actual test code. If debugging (and testing) is disabled then the SeqAn assertion macros expand to no instructions.

Note that `NDEBUG` is set undefined if `SEQAN_ENABLE_DEBUG` = 1 and `NDEBUG` is set to 1 if `SEQAN_ENABLE_DEBUG` = 0.

If you want to change this value then you have to define this value before including any SeqAn header.

Force-enabled if SEQAN_ENABLE_TESTING is set to 1.

### TestSystemMacros#SEQAN_ENABLE_TESTING

Defined in
  <seqan/basic.h>

`SEQAN_ENABLE_TESTING`
Indicates whether testing is enabled.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  SEQAN_ENABLE_DEBUG

When set to 1, testing is enabled. If it is undefined or set to 0, testing is disabled. This means the macros for the tests (SEQAN_BEGIN_TESTSUITE, SEQAN_DEFINE_TEST, SEQAN_CALL_TEST, and SEQAN_END_TESTSUITE) will be enabled. This makes failing assertions raise exceptions instead of calling `abort()` (which terminates the program).

By default, this is set to 0.

If you want to change this value in your C++ program code you have to define this value before including any SeqAn header!

If set to 1 then SEQAN_ENABLE_DEBUG is forced to 1 as well.

### TestSystemMacros#SEQAN_END_TESTSUITE

Defined in
  <seqan/basic.h>

`SEQAN_END_TESTSUITE`
Expand to test suite ending.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro expands to finalization code for a test suite.

#### Examples

    #include <seqan/basic.h>

    SEQAN_BEGIN_TESTSUITE(test_foo)
    {
        SEQAN_CALL_TEST(test_foo_my_test);
    }
    SEQAN_END_TESTSUITE

### TestSystemMacros#SEQAN_SKIP_TEST

Defined in
  <seqan/basic.h>

`SEQAN_SKIP_TEST;`
Force the test to return without failing and mark it as skipped.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Examples

    SEQAN_DEFINE_TEST(test_skipped)
    {
        SEQAN_SKIP_TEST;
    }

### TestSystemMacros#SEQAN_TYPEDEF_FOR_DEBUG

Defined in
  <seqan/basic.h>

`SEQAN_TYPEDE_FOR_DEBUG`
When using typedefs that are only used in debug mode then they have to be marked with macro.

Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Examples

    typedef int TInt SEQAN_TYPEDEF_FOR_DEBUG;

#### Dox Sources

    /*!
     * @defgroup TestSystemMacros Test System Macros
     *
     * @brief Macros for the test system.
     *
     * @macro TestSystemMacros#SEQAN_ENABLE_TESTING
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Indicates whether testing is enabled.
     *
     * @signature SEQAN_ENABLE_TESTING
     *
     * When set to 1, testing is enabled. If it is undefined or set to 0, testing is
     * disabled. This means the macros for the tests (SEQAN_BEGIN_TESTSUITE,
     * SEQAN_DEFINE_TEST, SEQAN_CALL_TEST, and SEQAN_END_TESTSUITE) will be enabled.
     * This makes failing assertions raise exceptions instead of calling
     * <tt>abort()</tt> (which terminates the program).
     *
     * By default, this is set to 0.
     *
     * If you want to change this value in your C++ program code you have to define
     * this value before including any SeqAn header!
     *
     * If set to 1 then @link TestSystemMacros#SEQAN_ENABLE_DEBUG @endlink is forced
     * to 1 as well.
     *
     * @see TestSystemMacros#SEQAN_ENABLE_DEBUG
     *
     * @macro TestSystemMacros#SEQAN_ENABLE_DEBUG
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Indicates whether debugging is enabled.
     *
     * @signature SEQAN_ENABLE_DEBUG
     *
     * When enabled (set to 1) then debugging is enabled. This means the assertion
     * macros are expanded to actual test code. If debugging (and testing) is
     * disabled then the SeqAn assertion macros expand to no instructions.
     *
     * Note that <tt>NDEBUG</tt> is set undefined if <tt>SEQAN_ENABLE_DEBUG</tt> = 1
     * and <tt>NDEBUG</tt> is set to 1 if <tt>SEQAN_ENABLE_DEBUG</tt> = 0.
     *
     * If you want to change this value then you have to define this value before
     * including any SeqAn header.
     *
     * Force-enabled if SEQAN_ENABLE_TESTING is set to 1.
     *
     * @see TestSystemMacros#SEQAN_ENABLE_TESTING
     *
     * @macro TestSystemMacros#SEQAN_TYPEDEF_FOR_DEBUG
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief When using typedefs that are only used in debug mode then they have to
     *        be marked with macro.
     *
     * @signature SEQAN_TYPEDE_FOR_DEBUG
     *
     * @section Examples
     *
     * @code{.cpp}
     * typedef int TInt SEQAN_TYPEDEF_FOR_DEBUG;
     * @endcode
     *
     *
     * @macro TestSystemMacros#SEQAN_DEFINE_TEST
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Expand to test definition.
     *
     * @signature SEQAN_DEFINE_TEST(test_name)
     *
     * This macro expands to the definition of a $void$ function with
     * <tt>SEQAN_TEST_ + test_name</tt> as its name.
     *
     * @section Example
     *
     * @code{.cpp}
     * SEQAN_DEFINE_TEST(test_name)
     * {
     *     SEQAN_ASSERT_LT(0, 3);
     * }
     * @endcode
     *
     *
     * @macro TestSystemMacros#SEQAN_BEGIN_TESTSUITE
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Expand to a test suite beginning.
     *
     * @signature SEQAN_BEGIN_TESTSUITE(name)
     *
     * @param[in] name The name of the test suite.
     *
     * This macro expands to a <tt>main()</tt> function and some initialization code
     * that sets up the test system.
     *
     * @section Examples
     *
     * @code{.cpp}
     * #include <seqan/basic.h>
     *
     * SEQAN_BEGIN_TESTSUITE(test_foo)
     * {
     *    SEQAN_CALL_TEST(test_foo_my_test);
     * }
     * SEQAN_END_TESTSUITE
     * @endcode
     *
     *
     * @macro TestSystemMacros#SEQAN_END_TESTSUITE
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Expand to test suite ending.
     *
     * @signature SEQAN_END_TESTSUITE
     *
     * This macro expands to finalization code for a test suite.
     *
     * @section Examples
     *
     * @code{.cpp}
     * #include <seqan/basic.h>
     *
     * SEQAN_BEGIN_TESTSUITE(test_foo)
     * {
     *     SEQAN_CALL_TEST(test_foo_my_test);
     * }
     * SEQAN_END_TESTSUITE
     * @endcode
     *
     *
     * @macro TestSystemMacros#SEQAN_CALL_TEST
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Expand to calling a test.
     *
     * @signature SEQAN_CALL_TEST(test_name);
     *
     * This expects the test to be defined with SEQAN_DEFINE_TEST. This macro will
     * expand to code that calls the code inside a try/catch block. Use this macro
     * within a test suite, only.
     *
     * @section Examples
     *
     * @code{.cpp}
     * // Within a test suite.
     * SEQAN_CALL_TEST(test_name);
     * @endcode
     *
     *
     * @macro TestSystemMacros#SEQAN_SKIP_TEST
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Force the test to return without failing and mark it as skipped.
     *
     * @signature SEQAN_SKIP_TEST;
     *
     * @section Examples
     *
     * @code{.cpp}
     * SEQAN_DEFINE_TEST(test_skipped)
     * {
     *     SEQAN_SKIP_TEST;
     * }
     * @endcode
     */