Testsuite Utilities (v8::testing)

Detailed Description

Unit testing toolkit for waLBerla.

This toolkit of test utilities is designed to facilitate unit testing of the waLBerla framework.

See also Testing in the V8 core contributors guide.

Creating a Test Executable

Tests are grouped into test executables. We thematically group as many tests as sensible into a single executable to accelerate compilation times. Test executables follow the naming scheme TestX.cpp. To register a test executable with CMake, use the waLBerla_add_test_executable function:

waLBerla_add_test_executable( TestX TestX.cpp )

Registering Tests

Every test executable must include the following scaffolding, where the tests are registered with a TestsRunner instance:

#include "walberla/v8/Testing.hpp"
 
int main(int argc, char** argv) {
   walberla::mpi::Environment env{ argc, argv };
 
   return walberla::v8::testing::TestsRunner({
        // TEST FUNCTIONS
        {"MyTest1", &myTest1},
        {"MyTest2", &myTest2},
        // ...
   }).run(argc, argv);
}

The individual tests (MyTest1, MyTest2, ...) are zero-argument void functions. To automatically run the tests, they must further be registered with CTest in the CMakeLists.txt, using walberla_v8_add_tests:

walberla_v8_add_tests( TestX IDS MyTest1 MyTest2 ... )

Here, TestX is the name of the test application, the IDS are the test names as passed to the TestsRunner.

Writing Tests

Tests should be written using the assertion functions from this module, listed below.

Classes
class	walberla::v8::testing::TestsRunner
	Primary test orchestrator. More...
class	walberla::v8::testing::with_tolerance
	Floating-point near-equality assertions with given tolerances. More...

Functions
std::filesystem::path	walberla::v8::testing::tmp_dir ()
	Create and obtain a unique temporary directory.
void	walberla::v8::testing::assert_true (bool cond, const std::source_location loc=std::source_location::current())
	Check if the given boolean condition is true.
void	walberla::v8::testing::assert_false (bool cond, const std::source_location loc=std::source_location::current())
	Check if the given boolean condition is false.
template<typename TException>
void	walberla::v8::testing::throws (const std::function< void() > &func, const std::source_location loc=std::source_location::current())
	Check if the given callback function raises an expected exception type.
template<std::equality_comparable T>
void	walberla::v8::testing::assert_equal (const T &actual, const T &desired, const std::source_location loc=std::source_location::current())
	Check if two values are equal.
template<std::equality_comparable T>
void	walberla::v8::testing::assert_inequal (const T &left, const T &right, const std::source_location loc=std::source_location::current())
	Check if two values are inequal.
template<std::totally_ordered T>
void	walberla::v8::testing::assert_less (const T &left, const T &right, const std::source_location loc=std::source_location::current())
	Check if one value is less than another.
template<std::totally_ordered T>
void	walberla::v8::testing::assert_greater (const T &left, const T &right, const std::source_location loc=std::source_location::current())
	Check if one value is greater than another.
template<std::totally_ordered T>
void	walberla::v8::testing::assert_less_equal (const T &left, const T &right, const std::source_location loc=std::source_location::current())
	Check if one value is less or equal to another.
template<std::totally_ordered T>
void	walberla::v8::testing::assert_greater_equal (const T &left, const T &right, const std::source_location loc=std::source_location::current())
	Check if one value is greater or equal to another.
template<std::ranges::range R1, std::ranges::range R2>
void	walberla::v8::testing::assert_range_equal (const R1 &actual, const R2 &desired, const std::source_location loc=std::source_location::current())
	Check if two ranges have identical elements.
template<std::ranges::range R1>
void	walberla::v8::testing::assert_range_equal (const R1 &actual, const std::ranges::range_value_t< R1 > &desired, const std::source_location loc=std::source_location::current())
	Check if all elements of a range are equal to a desired value.

Function Documentation

assert_equal()

template<std::equality_comparable T>

void walberla::v8::testing::assert_equal	(	const T &	actual,
		const T &	desired,
		const std::source_location	loc = std::source_location::current() )

Check if two values are equal.

Note

For floating-point comparisons, use assert_close instead.

assert_false()

void walberla::v8::testing::assert_false ( bool cond, const std::source_location loc = std::source_location::current() )

inline

Check if the given boolean condition is false.

assert_greater()

template<std::totally_ordered T>

void walberla::v8::testing::assert_greater	(	const T &	left,
		const T &	right,
		const std::source_location	loc = std::source_location::current() )

Check if one value is greater than another.

assert_greater_equal()

template<std::totally_ordered T>

void walberla::v8::testing::assert_greater_equal	(	const T &	left,
		const T &	right,
		const std::source_location	loc = std::source_location::current() )

Check if one value is greater or equal to another.

assert_inequal()

template<std::equality_comparable T>

void walberla::v8::testing::assert_inequal	(	const T &	left,
		const T &	right,
		const std::source_location	loc = std::source_location::current() )

Check if two values are inequal.

assert_less()

template<std::totally_ordered T>

void walberla::v8::testing::assert_less	(	const T &	left,
		const T &	right,
		const std::source_location	loc = std::source_location::current() )

Check if one value is less than another.

assert_less_equal()

template<std::totally_ordered T>

void walberla::v8::testing::assert_less_equal	(	const T &	left,
		const T &	right,
		const std::source_location	loc = std::source_location::current() )

Check if one value is less or equal to another.

assert_range_equal() [1/2]

template<std::ranges::range R1, std::ranges::range R2>

void walberla::v8::testing::assert_range_equal	(	const R1 &	actual,
		const R2 &	desired,
		const std::source_location	loc = std::source_location::current() )

Check if two ranges have identical elements.

assert_range_equal() [2/2]

template<std::ranges::range R1>

void walberla::v8::testing::assert_range_equal	(	const R1 &	actual,
		const std::ranges::range_value_t< R1 > &	desired,
		const std::source_location	loc = std::source_location::current() )

Check if all elements of a range are equal to a desired value.

Note

If the range is empty, this assertion will succeed.

assert_true()

void walberla::v8::testing::assert_true ( bool cond, const std::source_location loc = std::source_location::current() )

inline

Check if the given boolean condition is true.

throws()

template<typename TException>

void walberla::v8::testing::throws	(	const std::function< void() > &	func,
		const std::source_location	loc = std::source_location::current() )

Check if the given callback function raises an expected exception type.

Example:

throws< std::invalid_argument >([&](){
   // code that should throw ...
});

tmp_dir()

std::filesystem::path walberla::v8::testing::tmp_dir ( )

inline

Create and obtain a unique temporary directory.

Note

To override the location where temporary directories are placed, set the TMPDIR environment variable. See also std::filesystem::temp_directory_path