Unit Testing Support

Topics
	Unit Testing Definition Macros
	Unit Testing Assert Macros

Detailed Description

Teuchos contains simple but effective native unit testing support. Unit tests can be defined in separate files. This can be as simple as:

// Int_UnitTests.cpp
 
#include "Teuchos_UnitTestHarness.hpp"
 
namespace {
 
TEUCHOS_UNIT_TEST( Int, Basic )
{
  int i1 = 5;
  TEST_EQUALITY_CONST( i1, 5 );
}
 
TEUCHOS_UNIT_TEST( Int, Assignment )
{
  int i1 = 4;
  int i2 = i1;
  TEST_EQUALITY( i2, i1 );
}
 
} // namespace

and then compiled along with other unit testing definition files into executables along with a simple main function like:

// UnitTestMain.cpp
 
#include "Teuchos_UnitTestRepository.hpp"
#include "Teuchos_GlobalMPISession.hpp"
 
int main( int argc, char* argv[] )
{
  Teuchos::GlobalMPISession mpiSession(&argc, &argv);
  return Teuchos::UnitTestRepository::runUnitTestsFromMain(argc, argv);
}

using CMake code like:

PACKAGE_ADD_EXECUTABLE_AND_TEST(
  MyUnitTests
  SOURCES
    UnitTestMain.cpp
    Int_UnitTests.cpp
    ... other unit test files ...
  STANDARD_PASS_OUTPUT
  )

Once the Unit test exectuable is built, it will run with CTest automatically and produce output indicating which tests passed or failed. It is just run as:

  ./MyPackage_MyUnitTest.exe

One of the most useful properties of this simple unit testing support code is that the unit testing exectuable (created by the above CMake code) accepts command-line arguments for showing more or less output, runing only particular sets of tests, etc. Just pass in the –help flag to see all of the options as:

  ./MyPackage_MyUnitTest.exe --help

Now learn about unit tests, for example, at:

http://www.oreillynet.com/pub/a/oreilly/oracle/utplsql/news/fulldoc.html

References for Teuchos Unit Testing Support:

• Unit Testing DefinitionMacros: Macros used to define individual unit test blocks line TEUCHOS_UNIT_TEST().

• Unit Testing Assert Macros: Used within a given unit test to individual statement-level checks like TEST_EQUALITY().

Suggestions for unit testing:

• Put all unit tests for a given class MyClass into a single file with the name MyClass_UnitTests.cpp. This makes the unit tests for a class easy to find and maintain.

• Aggregate unit tests for related classes and functionality into single executables. Putting lots of related unit tests in the same exectuable ensures the process startup and shutdown for a given exectuable run by CTest does not overwelm the cost of the the actual unit tests. If well defined, you can run thousands of unit tests in a single exectuable in a fraction of a second.

• Don't bother writing you own simple UnitTestMain.cpp like above, just include the standard one teuchos/core/test/UnitTest/Teuchos_StandardUnitTestMain.cpp in your PACKAGE_ADD_EXECUTABLE_AND_TEST(...) CMake macro. If you are using a TriBITS build in a downstream package, you can just use the global CMake variable ${TEUCHOS_STD_UNIT_TEST_MAIN}.

• For parallel tests (using MPI), you can turn on automatic reductions across processes of pass/fail. To enable this by default for your unit tests, use the standard main source file teuchos/comm/test/UnitTesting/Teuchos_StandardParallelUnitTestMain.cpp and see the option Teuchos::UnitTestRepository::setGloballyReduceTestResult(). If you are using a TriBITS build in a downstream package, you can just use the global CMake variable ${TEUCHOS_STD_PARALLEL_UNIT_TEST_MAIN}.

• When doing Test-Driven Development (TDD), write a single unit test at a time (fail, pass, refactor) and constantly be rebuilding and rerunning the unit test executable.

• Get an idea of all the different ways you can write unit tests by searching for unit test examples in Trilinos by doing:

  $ find . -name "*" -exec grep -l 'TEUCHOS_UNIT_TEST' {} \;
  

  Just open a bunch of those files and see how people use these unit testing tools.

  Search packages like Teuchos, Tpetra, and Thyra first since these are the most numerous and mature unit testing examples you will find in Trilinos.