Gromacs  2020.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Macros | Enumerations | Functions | Directories | Files
Testing Utilities (testutils)
+ Collaboration diagram for Testing Utilities (testutils):

Description

Common helper classes and functions for writing tests using Google Test.

General documentation for the testing in GROMACS can be found in the developer guide. This page provides an overview of the actual API provided by the testutils module.

There are several distinct functionalities provided:

Additionally, testinit.h and mpi_printer.h, and their corresponding source files, provide functionality that is not visible on the API level: they provide initialization routines for the above functionality, which are automatically called by the main() function provided in unittest_main.cpp.

mpi_printer.h provides a Google Test listener that is installed when the tests are compiled with MPI. This listener allows the test binary to be run on multiple MPI ranks, and synchronizes the execution and output from the test cases, as well as makes the test fail on even if an assertion fails only on one rank.

Helper functions for computing floating-point differences

These routines are used to initialize FloatingPointDifference. They peek into some internal types from Google Test (gtest-internal.h), and duplicate some other functionality from there, but that is likely a better alternative than just copying all that code here.

template<typename FloatType >
FloatingPoint< FloatType >::Bits gmx::test::anonymous_namespace{testasserts.cpp}::floatingPointToBiasedInteger (const FloatingPoint< FloatType > &value)
 Computes biased integer representation for a floating-point value. More...
 
template<typename FloatType >
uint64_t gmx::test::anonymous_namespace{testasserts.cpp}::calculateUlpDifference (const FloatingPoint< FloatType > &value1, const FloatingPoint< FloatType > &value2)
 Computes the magnitude of the difference in ULPs between two numbers, treating also values of different sign.
 
template<typename FloatType >
void gmx::test::anonymous_namespace{testasserts.cpp}::initDifference (FloatType raw1, FloatType raw2, double *absoluteDifference, uint64_t *ulpDifference, bool *bSignDifference)
 Helper to implement the constructors for FloatingPointDifference.
 
template<typename FloatType >
uint64_t gmx::test::anonymous_namespace{testasserts.cpp}::relativeToleranceToUlp (FloatType tolerance)
 Converts a relative tolerance into an ULP difference.
 

Assertions for exceptions

These macros replace (ASSERT|EXPECT)(_NO)?_THROW from Google Test. They are used exactly like the Google Test ones, but also print details of any unexpected exceptions using GROMACS-specific routines. This makes it much easier to see at one glance what went wrong. See Google Test documentation for details on how to use the macros.

#define GMX_TEST_THROW_(statement, expected_exception, fail)
 Internal implementation macro for exception assertations. More...
 
#define GMX_TEST_NO_THROW_(statement, fail)
 Internal implementation macro for exception assertations. More...
 
#define EXPECT_THROW_GMX(statement, expected_exception)
 Asserts that a statement throws a given exception.
 
#define EXPECT_NO_THROW_GMX(statement)
 Asserts that a statement does not throw.
 
#define ASSERT_THROW_GMX(statement, expected_exception)
 Asserts that a statement throws a given exception.
 
#define ASSERT_NO_THROW_GMX(statement)
 Asserts that a statement does not throw.
 
#define GMX_EXPECT_DEATH_IF_SUPPORTED(expr, msg)
 Wrapper around EXPECT_DEATH_IF_SUPPORTED gtest macro for thread safe execution. More...
 
#define GMX_ASSERT_DEATH_IF_SUPPORTED(expr, msg)
 Wrapper around ASSERT_DEATH_IF_SUPPORTED gtest macro for thread safe execution. More...
 

Assertions for floating-point comparison

These routines extend (EXPECT|ASSERT)_(FLOAT|DOUBLE)_EQ and (EXPECT|ASSERT)_NEAR from Google Test to provide more flexible assertions for floating-point values.

See gmx::test::FloatingPointTolerance for the possible ways to specify the tolerance, and gmx::test::FloatingPointDifference for some additional details of the difference calculation.

template<typename FloatType >
static
inline::testing::AssertionResult 
gmx::test::assertEqualWithinTolerance (const char *expr1, const char *expr2, const char *, FloatType value1, FloatType value2, const FloatingPointTolerance &tolerance)
 Assertion predicate formatter for comparing two floating-point values. More...
 
#define EXPECT_FLOAT_EQ_TOL(value1, value2, tolerance)
 Asserts that two single-precision values are within the given tolerance.
 
#define EXPECT_DOUBLE_EQ_TOL(value1, value2, tolerance)
 Asserts that two double-precision values are within the given tolerance.
 
#define EXPECT_REAL_EQ_TOL(value1, value2, tolerance)
 Asserts that two real values are within the given tolerance.
 
#define ASSERT_FLOAT_EQ_TOL(value1, value2, tolerance)
 Asserts that two single-precision values are within the given tolerance.
 
#define ASSERT_DOUBLE_EQ_TOL(value1, value2, tolerance)
 Asserts that two double-precision values are within the given tolerance.
 
#define ASSERT_REAL_EQ_TOL(value1, value2, tolerance)
 Asserts that two real values are within the given tolerance.
 
#define EXPECT_REAL_EQ(value1, value2)   EXPECT_REAL_EQ_TOL(value1, value2, ::gmx::test::defaultRealTolerance())
 EXPECT_REAL_EQ_TOL with default tolerance.
 
#define ASSERT_REAL_EQ(value1, value2)   ASSERT_REAL_EQ_TOL(value1, value2, ::gmx::test::defaultRealTolerance())
 ASSERT_REAL_EQ_TOL with default tolerance.
 

Classes

class  gmx::test::CommandLine
 Helper class for tests that need to construct command lines. More...
 
class  gmx::test::CommandLineTestHelper
 Helper class for tests that construct command lines that need to reference existing files. More...
 
class  gmx::test::CommandLineTestBase
 Test fixture for tests that call a single command-line program with input/output files. More...
 
class  gmx::test::ConfMatch
 Match the contents as an gro file. More...
 
class  gmx::test::IFileMatcher
 Represents a file matcher, matching file contents against reference (or other) data. More...
 
class  gmx::test::IFileMatcherSettings
 Represents a factory for creating a file matcher. More...
 
class  gmx::test::TextFileMatch
 Use a ITextBlockMatcher for matching the contents. More...
 
class  gmx::test::NoContentsMatch
 Do not check the contents of the file. More...
 
class  gmx::test::InteractiveTestHelper
 Helper class for testing interactive sessions. More...
 
class  gmx::test::LoggerTestHelper
 Helper class for tests to check output written to a logger. More...
 
class  gmx::test::internal::TestReferenceDataImpl
 Private implementation class for TestReferenceData. More...
 
class  gmx::test::TestReferenceChecker::Impl
 Private implementation class for TestReferenceChecker. More...
 
class  gmx::test::TestReferenceData
 Handles creation of and comparison to test reference data. More...
 
class  gmx::test::TestReferenceChecker
 Handles comparison to test reference data. More...
 
class  gmx::test::StdioTestHelper
 Helper class for tests where code reads directly from stdin. More...
 
class  gmx::test::StringTestBase
 Test fixture for tests that check string formatting. More...
 
class  gmx::test::FloatingPointDifference
 Computes and represents a floating-point difference value. More...
 
class  gmx::test::FloatingPointTolerance
 Specifies a floating-point comparison tolerance and checks whether a difference is within the tolerance. More...
 
class  gmx::test::TestException
 Exception class for reporting errors in tests. More...
 
class  gmx::test::TestFileManager
 Helper for tests that need input and output files. More...
 
class  gmx::test::TestFileInputRedirector
 In-memory implementation for IFileInputRedirector for tests. More...
 
class  gmx::test::TestFileOutputRedirector
 In-memory implementation of IFileOutputRedirector for tests. More...
 
class  gmx::test::anonymous_namespace{testinit.cpp}::TestProgramContext
 Custom program context for test binaries. More...
 
class  gmx::test::anonymous_namespace{testoptions.cpp}::TestOptionsRegistry
 Singleton registry for test options added with GMX_TEST_OPTIONS. More...
 
class  gmx::test::TestOptionsProvider
 Provides additional options for the test executable. More...
 
class  gmx::test::ITextBlockMatcher
 Represents a text matcher, matching text stream contents against reference data. More...
 
class  gmx::test::ITextBlockMatcherSettings
 Represents a factory for creating a text matcher. More...
 
class  gmx::test::ExactTextMatch
 Use an exact text match (the contents should be exactly equal). More...
 
class  gmx::test::NoTextMatch
 Do not match the text (the contents are ignored). More...
 
class  gmx::test::FilteringExactTextMatch
 Use an exact text match after scrubbing lines of the text that match the supplied regular expressions. More...
 
class  gmx::test::XvgMatch
 Match the contents as an xvg file. More...
 

Macros

#define GMX_MPI_TEST(expectedRankCount)   ASSERT_EQ(expectedRankCount, ::gmx::test::getNumberOfTestMpiRanks())
 Declares that this test is an MPI-enabled unit test. More...
 
#define EXPECT_PLAIN(expr)
 Assert for predicates that return AssertionResult and produce a full failure message. More...
 
#define ASSERT_PLAIN(expr)
 Assert for predicates that return AssertionResult and produce a full failure message. More...
 
#define GMX_TEST_OPTIONS(name, options)
 Macro to add additional command-line options for the test binary. More...
 

Enumerations

enum  gmx::test::ReferenceDataMode { gmx::test::erefdataCompare, gmx::test::erefdataCreateMissing, gmx::test::erefdataUpdateChanged, gmx::test::erefdataUpdateAll }
 Mode of operation for reference data handling. More...
 

Functions

void gmx::test::initMPIOutput ()
 Customizes test output and test failure handling for MPI runs. More...
 
int gmx::test::getNumberOfTestMpiRanks ()
 Returns the number of MPI ranks to use for an MPI test. More...
 
bool gmx::test::threadMpiTestRunner (std::function< void()> testBody)
 Helper function for GMX_MPI_TEST().
 
void gmx::test::initReferenceData (IOptionsContainer *options)
 Initializes reference data handling. More...
 
ReferenceDataEntry::EntryPointer gmx::test::readReferenceDataFile (const std::string &path)
 Loads reference data from an XML file. More...
 
void gmx::test::writeReferenceDataFile (const std::string &path, const ReferenceDataEntry &root)
 Saves reference data to an XML file. More...
 
static
inline::testing::AssertionResult 
gmx::test::plainAssertHelper (const char *, const ::testing::AssertionResult &expr)
 Helper method for (EXPECT|ASSERT)_PLAIN. More...
 
void gmx::test::initTestUtils (const char *dataPath, const char *tempPath, bool usesMpi, bool usesHardwareDetection, int *argc, char ***argv)
 Initializes the test utilities library. More...
 
void gmx::test::finalizeTestUtils ()
 Finalizes the test utilities library. More...
 
void gmx::test::registerTestOptions (const char *name, TestOptionsProvider *provider)
 Registers a test option provider with the test framework. More...
 
void gmx::test::initTestOptions (IOptionsContainer *options)
 Initializes the options from all registered test providers. More...
 
template<typename FloatType >
FloatType anonymous_namespace{testasserts_tests.cpp}::addUlps (FloatType value, int ulps)
 Helper to produce floating-point numbers with specified ULP difference. More...
 
static FloatingPointTolerance ulpTolerance (uint64_t ulpDiff)
 Creates a tolerance that only allows a specified ULP difference. More...
 
FloatingPointTolerance relativeToleranceAsFloatingPoint (double magnitude, double tolerance)
 Creates a tolerance that allows a difference in two compared values that is relative to the given magnitude. More...
 
FloatingPointTolerance relativeToleranceAsPrecisionDependentFloatingPoint (double magnitude, float singleTolerance, double doubleTolerance)
 Creates a tolerance that allows a precision-dependent difference in two compared values that is relative to the given magnitude. More...
 
static FloatingPointTolerance relativeToleranceAsPrecisionDependentUlp (double magnitude, uint64_t singleUlpDiff, uint64_t doubleUlpDiff)
 Creates a tolerance that allows a precision-dependent relative difference in a complex computation. More...
 
static FloatingPointTolerance absoluteTolerance (double tolerance)
 Creates a tolerance that allows a specified absolute difference.
 
static FloatingPointTolerance relativeToleranceAsUlp (double magnitude, uint64_t ulpDiff)
 Creates a tolerance that allows a relative difference in a complex computation. More...
 
static FloatingPointTolerance defaultRealTolerance ()
 Returns the default tolerance for comparing real numbers.
 
static FloatingPointTolerance defaultFloatTolerance ()
 Returns the default tolerance for comparing single-precision numbers when compared by GROMACS built in either precision mode. More...
 

Directories

directory testutils
 Testing Utilities (testutils)
 
directory tests
 Unit tests for Testing Utilities (testutils).
 

Files

file  cmdlinetest.cpp
 Implements classes from cmdlinetest.h.
 
file  cmdlinetest.h
 Declares utilities testing command-line programs.
 
file  conftest.cpp
 Implements routine to check the content of conf files.
 
file  conftest.h
 Declares function to add the content of a conf file to a checker.
 
file  filematchers.cpp
 Implements classes from filematchers.h.
 
file  filematchers.h
 Declares utility classes for testing file contents.
 
file  interactivetest.cpp
 Implements classes from interactivetest.h.
 
file  interactivetest.h
 Provides helper classes for testing interactive prompts.
 
file  loggertest.cpp
 Implements gmx::test::LoggerTestHelper.
 
file  loggertest.h
 Declares gmx::test::LoggerTestHelper.
 
file  mpi_printer.h
 Declares gmx::test::initMPIOutput().
 
file  mpitest.cpp
 Implements functions in mpitest.h.
 
file  mpitest.h
 Helper functions for MPI tests to make thread-MPI look like real MPI.
 
file  refdata.cpp
 Implements classes and functions from refdata.h.
 
file  refdata.h
 Functionality for writing tests that can produce their own reference data.
 
file  refdata_checkers.h
 Declares internal helper classes for the reference data framework to check reference data values of different types.
 
file  refdata_impl.h
 Declares internal data structures for the reference data framework.
 
file  refdata_xml.cpp
 Implements reference data XML persistence.
 
file  refdata_xml.h
 Declares functions for reference data XML persistence.
 
file  setenv.h
 Helper functions to have identical behavior of setenv and unsetenv on Unix and Windows systems.
 
file  simulationdatabase.cpp
 Implements declarations from in simulationdatabase.h.
 
file  simulationdatabase.h
 Functionality for testing whether calls to mdrun produce the same energy and force quantities when they should do so.
 
file  stdiohelper.cpp
 Implements classes in stdiohelper.h.
 
file  stdiohelper.h
 Declares gmx::test::StdioTestHelper.
 
file  stringtest.cpp
 Implements gmx::test::StringTestBase.
 
file  stringtest.h
 Declares gmx::test::StringTestBase.
 
file  testasserts.cpp
 Implements floating-point comparison routines from testasserts.h.
 
file  testasserts.h
 Extra assertions for unit tests.
 
file  testexceptions.h
 Exception classes for errors in tests.
 
file  testfilemanager.cpp
 Implements gmx::test::TestFileManager.
 
file  testfilemanager.h
 Declares gmx::test::TestFileManager.
 
file  testfileredirector.cpp
 Implements classes from testfileredirector.h.
 
file  testfileredirector.h
 Declares generic mock implementations for interfaces in fileredirector.h.
 
file  testinit.cpp
 Implements functions in testinit.h.
 
file  testinit.h
 Functions for initialing GROMACS unit test executables.
 
file  testmatchers.cpp
 Implements floating-point matchers from testmatchers.h for use with Google Mock.
 
file  testmatchers.h
 Extra GoogleMock matchers for unit tests.
 
file  testoptions.cpp
 Implements functions in testoptions.h.
 
file  testoptions.h
 Functions for accessing test command-line options.
 
file  interactivetest.cpp
 Self-tests for interactive test helpers.
 
file  mpitest.cpp
 Tests for infrastructure for running tests under MPI.
 
file  refdata_tests.cpp
 Tests utilities for test reference data.
 
file  testasserts_tests.cpp
 Tests GROMACS-specific test assertions.
 
file  xvgtest_tests.cpp
 Tests utilities for testing xvg files.
 
file  testutils_doc.h
 Dummy header for Testing Utilities (testutils) documentation.
 
file  textblockmatchers.cpp
 Implements classes from textblockmatchers.h.
 
file  textblockmatchers.h
 Declares utility classes for testing multi-line strings against reference data.
 
file  tprfilegenerator.cpp
 Implements helper for generating reusuable TPR files for tests within the same test binary.
 
file  tprfilegenerator.h
 Helper for generating reusuable TPR files for tests within the same test binary.
 
file  unittest_main.cpp
 main() for unit tests that use Testing Utilities (testutils).
 
file  xvgtest.cpp
 Implements routine to check the content of xvg files.
 
file  xvgtest.h
 Declares function to add the content of an xvg file to a checker.
 

Macro Definition Documentation

#define ASSERT_PLAIN (   expr)

Assert for predicates that return AssertionResult and produce a full failure message.

expr should evaluate to AssertionResult, and on failure the message from the result is used as-is, unlike in ASSERT_TRUE().

#define EXPECT_PLAIN (   expr)

Assert for predicates that return AssertionResult and produce a full failure message.

expr should evaluate to AssertionResult, and on failure the message from the result is used as-is, unlike in EXPECT_TRUE().

#define GMX_ASSERT_DEATH_IF_SUPPORTED (   expr,
  msg 
)

Wrapper around ASSERT_DEATH_IF_SUPPORTED gtest macro for thread safe execution.

Makes sure that tests that are supposed to trigger an assertion are only executed in a threadsafe environment when running under e.g. MPI.

#define GMX_EXPECT_DEATH_IF_SUPPORTED (   expr,
  msg 
)

Wrapper around EXPECT_DEATH_IF_SUPPORTED gtest macro for thread safe execution.

Makes sure that tests that are supposed to trigger an assertion are only executed in a threadsafe environment, and not when when running under e.g. MPI.

#define GMX_MPI_TEST (   expectedRankCount)    ASSERT_EQ(expectedRankCount, ::gmx::test::getNumberOfTestMpiRanks())

Declares that this test is an MPI-enabled unit test.

Parameters
[in]expectedRankCountExpected number of ranks for this test. The test will fail if run with unsupported number of ranks.

To write unit tests that run under MPI, you need to do a few things:

  • Put GMX_MPI_TEST() as the first statement in your test body and specify the number of ranks this test expects.
  • Declare your unit test in CMake with gmx_add_mpi_unit_test(). Note that all tests in the binary should fulfill the conditions above, and work with the same number of ranks. TODO: Figure out a mechanism for mixing tests with different rank counts in the same binary (possibly, also MPI and non-MPI tests).

When you do the above, the following will happen:

  • The test will get compiled only if thread-MPI or real MPI is enabled.
  • The test will get executed on the number of ranks specified. If you are using real MPI, the whole test binary is run under MPI and test execution across the processes is synchronized (GMX_MPI_TEST() actually has no effect in this case, the synchronization is handled at a higher level). If you are using thread-MPI, GMX_MPI_TEST() is required and it initializes thread-MPI with the specified number of threads and runs the rest of the test on each of the threads.

You need to be extra careful for variables in the test fixture, if you use one: when run under thread-MPI, these will be shared across all the ranks, while under real MPI, these are naturally different for each process. Local variables in the test body are private to each rank in both cases.

Currently, it is not possible to specify the number of ranks as one, because that will lead to problems with (at least) thread-MPI, but such tests can be written as serial tests anyways.

#define GMX_TEST_NO_THROW_ (   statement,
  fail 
)
Value:
GTEST_AMBIGUOUS_ELSE_BLOCKER_ \
if (::testing::AssertionResult gmx_ar = ::testing::AssertionSuccess()) \
{ \
try \
{ \
GTEST_SUPPRESS_UNREACHABLE_CODE_WARNING_BELOW_(statement); \
} \
catch (std::exception const& ex) \
{ \
gmx_ar << "Expected: " #statement " doesn't throw an exception.\n" \
<< " Actual: it throws.\n" \
<< "Exception details:\n" \
goto GTEST_CONCAT_TOKEN_(gmx_label_testnothrow_, __LINE__); \
} \
catch (...) \
{ \
gmx_ar << "Expected: " #statement " doesn't throw an exception.\n" \
<< " Actual: it throws."; \
goto GTEST_CONCAT_TOKEN_(gmx_label_testnothrow_, __LINE__); \
} \
} \
else \
GTEST_CONCAT_TOKEN_(gmx_label_testnothrow_, __LINE__) : fail(gmx_ar.message())
std::string formatExceptionMessageToString(const std::exception &ex)
Formats an error message for reporting an exception.
Definition: exceptions.cpp:553

Internal implementation macro for exception assertations.

Parameters
statementStatements to execute.
failFunction/macro to call on failure.

The implementation is copied and adjusted from include/gtest/internal/gtest-internal.h in Google Test 1.6.0.

#define GMX_TEST_OPTIONS (   name,
  options 
)

Macro to add additional command-line options for the test binary.

Parameters
nameUnique name for the set of options.
optionsPlaceholder name for an gmx::Options object for adding options.

The macro should be followed by a block that adds the desired command-line options to options using gmx::Options::addOption(). Extensible Handling of Options (options) provides an overview of the options machinery.

name must be unique within the executable to which the options are added. If the macro is within an unnamed namespace, then it is sufficient that it is unique within the file.

Typical usage:

namespace gmx
{
namespace
{
bool g_optionValue = false;
//! \cond
GMX_TEST_OPTIONS(MyTestOptions, options)
{
options->addOption(BooleanOption("flag").store(&g_optionValue)
.description("My description"));
}
//! \endcond
} // namespace
} // namespace gmx

\cond and \endcond statements are necessary around the macro to avoid Doxygen warnings.

One macro invocation per an added option, with more of the implementation details hidden inside the macro, could be nicer. But that requires more elaborate macro machinery, so it is probably not worth the effort and complexity.

#define GMX_TEST_THROW_ (   statement,
  expected_exception,
  fail 
)

Internal implementation macro for exception assertations.

Parameters
statementStatements to execute.
expected_exceptionException type that statement should throw.
failFunction/macro to call on failure.

The implementation is copied and adjusted from include/gtest/internal/gtest-internal.h in Google Test 1.6.0.

Enumeration Type Documentation

Mode of operation for reference data handling.

There should be no need to use this type outside the test utility module.

Enumerator
erefdataCompare 

Compare to existing reference data.

If reference data does not exist, or if the test results differ from those in the reference data, the test fails.

erefdataCreateMissing 

Create missing reference data.

If reference data does not exist for a test, that test behaves as if erefdataUpdateAll had been specified. Tests for which reference data exists, behave like with erefdataCompare.

erefdataUpdateChanged 

Update reference data that does not pass comparison.

Tests utilizing reference data should always pass in this mode unless there is an I/O error.

erefdataUpdateAll 

Update reference data, overwriting old data.

Tests utilizing reference data should always pass in this mode unless there is an I/O error.

Function Documentation

template<typename FloatType >
FloatType anonymous_namespace{testasserts_tests.cpp}::addUlps ( FloatType  value,
int  ulps 
)

Helper to produce floating-point numbers with specified ULP difference.

This doesn't work if the value would change sign.

template<typename FloatType >
static inline ::testing::AssertionResult gmx::test::assertEqualWithinTolerance ( const char *  expr1,
const char *  expr2,
const char *  ,
FloatType  value1,
FloatType  value2,
const FloatingPointTolerance &  tolerance 
)
static

Assertion predicate formatter for comparing two floating-point values.

static FloatingPointTolerance defaultFloatTolerance ( )
related

Returns the default tolerance for comparing single-precision numbers when compared by GROMACS built in either precision mode.

This permits a checker compiled with any GROMACS precision to compare equal or not in the same way.

void gmx::test::finalizeTestUtils ( )

Finalizes the test utilities library.

Does not throw. Terminates the program with a non-zero error code if an error occurs.

This function is automatically called by unittest_main.cpp.

template<typename FloatType >
FloatingPoint<FloatType>::Bits gmx::test::anonymous_namespace{testasserts.cpp}::floatingPointToBiasedInteger ( const FloatingPoint< FloatType > &  value)

Computes biased integer representation for a floating-point value.

This moves the integer representation from a sign-and-magnitude representation to a biased representation where the 0x8000... represents zero, and the order of the integer values matches the order of the floating-point values.

int gmx::test::getNumberOfTestMpiRanks ( )

Returns the number of MPI ranks to use for an MPI test.

For thread-MPI builds, this will return the requested number of ranks even before the thread-MPI threads have been started.

void gmx::test::initMPIOutput ( )

Customizes test output and test failure handling for MPI runs.

Only one rank should report the test result. Errors detected on a subset of ranks need to be reported individually, and as an overall failure.

On non-MPI builds, does nothing.

void gmx::test::initReferenceData ( IOptionsContainer *  options)

Initializes reference data handling.

Adds command-line options to options to set the reference data mode. By default, erefdataCompare is used, but --ref-data create or --ref-data update can be used to change it.

This function is automatically called by initTestUtils().

void gmx::test::initTestOptions ( IOptionsContainer *  options)

Initializes the options from all registered test providers.

Parameters
optionsThe options are added here.

This is called automatically by initTestUtils().

void gmx::test::initTestUtils ( const char *  dataPath,
const char *  tempPath,
bool  usesMpi,
bool  usesHardwareDetection,
int *  argc,
char ***  argv 
)

Initializes the test utilities library.

Does not throw. Terminates the program with a non-zero error code if an error occurs.

This function is automatically called by unittest_main.cpp.

Parameters
[in]dataPathFilepath to input files.
[in]tempPathFilepath to temporary files.
[in]usesMpiIf the test is run with MPI or not.
[in]usesHardwareDetectionIf hardwaredetection is enabled.
[in]argcNumber of cmdline options
[in]argvCmdline options.
static inline ::testing::AssertionResult gmx::test::plainAssertHelper ( const char *  ,
const ::testing::AssertionResult &  expr 
)
static

Helper method for (EXPECT|ASSERT)_PLAIN.

ReferenceDataEntry::EntryPointer gmx::test::readReferenceDataFile ( const std::string &  path)

Loads reference data from an XML file.

Parameters
[in]pathPath to the file from which the data is loaded.
Returns
Root entry for the reference data parsed from the file.
Exceptions
TestExceptionif there is a problem reading the file.
void gmx::test::registerTestOptions ( const char *  name,
TestOptionsProvider *  provider 
)

Registers a test option provider with the test framework.

Parameters
[in]nameName of the options provider (for ordering).
[in]providerThe provider to register.
Exceptions
std::bad_allocif out of memory.
tMPI::system_erroron mutex failures.

Typically not used directly in test code, but through the GMX_TEST_OPTIONS macro.

This gets called from constructors for global variables, so ideally it would not throw to avoid unhandled exceptions. But since this is only test code, it is not worth the effort to try to remove those rare exceptions (mutex failures and out-of-memory from STL).

FloatingPointTolerance relativeToleranceAsFloatingPoint ( double  magnitude,
double  tolerance 
)
related

Creates a tolerance that allows a difference in two compared values that is relative to the given magnitude.

Parameters
[in]magnitudeMagnitude of the numbers the computation operates in.
[in]toleranceRelative tolerance permitted (e.g. 1e-4).

In addition to setting an relative tolerance for both precisions, this sets the absolute tolerance such that values close to zero (in general, smaller than magnitude) do not fail the check if they differ by less than tolerance evaluated at magnitude. This accounts for potential loss of precision for small values, and should be used when accuracy of values much less than magnitude do not matter for correctness.

FloatingPointTolerance relativeToleranceAsPrecisionDependentFloatingPoint ( double  magnitude,
float  singleTolerance,
double  doubleTolerance 
)
related

Creates a tolerance that allows a precision-dependent difference in two compared values that is relative to the given magnitude.

Parameters
[in]magnitudeMagnitude of the numbers the computation operates in.
[in]singleToleranceRelative tolerance permitted (e.g. 1e-4) in single precision.
[in]doubleToleranceRelative tolerance permitted (e.g. 1e-4) in double precision.

In addition to setting an relative tolerance for both precisions, this sets the absolute tolerance such that values close to zero (in general, smaller than magnitude) do not fail the check if they differ by less than tolerance evaluated at magnitude. This accounts for potential loss of precision for small values, and should be used when accuracy of values much less than magnitude do not matter for correctness.

static FloatingPointTolerance relativeToleranceAsPrecisionDependentUlp ( double  magnitude,
uint64_t  singleUlpDiff,
uint64_t  doubleUlpDiff 
)
related

Creates a tolerance that allows a precision-dependent relative difference in a complex computation.

Parameters
[in]magnitudeMagnitude of the numbers the computation operates in.
[in]singleUlpDiffExpected accuracy of single-precision computation (in ULPs).
[in]doubleUlpDiffExpected accuracy of double-precision computation (in ULPs).

This works as relativeToleranceAsUlp(), but allows setting the ULP difference separately for the different precisions. This supports cases where the double-precision calculation can acceptably has a higher ULP difference, but relaxing the single-precision tolerance would lead to an unnecessarily loose test.

static FloatingPointTolerance relativeToleranceAsUlp ( double  magnitude,
uint64_t  ulpDiff 
)
related

Creates a tolerance that allows a relative difference in a complex computation.

Parameters
[in]magnitudeMagnitude of the numbers the computation operates in.
[in]ulpDiffExpected accuracy of the computation (in ULPs).

In addition to setting the ULP tolerance as ulpTolerance(), this sets the absolute tolerance such that values close to zero (in general, smaller than magnitude) do not fail the check if they differ by less than ulpDiff evaluated at magnitude. This accounts for potential loss of precision for small values, and should be used when accuracy of values much less than magnitude do not matter for correctness.

static FloatingPointTolerance ulpTolerance ( uint64_t  ulpDiff)
related

Creates a tolerance that only allows a specified ULP difference.

The tolerance uses the given ULP value for both precisions, i.e., double precision will have much stricter tolerance.

void gmx::test::writeReferenceDataFile ( const std::string &  path,
const ReferenceDataEntry &  root 
)

Saves reference data to an XML file.

Parameters
[in]pathPath to the file to which the data is saved.
[in]rootRoot entry for the reference data to write.
Exceptions
TestExceptionif there is a problem writing the file.