| OpenMS 2.5.0

Macros
Class test macros
Concept

These macros are used by the test programs in the subdirectory `OpenMS/source/TEST`. More...

## Macros

#define | START_TEST(class_name, version)
| Begin of the test program for a given class. More...
#define | END_TEST
| End of the test program for a class. More...
#define | START_SECTION(name_of_test)
| Begin of a subtest with a given name. More...
#define | END_SECTION
| End of a subtest. More...
#define | TEST_EQUAL(a, b)
| Generic equality macro. More...
#define | TEST_NOT_EQUAL(a, b)
| Generic inequality macro. More...
#define | TEST_STRING_EQUAL(a, b)
| String equality macro. More...
#define | TEST_FILE_EQUAL(filename, templatename)
| File comparison macro. More...
#define | TEST_REAL_SIMILAR(a, b)
| Floating point similarity macro. More...
#define | TEST_STRING_SIMILAR(a, b)
| String similarity macro. More...
#define | TEST_FILE_SIMILAR(a, b)
| File similarity macro. More...
#define | TOLERANCE_RELATIVE(a)
| Define the relative tolerance for floating point comparisons. More...
#define | TOLERANCE_ABSOLUTE(a)
| Define the absolute tolerance for floating point comparisons. More...
#define | WHITELIST(a) TEST::setWhitelist(__FILE__, __LINE__, (a));
| Define the whitelist_ used by TEST_STRING_SIMILAR and TEST_FILE_SIMILAR. More...
#define | TEST_EXCEPTION(exception_type, command)
| Exception test macro. More...
#define | TEST_PRECONDITION_VIOLATED(command)
| Precondition test macro. More...
#define | TEST_POSTCONDITION_VIOLATED(command)
| Postcondition test macro. More...
#define | TEST_EXCEPTION_WITH_MESSAGE(exception_type, command, message)
| Exception test macro (with test for exception message). More...
#define | NEW_TMP_FILE(filename)
| Create a temporary filename. More...
#define | ABORT_IF(condition)
| Skip the remainder of the current subtest. More...
#define | STATUS(message)
| Print a status message. More...
#define | ADD_MESSAGE(message)
| Sets an additional text that is displayed after final result of the test. More...
#define | NOT_TESTABLE
| Macro that suppresses the warning issued when no subtests are performed. More...

## Detailed Description

These macros are used by the test programs in the subdirectory `OpenMS/source/TEST`.

On successful operation the test program will print out the message "PASSED", otherwise "FAILED".

If called with the -v option, the test program prints verbose information about subsections.

If called with the -V option, the test program prints even more verbose information for every elementary test.

The implementation is done in namespace OpenMS::Internal::ClassTest.

To create a test you can use the 'create_test.php' script in OpenMS/tools/ (other useful scripts in the same directory - have a look).

## Macro Definition Documentation

## ◆ ABORT_IF

#define ABORT_IF | ( |  | condition | ) |

Skip the remainder of the current subtest.

If the condition is not fulfilled, the remainder of the current subtest is skipped over. The status (whether it fails or passes) remains unchanged.

## ◆ ADD_MESSAGE

#define ADD_MESSAGE | ( |  | message | ) |

Sets an additional text that is displayed after final result of the test.

This can be used to provide additional information about the test to the user. It is e.g. used to indicate that the DB test were skipped, when there are no credentials given.

## ◆ END_SECTION

#define END_SECTION

End of a subtest.

See also
  START_SECTION.

The END_SECTION macro defines the end of a subtest.

Each elementary test macro updates an internal variable (TEST::test) that holds the state of the current subtest. END_SECTION prints whether the subtest has passed or failed (in verbose mode) and updates the internal variables TEST::all_tests that describes the state of the whole class test. TEST::all_tests is initialized to be true. If any elementary test fails, TEST::test becomes false. At the time of the next call to END_SECTION, TEST::all_tests will be set to false, if TEST::test is false. One failed elementary test leads therefore to a failed subtest, which leads to a failed class test.

This macro closes the `try` block opened by START_SECTION, so START_SECTION and END_SECTION have to be balanced, or some ugly compile-time errors will occur. END_SECTION first tries to catch all `OpenMS::Exception`s (i.e. exceptions derived from OpenMS::Exception::BaseException). If this fails, it tries to catch any exception. After the exception is caught, the execution will continue with the next subtest, but the current subtest is marked as failed (as is the whole test program).

## ◆ END_TEST

#define END_TEST

End of the test program for a class.

See also
  START_TEST.

The END_TEST macro implements the correct termination of the test program and should therefore be the last macro to call. It determines the exit code based on all previously run subtests and prints out the message "PASSED" or "FAILED". This macro also closes the global `try` block opened by START_TEST and contains the related `catch` clauses. If an exception is caught here, the test program fails.

## ◆ NEW_TMP_FILE

#define NEW_TMP_FILE | ( |  | filename | ) |

Create a temporary filename.

This macro assigns a new temporary filename to the string variable given as its argument. The filename is created using the filename of the test and the line number where this macro is invoked, for example 'Matrix_test.cpp' might create a temporary file 'Matrix_test_268.tmp' if NEW_TMP_FILE is used in line 268. All temporary files are deleted if END_TEST is called.

Parameters

  filename | string will contain the filename on completion of the macro.

All temporary files are validated using the XML schema,if the type of file can be determined by FileHandler. Therefore for each file written in a test NEW_TMP_FILE should be called. Otherwise only the last written file is checked.

## ◆ NOT_TESTABLE

#define NOT_TESTABLE

Macro that suppresses the warning issued when no subtests are performed.

Please use this macro only if the method cannot be tested at all or cannot be tested properly on its own. In the later case, the method must however be tested in tests of related methods. See also test_count.

## ◆ START_SECTION

#define START_SECTION | ( |  | name_of_test | ) |

Begin of a subtest with a given name.

See also
  END_SECTION.

The START_SECTION macro is used to declare the name of a subtest. Use this to examine a member function of the class which was specified in START_TEST. If you want to check e.g. the memFunc() method of a class, insert a line START_SECTION(memFunc()) in your test program. If the test program is called in verbose mode, this leads to the name of the subtest being printed on execution. If you are testing a non-public method you can use the [EXTRA] statement, e.g. START_SECTION([EXTRA]memFunc()) to indicate this. Otherwise you will trigger a warning by OpenMS/tools/checker.php due to this unexpected subtest.

This macro also opens a `try` block to catch any unexpected exceptions thrown in the course of a subtest. To catch wanted exceptions (i.e. to check for exceptions that are the expected result of some command) use the TEST_EXCEPTION macro. The `try` block opened by START_SECTION is closed in END_SECTION, so these two macros have to be balanced.

## ◆ START_TEST

#define START_TEST | ( |  | class_name,
|  |  | version
| ) |  |

Begin of the test program for a given class.

See also
  END_TEST.

The START_TEST macro defines the start of the test program for a given classname. The classname is printed together with some information when calling the test program with any arguments (except for `-v` or `-V`).

The second argument version should take the form "$Id:$" but is currently deprecated. Originally, the SVN revision was annotated by the revision control system.

The START_TEST macro should be the first one to call in a test program. It opens a global `try` block to catch any unwanted exceptions. If any of these exceptions occurs, all tests fail. Exceptions defined by OpenMS (i.e. exception classes derived from Exception::BaseException) provide some additional information that is evaluated by the END_TEST macro. The END_TEST macro also closes the `try` block. This `try` block should never catch an exception! All exceptions that are thrown due to some malfunction in one of the member functions should be caught by the `try` block created by START_SECTION and END_SECTION .

## ◆ STATUS

#define STATUS | ( |  | message | ) |

Print a status message.

If tests require longer preparations, STATUS may be used to print some intermediate progress messages. STATUS uses `cout` to print these messages (in verbose mode only). The given stream expression `message` is prefixed by the string `status:` and terminated with a newline. All valid operations on a stream may be performed in `message`.

Example: `STATUS( "just calculated x = " << precisionWrapper(x) )`

## ◆ TEST_EQUAL

#define TEST_EQUAL | ( |  | a,
|  |  | b
| ) |  |

Generic equality macro.

This macro uses the operator == to check its two arguments for equality. Besides handling some internal stuff, it basically evaluates ((a) == (b)).

Remember that operator == has to be defined somehow for the two argument types. Additionally the << operator needs to be defined. If only == is available you will get a compilation error. As workaround use TEST_EQUAL(a==b, true) thereby making bug tracing harder, as you won't see the values of a and b.

Note
  This macro evaluates its arguments once or twice, depending on verbosity settings.

Parameters

  a | value/object to test
  b | expected value

## ◆ TEST_EXCEPTION

#define TEST_EXCEPTION | ( |  | exception_type,
|  |  | command
| ) |  |

Exception test macro.

This macro checks if a given type of exception occurred while executing the given command. Example: TEST_EXCEPTION(Exception::IndexOverflow, vector[-1]). If no or a wrong exception occurred, false is returned, otherwise true.

Parameters

  exception_type | the exception-class
  command | any general C++ or OpenMS-specific command

## ◆ TEST_EXCEPTION_WITH_MESSAGE

#define TEST_EXCEPTION_WITH_MESSAGE | ( |  | exception_type,
|  |  | command,
|  |  | message
| ) |  |

Exception test macro (with test for exception message).

This macro checks if a given type of exception occurred while executing the given command and additionally tests for the message of the exception.

Example: TEST_EXCEPTION_WITH_MESSAGE(Exception::IndexOverflow, vector[-1], "a null pointer was specified")

If no, a wrong exception occurred or a wrong message is returned, false is returned, otherwise true.

Parameters

  exception_type | the exception-class
  command | any general C++ or OpenMS-specific command
  message | the message the exception should give

## ◆ TEST_FILE_EQUAL

#define TEST_FILE_EQUAL | ( |  | filename,
|  |  | templatename
| ) |  |

File comparison macro.

This macro is used to test file operations. It compares the file with name `filename` against a template file `templatename`. Corresponding lines of the two files have to be identical.

Note
  line length is limited to 64k characters
  This macro evaluates its arguments once or twice, depending on verbosity settings.

## ◆ TEST_FILE_SIMILAR

#define TEST_FILE_SIMILAR | ( |  | a,
|  |  | b
| ) |  |

File similarity macro.

Compares the two files using FuzzyStringComparator with the settings of TOLERANCE_ABSOLUTE and TOLERANCE_RELATIVE.

Note
  This macro evaluates its arguments once or twice, depending on verbosity settings.
  The actual comparison is done by isFileSimilar().

Parameters

  a | value to test
  b | expected value

## ◆ TEST_NOT_EQUAL

#define TEST_NOT_EQUAL | ( |  | a,
|  |  | b
| ) |  |

Generic inequality macro.

This macro checks for inequality just like TEST_EQUAL tests for equality. The only difference between the two macros is that TEST_NOT_EQUAL evaluates !((a) == (b)).

Parameters

  a | value/object to test
  b | forbidden value

## ◆ TEST_POSTCONDITION_VIOLATED

#define TEST_POSTCONDITION_VIOLATED | ( |  | command | ) |

Postcondition test macro.

This macro checks if a postcondition violation is detected while executing the command, similar to `TEST_EXCEPTION(Exception::Postcondition,command)`. However the test is executed only when the OPENMS_POSTCONDITION macros are active, i.e., when compiling in Debug mode. (See Macros.h)

Parameters

  command | any general C++ or OpenMS-specific command

## ◆ TEST_PRECONDITION_VIOLATED

#define TEST_PRECONDITION_VIOLATED | ( |  | command | ) |

Precondition test macro.

This macro checks if a precondition violation is detected while executing the command, similar to `TEST_EXCEPTION(Exception::Precondition,command)`. However the test is executed only when the OPENMS_PRECONDITION macros are active, i.e., when compiling in Debug mode. (See Macros.h)

Parameters

  command | any general C++ or OpenMS-specific command

## ◆ TEST_REAL_SIMILAR

#define TEST_REAL_SIMILAR | ( |  | a,
|  |  | b
| ) |  |

Floating point similarity macro.

Checks whether the two numbers are sufficiently close based upon the settings of TOLERANCE_ABSOLUTE and TOLERANCE_RELATIVE.

Note
  This macro evaluates its arguments once or twice, depending on verbosity settings.
  Both arguments are converted to `double`. The actual comparison is done by isRealSimilar().

Parameters

  a | value to test
  b | expected value

## ◆ TEST_STRING_EQUAL

#define TEST_STRING_EQUAL | ( |  | a,
|  |  | b
| ) |  |

String equality macro.

Both arguments are converted to std::string and tested for equality. (That is, we check whether `(std::string(a) == std::string(b))` holds.)

Note
  This macro evaluates its arguments once or twice, depending on verbosity settings.

Parameters

  a | value to test
  b | expected value

## ◆ TEST_STRING_SIMILAR

#define TEST_STRING_SIMILAR | ( |  | a,
|  |  | b
| ) |  |

String similarity macro.

Compares the two strings using FuzzyStringComparator with the settings of TOLERANCE_ABSOLUTE and TOLERANCE_RELATIVE.

Note
  This macro evaluates its arguments once or twice, depending on verbosity settings.
  Both arguments are converted to `std::string`. The actual comparison is done by testStringSimilar().

Parameters

  a | value to test
  b | expected value

## ◆ TOLERANCE_ABSOLUTE

#define TOLERANCE_ABSOLUTE | ( |  | a | ) |

Define the absolute tolerance for floating point comparisons.

See also
  TEST_REAL_SIMILAR, TEST_STRING_SIMILAR, TEST_FILE_SIMILAR

Several macros consider two numbers sufficiently "close" if the absolute difference is bounded by the value supplied by TOLERANCE_ABSOLUTE. The default value is . It is possible to redefine the absolute tolerance by calling TOLERANCE_ABSOLUTE with the new value.

## ◆ TOLERANCE_RELATIVE

#define TOLERANCE_RELATIVE | ( |  | a | ) |

Define the relative tolerance for floating point comparisons.

See also
  TEST_REAL_SIMILAR, TEST_STRING_SIMILAR, TEST_FILE_SIMILAR

Several macros consider two numbers sufficiently "close" if the ratio of the larger and the smaller is bounded by the value supplied by TOLERANCE_RELATIVE. The default value is . It is possible to redefine the relative tolerance by calling TOLERANCE_RELATIVE with the new value.

## ◆ WHITELIST

#define WHITELIST | ( |  | a | ) | TEST::setWhitelist(__FILE__, __LINE__, (a));

Define the whitelist_ used by TEST_STRING_SIMILAR and TEST_FILE_SIMILAR.

If both lines contain the same element from this list, they are skipped over. (See FuzzyStringComparator.)