MueLu's unit tests

As stated in the Trilinos developers guide, one of the goal of the project is to have every parts of the code unit-tested to ensure quality and backward compatibility when new features are added to the code. MueLu's unit-tests are located in Trilinos/packages/muelu/test/unit_tests/ and consist of a simple .cpp file, they might also include .xml files to drive tests. The unit-tests code is generally encapsulated in the MueLuTests namespace and to ease the bundling and instantiation of the tests, helper functions and macros are used in these tests, notably the headers:

#include <Teuchos_UnitTestHarness.hpp>
#include <Teuchos_TestingHelpers.hpp>
#include <Teuchos_ScalarTraits.hpp>
#include <MueLu_TestHelpers.hpp>
#include <MueLu_Version.hpp>

are always included.

The test functions signature are generated by the following macro: TEUCHOS_UNIT_TEST_TEMPLATE_4_DECL. (Similar macros exist for unit tests with some number of template declarations different than four.)

Proper instantiation of the arguments of the test functions is realized by the following macro which is added at the end of the .cpp file, usually just before closing the namespace;

#define MUELU_ETI_GROUP(Scalar,LO,GO,Node) \
  TEUCHOS_UNIT_TEST_TEMPLATE_4_INSTANT(MyTestGroupName,MyTestName1,Scalar,LO,GO,Node) \
  TEUCHOS_UNIT_TEST_TEMPLATE_4_INSTANT(MyTestGroupName,MyTestName2,Scalar,LO,GO,Node)

#include <MueLu_ETI_4arg.hpp>

A few more useful macros to write unit-test are:

    MUELU_TESTING_SET_OSTREAM;
    MUELU_TESTING_LIMIT_SCOPE(Scalar,GlobalOrdinal,Node);
    TEST_EQUALITY(some logical test, expected output of the logical test)

The first macro handles the level of printing in the test, the second provides fine grained control of the explicit template instantiation of the test, the third macro is used to check whether the test is successful or not. Here is the full list of Teuchos macros for checking test success.

To ensure that your unit-test is properly compiled and included into the test-suite of MueLu you need to modify the CMakeLists.txt file. Mainly you need to add the path to your unit test source code to the SOURCES set, which is done as follows:

APPEND_SET(SOURCES
  path/to/myTest.cpp
)

This command can be guarded by CMake if statements when myTest.cpp depends on a particular package or TPL.

Finally, keep in mind that most of these test are run by y the pull request auto-tester. So, please ensure that your test, while verifying that all the tested functions work properly, the time spend in the test should be kept as short as possible.