Gromacs  2024.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions
gmx::test::TestReferenceData Class Reference

#include <testutils/include/testutils/refdata.h>

Description

Handles creation of and comparison to test reference data.

See Using reference data in C++ tests for an overview of the functionality.

This class provides functionality to use the same code to generate reference data and then on later runs compare the results of the code against that reference. The mode in which the class operates (writing reference data or comparing against existing data) is set using a command-line option that is automatically managed when using the testutils module to implement tests. Tests only need to create an instance of TestReferenceData, obtain a TestReferenceChecker using the rootChecker() method and use the various check*() methods in TestReferenceChecker to indicate values to check. If the test is running in reference data creation mode, it will produce an XML file with the values recorder. In comparison mode, it will read that same XML file and produce a Google Test non-fatal assertion for every discrepancy it detects with the reference data (including missing reference data file or individual item). Exceptions derived from TestException are thrown for I/O errors and syntax errors in the reference data.

Simple example (using Google Test):

int functionToTest(int param);
namespace gmx
{
namespace test
{
TEST(MyTest, SimpleTest)
{
TestReferenceChecker checker(data.rootChecker());
checker.checkInteger(functionToTest(3), "ValueWith3");
checker.checkInteger(functionToTest(5), "ValueWith5");
TestReferenceChecker compound(
checker.checkCompound("CustomCompound", "Item"));
compound.checkInteger(function2ToTest(3), "ValueWith3");
compound.checkInteger(function2ToTest(5), "ValueWith5");
checker.checkInteger(functionToTest(4), "ValueWith4");
checker.checkVector(functionProducingRVec(), "Describe The RVec");
}
} // namespace test
} // namespace gmx
*

If rootChecker() is never called, no comparison is done (i.e., missing reference data file is not reported as an error, nor is empty reference data file created in write mode).

For floating-point comparisons, the reference data should be generated in double precision (currently, no warning is provided even if this is not the case, but the double precision tests will then very likely fail).

Public Member Functions

 TestReferenceData ()
 Initializes the reference data in the global mode.
 
 TestReferenceData (std::string testNameOverride)
 Initializes the reference data in the global mode while providing the test name. More...
 
 TestReferenceData (ReferenceDataMode mode)
 Initializes the reference data in a specific mode. More...
 
 ~TestReferenceData ()
 Frees reference data structures. More...
 
TestReferenceChecker rootChecker ()
 Returns a root-level checker object for comparisons. More...
 

Constructor & Destructor Documentation

gmx::test::TestReferenceData::TestReferenceData ( std::string  testNameOverride)
explicit

Initializes the reference data in the global mode while providing the test name.

Providing a name for the test, rather than using the default name generated by GoogleTest, is useful when many tests should share common reference data because e.g. they are value-parameterized over multiple equivalent implementations or run modes. The name should include a filename suffix e.g. .xml and refers to a file that will be found in the refdata subdirectory for the test case.

gmx::test::TestReferenceData::TestReferenceData ( ReferenceDataMode  mode)
explicit

Initializes the reference data in a specific mode.

This function is only useful for self-testing the reference data framework. As such, it also puts the framework in a state where it logs additional internal information for failures to help diagnosing problems in the framework, and stores the reference data in a temporary directory instead of the source tree. The default constructor should be used in tests utilizing this class.

gmx::test::TestReferenceData::~TestReferenceData ( )

Frees reference data structures.

The reference data is written out if necessary automatically when the test finishes.

Member Function Documentation

TestReferenceChecker gmx::test::TestReferenceData::rootChecker ( )

Returns a root-level checker object for comparisons.

Each call returns an independent instance.


The documentation for this class was generated from the following files: