#include <testutils/refdata.h>

Description

Handles comparison to test reference data.

Every check*() method takes an id string as the last parameter. This id is used to uniquely identify the value in the reference data, and it makes the output XML more human-friendly and more robust to errors. The id can be NULL; in this case, multiple elements with no id are created, and they will be matched in the same order as in which they are created. The checkCompound() method can be used to create a set of reference values grouped together. In this case, all check*() calls using the returned child TestReferenceChecker object will create the reference data within this group, and the ids only need to be unique within the compound. Compounds can be nested.

For usage example, see TestReferenceData.

Copies of this class behave have independent internal state.

Classes
class	Impl
	Private implementation class for TestReferenceChecker. More...

Public Member Functions
	TestReferenceChecker ()
	Creates a checker that cannot be used for checking. More...

	TestReferenceChecker (const TestReferenceChecker &other)
	Creates a deep copy of the other checker.

	TestReferenceChecker (TestReferenceChecker &&other)
	Moves the checker.

TestReferenceChecker &	operator= (const TestReferenceChecker &)=delete
	Prevents implicit copying during assignment.

TestReferenceChecker &	operator= (TestReferenceChecker &&other)
	Assigns a test reference checker.

bool	isValid () const
	Returns whether the checker is initialized.

	operator bool () const
	Allows testing whether the checker is initialized directly with if.

void	setDefaultTolerance (const FloatingPointTolerance &tolerance)
	Sets the tolerance for floating-point comparisons. More...

void	checkUnusedEntries ()
	Checks that all reference values have been compared against. More...

bool	checkPresent (bool bPresent, const char *id)
	Checks whether a data item is present. More...

TestReferenceChecker	checkCompound (const char type, const char id)
	Initializes comparison of a group of related data items. More...

void	checkBoolean (bool value, const char *id)
	Check a single boolean value.

void	checkString (const char value, const char id)
	Check a single string value.

void	checkString (const std::string &value, const char *id)
	Check a single string value.

void	checkTextBlock (const std::string &value, const char *id)
	Check a multi-line string value. More...

void	checkUChar (unsigned char value, const char *id)
	Check a single unsigned char value.

void	checkInteger (int value, const char *id)
	Check a single integer value.

void	checkInt64 (gmx_int64_t value, const char *id)
	Check a single int64 value.

void	checkUInt64 (gmx_uint64_t value, const char *id)
	Check a single uint64 value.

void	checkFloat (float value, const char *id)
	Check a single single-precision floating point value.

void	checkDouble (double value, const char *id)
	Check a single double-precision floating point value.

void	checkReal (float value, const char *id)
	Check a single floating point value.

void	checkReal (double value, const char *id)
	Check a single floating point value.

void	checkVector (const int value[3], const char *id)
	Check a vector of three integer values.

void	checkVector (const float value[3], const char *id)
	Check a vector of three single-precision floating point values.

void	checkVector (const double value[3], const char *id)
	Check a vector of three double-precision floating point values.

void	checkRealFromString (const std::string &value, const char *id)
	Check a single floating-point value from a string.

void	checkVariant (const Variant &value, const char *id)
	Checks a variant value that contains a supported simple type.

void	checkKeyValueTreeObject (const KeyValueTreeObject &tree, const char *id)
	Checks a key-value tree rooted at a object.

void	checkKeyValueTreeValue (const KeyValueTreeValue &value, const char *id)
	Checks a generic key-value tree value.

template<class Iterator >
void	checkSequence (Iterator begin, Iterator end, const char *id)
	Generic method to check a sequence of simple values. More...

template<class Iterator , class ItemChecker >
void	checkSequence (Iterator begin, Iterator end, const char *id, ItemChecker checkItem)
	Generic method to check a sequence of custom values. More...

template<typename T >
void	checkSequenceArray (size_t length, const T values, const char id)
	Check an array of values. More...

void	checkEmptySequence (const char *id)
	Convenience method for checking that a sequence is empty. More...

TestReferenceChecker	checkSequenceCompound (const char *id, size_t length)
	Initializes a compound for a sequence of items. More...

Methods to read values from reference data
These methods assume that a value with the given `id` has already been created in the test with `check*()` methods, and that it has the correct type. Currently, these methods do not work correctly if the reference data file does not exist, so a test using them may fail with exceptions before the reference data has been generated.
unsigned char	readUChar (const char *id)
	Reads an unsigned char value.

int	readInteger (const char *id)
	Reads an integer value.

gmx_int64_t	readInt64 (const char *id)
	Reads a 64-bit integer value.

float	readFloat (const char *id)
	Reads a float value.

double	readDouble (const char *id)
	Reads a double value.

std::string	readString (const char *id)
	Reads a string value.

Overloaded versions of simple checker methods
These methods provide overloads under a single name for all the methods checkBoolean(), checkString(), checkReal() and checkVector(). They are provided mainly to allow template implementations (such as checkSequence()). Typically callers should use the individually named versions for greater clarity.
void	checkValue (bool value, const char *id)
	Check a single boolean value.

void	checkValue (const char value, const char id)
	Check a single string value.

void	checkValue (const std::string &value, const char *id)
	Check a single string value.

void	checkValue (int value, const char *id)
	Check a single integer value.

void	checkValue (gmx_int64_t value, const char *id)
	Check a single integer value.

void	checkValue (gmx_uint64_t value, const char *id)
	Check a single integer value.

void	checkValue (float value, const char *id)
	Check a single single-precision floating point value.

void	checkValue (double value, const char *id)
	Check a single double-precision floating point value.

void	checkValue (const int value[3], const char *id)
	Check a vector of three integer values.

void	checkValue (const float value[3], const char *id)
	Check a vector of three single-precision floating point values.

void	checkValue (const double value[3], const char *id)
	Check a vector of three double-precision floating point values.

void	checkValue (const KeyValueTreeValue &value, const char *id)
	Check a generic key-value tree value.

Friends
class	TestReferenceData
	Needed to expose the constructor only to TestReferenceData.

Constructor & Destructor Documentation

gmx::test::TestReferenceChecker::TestReferenceChecker ( )

Creates a checker that cannot be used for checking.

Attempting to call the check methods generates an assert. It is possible to check whether the checker is initialized by calling isValid(). This constructor exists to allow declaring checker variables that will receive their value later without resorting to dynamic allocation.

Member Function Documentation

TestReferenceChecker gmx::test::TestReferenceChecker::checkCompound	(	const char *	type,
		const char *	id
	)

Initializes comparison of a group of related data items.

Parameters

[in]	type	Informational type for the compound.
[in]	id	Unique identifier for the compound among its siblings.

Returns: Checker to use for comparison within the compound.

All checks performed with the returned checker only need to have unique ids within the compound, not globally.

Compound structures can be nested.

void gmx::test::TestReferenceChecker::checkEmptySequence ( const char * id )

Convenience method for checking that a sequence is empty.

Parameters

[in] id Unique identifier for the sequence among its siblings.

This method provides a convenient solution for a case where there is implicitly a sequence to be checked, but there is no pointer available to the values since the sequence is empty. Since this method does not require the type of the values, it can be used in such cases easily.

bool gmx::test::TestReferenceChecker::checkPresent	(	bool	bPresent,
		const char *	id
	)

Checks whether a data item is present.

Parameters

[in]	bPresent	Whether to check for presence or absence.
[in]	id	Unique identifier of the item to check.

Returns: true if bPresent was true and the data item was found.

If bPresent is true, checks that a data item with id is present, otherwise checks that the data item is absent. If the check fails, a non-fatal Google Test assertion is generated.

If reference data is being written, the check always succeeds and the return value is bPresent.

The main use of this method is to assign meaning for missing reference data. Example use:

  if (checker.checkPresent(bHaveVelocities, "Velocities"))
  {
      // <check the velocities>
  }
* 

template<class Iterator >

void gmx::test::TestReferenceChecker::checkSequence	(	Iterator	begin,
		Iterator	end,
		const char *	id
	)

inline

Generic method to check a sequence of simple values.

Template Parameters

Iterator Input iterator that allows multiple (two) passes. Value type must be one of those accepted by checkValue(), or implicitly convertible to one.

Parameters

[in]	begin	Iterator to the start of the range to check.
[in]	end	Iterator to the end of the range to check.
[in]	id	Unique identifier for the sequence among its siblings.

template<class Iterator , class ItemChecker >

void gmx::test::TestReferenceChecker::checkSequence	(	Iterator	begin,
		Iterator	end,
		const char *	id,
		ItemChecker	checkItem
	)

inline

Generic method to check a sequence of custom values.

Template Parameters

Iterator	Input iterator that allows multiple (two) passes.
ItemChecker	Functor to check an individual value. Signature void(TestReferenceChecker *, const T &), where T is the value type of `Iterator`.

Parameters

[in]	begin	Iterator to the start of the range to check.
[in]	end	Iterator to the end of the range to check.
[in]	id	Unique identifier for the sequence among its siblings.
[in]	checkItem	Functor to check an individual item.

This method creates a compound checker compound within which all values of the sequence are checked. Calls checkItem(&compound, *i) with that compound for each iterator i in the range [begin, end). checkItem should use the various check methods in the passed checker to check each value.

This method can be used to check a sequence made of compound types. Typically checkItem will create a compound within the passed checker to check different aspects of the value that was passed to it. Either NULL or a unique identifier string must be used for the id value of that compound.

template<typename T >

void gmx::test::TestReferenceChecker::checkSequenceArray	(	size_t	length,
		const T *	values,
		const char *	id
	)

inline

Check an array of values.

Template Parameters

T	Type of values to check. Should be one of those accepted by checkValue(), or implicitly convertible to one.

Parameters

[in]	length	Number of values to check.
[in]	values	Pointer to the first value to check.
[in]	id	Unique identifier for the sequence among its siblings.

This is a convenience method that delegates all work to checkSequence().

TestReferenceChecker gmx::test::TestReferenceChecker::checkSequenceCompound	(	const char *	id,
		size_t	length
	)

Initializes a compound for a sequence of items.

Parameters

[in]	id	Unique identifier for the sequence among its siblings.
[in]	length	Number of items that will be in the sequence.

Returns: Checker to use for comparison within the sequence.

This method can be used to check custom sequences where checkSequence() is not appropriate.

void gmx::test::TestReferenceChecker::checkTextBlock	(	const std::string &	value,
		const char *	id
	)

Check a multi-line string value.

This method works as checkString(), but should be used for long strings that may contain, e.g., newlines. Typically used to check formatted output, and attempts to make the output XML such that it is easier to edit by hand to set the desired output formatting.

void gmx::test::TestReferenceChecker::checkUnusedEntries ( )

Checks that all reference values have been compared against.

All values under the compound represented by this checker are checked, and a non-fatal Google Test assertion is produced if some values have not been used.

If not called explicitly, the same check will be done for all reference data values when the test ends.

This method also marks the values used, so that subsequent checks (including the check at the end of the test) will not produce another assertion about the same values.

void gmx::test::TestReferenceChecker::setDefaultTolerance ( const FloatingPointTolerance & tolerance )

Sets the tolerance for floating-point comparisons.

All following floating-point comparisons using this checker will use the new tolerance. Child checkers created with checkCompound() will inherit the tolerance from their parent checker at the time checkCompound() is called.

Does not throw.

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

src/testutils/refdata.h
src/testutils/refdata.cpp

Description

Classes

Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation