Functions
void	addTestDataPath (const std::string &path)
	Add a path (directory) that `openTestData()` will search for test data files.

pid_t	check_output (int write_pipe, const void const output, const size_t length)

void	dontCreateCoreDumps ()
	Don't create core dumps.

template<typename ACTUAL_STREAM >
void	matchTextData (const std::string &expected_text, ACTUAL_STREAM &actual)
	Same for the previous version, but the first argument is string.

void	matchTextData (const std::string &expected_text, const std::string &actual_text)
	Same for the previous two, but takes strings for both expected and actual data.

template<typename EXPECTED_STREAM , typename ACTUAL_STREAM >
void	matchTextData (EXPECTED_STREAM &expected, ACTUAL_STREAM &actual)
	Line-by-line text comparison.

template<typename EXPECTED_STREAM >
void	matchTextData (EXPECTED_STREAM &expected, const std::string &actual_text)
	Similar to the fully templated version, but takes string for the second (actual) data.

void	matchWireData (const void expected_data, size_t expected_len, const void actual_data, size_t actual_len)

void	matchWireData (const void expected_data, std::size_t expected_len, const void actual_data, std::size_t actual_len)
	Compare two sets of binary data in a google test.

void	openTestData (const char *const datafile, std::ifstream &ifs)
	Open a file specified by 'datafile' using the data paths registered via addTestDataPath().

unsigned char	parentReadState (int fd)
	A helper utility for a simple synchronization with another process.

bool	process_ok (pid_t process)
	Checks that a process terminates correctly.

pid_t	provide_input (int read_pipe, const void input, const size_t length)

int	run_all ()
	Run All Tests.

bool	runningOnValgrind ()
	Check if the program is run in valgrind.

Variables
bool	force_throw_on_new = false
	Switch to enable the use of special operator new.

size_t	throw_size_on_new = 0
	The allocation size that triggers an exception in the special operator new.

Function Documentation

◆ addTestDataPath()

void isc::util::unittests::addTestDataPath ( const string & path )

Add a path (directory) that openTestData() will search for test data files.

Definition at line 31 of file testdata.cc.

◆ check_output()

pid_t isc::util::unittests::check_output	(	int *	write_pipe,
		const void *const	output,
		const size_t	length
	)

Definition at line 95 of file fork.cc.

References isc::util::io::read_data().

Here is the call graph for this function:

◆ dontCreateCoreDumps()

void isc::util::unittests::dontCreateCoreDumps ( )

Don't create core dumps.

This function sets the core size to 0, inhibiting the creation of core dumps. It is meant to be used in testcases where EXPECT_DEATH is used, where processes abort (and create cores in the process). As a new process is forked to run EXPECT_DEATH tests, the rlimits of the parent process that runs the other tests should be unaffected.

Definition at line 21 of file resource.cc.

◆ matchTextData() [1/4]

template<typename ACTUAL_STREAM >

void isc::util::unittests::matchTextData	(	const std::string &	expected_text,
		ACTUAL_STREAM &	actual
	)

Same for the previous version, but the first argument is string.

Definition at line 71 of file textdata.h.

References matchTextData().

Here is the call graph for this function:

◆ matchTextData() [2/4]

void isc::util::unittests::matchTextData	(	const std::string &	expected_text,
		const std::string &	actual_text
	)

Same for the previous two, but takes strings for both expected and actual data.

Definition at line 79 of file textdata.h.

References matchTextData().

Here is the call graph for this function:

◆ matchTextData() [3/4]

template<typename EXPECTED_STREAM , typename ACTUAL_STREAM >

void isc::util::unittests::matchTextData	(	EXPECTED_STREAM &	expected,
		ACTUAL_STREAM &	actual
	)

Line-by-line text comparison.

This templated function takes two standard input streams, extracts strings from them, and compares the two sets of strings line by line.

Definition at line 34 of file textdata.h.

Referenced by matchTextData().

◆ matchTextData() [4/4]

template<typename EXPECTED_STREAM >

void isc::util::unittests::matchTextData	(	EXPECTED_STREAM &	expected,
		const std::string &	actual_text
	)

Similar to the fully templated version, but takes string for the second (actual) data.

Due to the nature of textual data, it will often be the case that test data is given as a string object. This shortcut version helps such cases so that the test code doesn't have to create a string stream with the string data just for testing.

Definition at line 63 of file textdata.h.

References matchTextData().

Here is the call graph for this function:

◆ matchWireData() [1/2]

void isc::util::unittests::matchWireData	(	const void *	expected_data,
		size_t	expected_len,
		const void *	actual_data,
		size_t	actual_len
	)

Definition at line 23 of file wiredata.cc.

◆ matchWireData() [2/2]

void isc::util::unittests::matchWireData	(	const void *	expected_data,
		std::size_t	expected_len,
		const void *	actual_data,
		std::size_t	actual_len
	)

Compare two sets of binary data in a google test.

This method checks if the expected and actual data have the same length and all bytes are the same. If not, it reports the point of mismatch in the google test format.

◆ openTestData()

void isc::util::unittests::openTestData	(	const char *const	datafile,
		std::ifstream &	ifs
	)

Open a file specified by 'datafile' using the data paths registered via addTestDataPath().

On success, ifs will be ready for reading the data stored in 'datafile'. If the data file cannot be open with any of the registered paths, a runtime_error exception will be thrown.

Note: Care should be taken if you want to reuse the same single ifs for multiple input data. Some standard C++ library implementations retain the failure bit if the first stream reaches the end of the first file, and make the second call to ifstream::open() fail. The safest way is to use a different ifstream object for a new call to this function; alternatively make sure you explicitly clear the error bit by calling ifstream::clear() on ifs.

Definition at line 36 of file testdata.cc.

◆ parentReadState()

unsigned char isc::util::unittests::parentReadState ( int fd )

A helper utility for a simple synchronization with another process.

It waits for incoming data on a given file descriptor up to 5 seconds (arbitrary choice), read one byte data, and return it to the caller. On any failure it returns 0xff (255), so the sender process should use a different value to pass.

Definition at line 19 of file interprocess_util.cc.

◆ process_ok()

bool isc::util::unittests::process_ok ( pid_t process )

Checks that a process terminates correctly.

Waits for a process to terminate (with a short timeout, this should be used whan the process is about to terminate) and checks its exit code.

Returns: True if the process terminates with 0, false otherwise.

Parameters

process The ID of process to wait for.

Definition at line 36 of file fork.cc.

◆ provide_input()

pid_t isc::util::unittests::provide_input	(	int *	read_pipe,
		const void *	input,
		const size_t	length
	)

Definition at line 67 of file fork.cc.

References isc::util::io::write_data().

Here is the call graph for this function:

◆ run_all()

int isc::util::unittests::run_all ( )

Run All Tests.

A wrapper for the Google Test RUN_ALL_TESTS() macro, this calls the macro but wraps the call in a try...catch block if the environment variable KEATEST_CATCH_EXCEPTION is defined, and calls the macro directly if not.

The catch block catches exceptions of types isc::Exception and std::exception and prints some information about them to stderr. (In the case of isc::Exception, this includes the file and line number from which the exception was raised.) It then re-throws the exception.

See: https://lists.isc.org/pipermail/bind10-dev/2011-January/001867.html for some context.

Returns: Return value from RUN_ALL_TESTS().

Definition at line 23 of file run_all.cc.

References isc::Exception::getFile(), isc::Exception::getLine(), and isc::Exception::what().

Here is the call graph for this function:

◆ runningOnValgrind()

bool isc::util::unittests::runningOnValgrind ( )

Check if the program is run in valgrind.

This is used to check for valgrind and skip (parts of) tests that fork, such as death tests, and general forking tests, and some threading tests; These tend to cause valgrind to report errors, which would hide other potential valgrind reports.

Returns: true if valgrind headers are available, and valgrind is running, false if the headers are not available, or if valgrind is not running

Definition at line 26 of file check_valgrind.cc.

Variable Documentation

◆ force_throw_on_new

bool isc::util::unittests::force_throw_on_new = false

Switch to enable the use of special operator new.

This is set to false by default.

Definition at line 41 of file newhook.cc.

◆ throw_size_on_new

size_t isc::util::unittests::throw_size_on_new = 0

The allocation size that triggers an exception in the special operator new.

This is the exact size that causes an exception to be thrown; for example, if it is set to 100, an attempt of allocating 100 bytes will result in an exception, but allocation attempt for 101 bytes won't (unless, of course, memory is really exhausted and allocation really fails).

The default value is 0. The value of this variable has no meaning unless the use of the special operator is enabled at build time and via force_throw_on_new.

Definition at line 42 of file newhook.cc.

Functions

Variables

Function Documentation

◆ addTestDataPath()

◆ check_output()

◆ dontCreateCoreDumps()

◆ matchTextData() [1/4]

◆ matchTextData() [2/4]

◆ matchTextData() [3/4]

◆ matchTextData() [4/4]

◆ matchWireData() [1/2]

◆ matchWireData() [2/2]

◆ openTestData()

◆ parentReadState()

◆ process_ok()

◆ provide_input()

◆ run_all()

◆ runningOnValgrind()

Variable Documentation

◆ force_throw_on_new

◆ throw_size_on_new