Default test driver include file. More...

#include <string>
#include <map>
#include <vector>
#include <iostream>
#include <fstream>
#include <cstdio>
#include <limits>
#include <basis/basis.h>
#include "testdriver.hxx"

Include dependency graph for testdriver.h:

Go to the source code of this file.

Classes
class	BinaryDiffVisitor
	Visitor used to handle –diff option. More...

class	CompareVisitor
	Visitor used to handle –compare option. More...

class	LineDiffVisitor
	Visitor used to handle –diff-lines option. More...

struct	RegressionTest
	Structure holding arguments to regression test options and currently set tolerances to be used for the regression test. More...

Macros
#define	_BASIS_TESTDRIVER_H

Enumerations
enum	TestMethod { METHOD_UNKNOWN, COMPARE_IMAGES, BINARY_DIFF, DIFF_LINES }

Functions
MultiStringArg	add_before_env ("", "add-before-env", "Add an environment variable named <name> with the given value." " The seperator used is the default one on the system.", false, "<name> <value>", 2)

MultiStringArg	add_before_env_with_sep ("", "add-before-env-with-sep", "Add an environment variable named <name> with the given value.", false, "<name> <value> <sep>", 3)

MultiStringArg	add_before_libpath ("", "add-before-libpath", "Add a path to the library path environment. This option takes" " care of choosing the right environment variable for your system.", false, "<dir>")

int	binary_diff (const char testfile, const char baseline)
	Compare two files byte by byte. More...

SwitchArg	clean_cwd_after_test ("", "clean-cwd-after", "Request the removal of all files and directories from the current" " working directory after the successful execution of the test." " This option is in particular useful if the test writes any results" " to the current working directory.", false)

SwitchArg	clean_cwd_before_test ("", "clean-cwd-before", "Request the removal of all files and directories from the current" " working directory before the execution of the test. This option is" " in particular useful if the test writes any results to the current" " working directory.", false)

MultiStringArg	compare ("", "compare", "Compare the <test> image to the <baseline> image using the" " current tolerances. If the test image should be compared to" " to more than one baseline image, specify the file name of" " the main baseline image and name the other baseline images" " similarly with only a numerical suffix appended to the" " basename of the image file path using a dot (.) as separator." " For example, name your baseline images baseline.nii," " baseline.1.nii, baseline.2.nii,..., and specify baseline.nii" " second argument value.", false, "<test> <baseline>", 2, false, &compare_visitor)

MultiStringArg	diff ("", "diff", "Compare the <test> file to the <baseline> file byte by byte." " Can by used to compare any files including text files." " For images, the --compare option should be used instead.", false, "<test> <baseline>", 2, false, &diff_visitor)

MultiStringArg	diff_lines ("", "diff-lines", "Compare the <test> file to the <baseline> file line by line." " Can by used to compare text files. The current --max-number-of-differences" " setting determines the number of lines which may differ between the files." " For binary files, consider the --diff option instead.", false, "<test> <baseline>", 2, false, &diff_lines_visitor)

SwitchArg	full_output ("", "full-output", "Causes the full output of the test to be passed to CDash.", false)

vector< string >	get_baseline_filenames (string filename_template)
	Generate list of names of baseline files from a given template filename. More...

int	image_regression_test (const char imagefile, const char baseline, double intensity_tolerance=2.0, unsigned int max_number_of_differences=0, unsigned int tolerance_radius=0, bool orientation_insensitive=false, int report=0)
	Compare output image to baseline image. More...

DoubleArg	intensity_tolerance ("", "intensity-tolerance", "The accepted maximum difference between image intensities" " to use for the following regression tests." " (default: 2.0)", false, 2.0, "<float>", true)

UIntArg	max_number_of_differences ("", "max-number-of-differences", "When comparing images specified with the following --compare option(s)," " allow the given number of image elements to differ.", false, 0, "<n>", true)

UIntArg	max_number_of_threads ("", "max-number-of-threads", "Use at most <n> threads. Set explicitly to n=1 to disable" " multi-threading. Note that the test itself still may use" " more threads, but the regression tests will not.", false, 0, "<n>")

SwitchArg	orientation_insensitive ("", "orientation-insensitive", "Allow the test and baseline images to have different orientation." " When this option is given, the orientation of both images is made" " identical before they are compared. It is suitable if the test" " and baseline images are simply stored with different orientation," " but with proper orientation information in the file header.")

StringArg	redirect_output ("", "redirect-output", "Redirects the test output to the specified file.", false, "", "<file>")

PositionalArgs	testcmd ("testcmd", "The name of the test to run and optional arguments." " Displays a list of available tests if this argument is omitted" " and waits for the user to input the number of the test to run." " Exist with error if an invalid test was specified." " Note that if the -- option is not given before the test name," " labeled arguments following the test name will be considered" " to be options of the test driver if known by the test driver." " Otherwise, if the option is unknown to the test driver or the" " -- option has been given before the test name, the remaining" " arguments are passed on to the test.", false, "", "[--] [<test name> [<arg>...]]")

void	testdriversetup (int argc, char *argv[])
	Parse command-line arguments and initialize test driver. More...

int	text_diff_lines (const char testfile, const char baseline, unsigned int max_number_of_differences=0)
	Compare two text files line by line. More...

UIntArg	tolerance_radius ("", "tolerance-radius", "At most one image element in the neighborhood specified by the" " given radius has to fulfill the criteria of the following" " regression tests", false, 0, "<int>", true)

MultiSwitchArg	verbose ("v", "verbose", "Increase verbosity of output messages.", false)

Variables
const unsigned int	BASIS_MAX_TEST_IMAGE_DIMENSION = 6
	Maximum dimension of images used for testing. More...

CompareVisitor	compare_visitor

LineDiffVisitor	diff_lines_visitor

BinaryDiffVisitor	diff_visitor

vector< RegressionTest >	regression_tests
	Container storing added regression tests. More...

Detailed Description

Default test driver include file.

This file is specified as INCLUDE argument to the create_test_sourcelist() command of CMake which generates the code of the test driver. Such test driver is used, in particular, to run a test which generates an output image. The resulting image can then be compared by the test driver to one or more baseline images. Note the difference to plain non-image processing based unit tests. These shall make use of the unit testing frameworks included with BASIS instead (see test.h for a C++ unit testing framework).

This file in particular declares the functions which are used to parse the command-line arguments of the test driver and those which are used by the code fragments defined in the files testdriver-before-test.inc and testdriver-after-test.inc.

Currently available test driver implementations included by this file are:

Definition in file testdriver.h.

Macro Definition Documentation

§ _BASIS_TESTDRIVER_H

#define _BASIS_TESTDRIVER_H

Definition at line 63 of file testdriver.h.

Enumeration Type Documentation

§ TestMethod

enum TestMethod

Enumerator
METHOD_UNKNOWN
COMPARE_IMAGES
BINARY_DIFF
DIFF_LINES

Definition at line 111 of file testdriver.h.

Function Documentation

§ add_before_env()

MultiStringArg add_before_env	(	""	,
		"add-before-env"	,
		"Add an environment variable named <name> with the given value." " The seperator used is the default one on the system."	,
		false	,
		"<name> <value>"	,
		2
	)

§ add_before_env_with_sep()

MultiStringArg add_before_env_with_sep	(	""	,
		"add-before-env-with-sep"	,
		"Add an environment variable named <name> with the given value."	,
		false	,
		"<name> <value> <sep>"	,
		3
	)

§ add_before_libpath()

MultiStringArg add_before_libpath	(	""	,
		"add-before-libpath"	,
		"Add a path to the library path environment. This option takes" " care of choosing the right environment variable for your system."	,
		false	,
		"<dir>"
	)

§ binary_diff()

int binary_diff	(	const char *	testfile,
		const char *	baseline
	)

Compare two files byte by byte.

Parameters

[in]	testfile	File generated by test.
[in]	baseline	Baseline file.

Return values

-1	if the test file could not be read
-2	if the baseline file could not be read
0	if the two files are identical
1	if the two files differ

Definition at line 189 of file testdriver.hxx.

§ clean_cwd_after_test()

SwitchArg clean_cwd_after_test	(	""	,
		"clean-cwd-after"	,
		"Request the removal of all files and directories from the current" " working directory after the successful execution of the test." " This option is in particular useful if the test writes any results" " to the current working directory."	,
		false
	)

§ clean_cwd_before_test()

SwitchArg clean_cwd_before_test	(	""	,
		"clean-cwd-before"	,
		"Request the removal of all files and directories from the current" " working directory before the execution of the test. This option is" " in particular useful if the test writes any results to the current" " working directory."	,
		false
	)

§ compare()

MultiStringArg compare	(	""	,
		"compare"	,
		"Compare the <test> image to the <baseline> image using the" " current tolerances. If the test image should be compared to" " to more than one baseline	image,
		specify the file name of" " the main baseline image and name the other baseline images" " similarly with only a numerical suffix appended to the" " basename of the image file path using a dot(.) as separator." " For	example,
		name your baseline images baseline.	nii,
		" " baseline.1.	nii,
		baseline.2.	nii,
			...,
		and specify baseline.nii" " second argument value."	,
		false	,
		"<test> <baseline>"	,
		2	,
		false	,
		&	compare_visitor
	)

§ diff()

MultiStringArg diff	(	""	,
		"diff"	,
		"Compare the <test> file to the <baseline> file byte by byte." " Can by used to compare any files including text files." " For	images,
		the --compare option should be used instead."	,
		false	,
		"<test> <baseline>"	,
		2	,
		false	,
		&	diff_visitor
	)

§ diff_lines()

MultiStringArg diff_lines	(	""	,
		"diff-lines"	,
		"Compare the <test> file to the <baseline> file line by line." " Can by used to compare text files. The current --max-number-of-differences" " setting determines the number of lines which may differ between the files." " For binary	files,
		consider the --diff option instead."	,
		false	,
		"<test> <baseline>"	,
		2	,
		false	,
		&	diff_lines_visitor
	)

§ full_output()

SwitchArg full_output	(	""	,
		"full-output"	,
		"Causes the full output of the test to be passed to CDash."	,
		false
	)

§ get_baseline_filenames()

vector<string> get_baseline_filenames ( string filename_template )

Generate list of names of baseline files from a given template filename.

The list of baseline file names is generated from the template filename using the following algorithm:

Strip the file name suffix.
Append a suffix containing of a dot (.) and a digit, i.e., .x
Append the original file name suffix. It the file exists, increment x and continue.

Additionally, if a file filename_template exists, it is the first element in the resulting list.

Parameters

[in] filename_template File path template.

Returns: List of baseline filenames or empty list if no such files exist.

§ image_regression_test()

int image_regression_test	(	const char *	imagefile,
		const char *	baseline,
		double	intensity_tolerance = `2.0`,
		unsigned int	max_number_of_differences = `0`,
		unsigned int	tolerance_radius = `0`,
		bool	orientation_insensitive = `false`,
		int	report = `0`
	)

Compare output image to baseline image.

This function compares a given image to a baseline image and returns a regression test result depending on how well the output image matches the baseline image given the provided tolerance arguments.

Parameters

[in]	imagefile	Output image file of test run.
[in]	baseline	Baseline image file.
[in]	intensity_tolerance	Maximum tolerable intensity difference.
[in]	max_number_of_differences	Maximum number of differing pixels.
[in]	tolerance_radius	Tolerance radius.
[in]	orientation_insensitive	Change orientation of both images to a common coordinate orientation before comparing them.
[in]	report	Level of test report to generate. If zero, no report is generated. If greater than zero, a report is generated. Similar to the verbosity of a program, is this parameter used to set the verbosity of the report. Most implementations yet only either generate a (full) report or none.

Returns: Number of voxels with a difference above the set intensity_tolerance.

Definition at line 299 of file testdriver.hxx.

§ intensity_tolerance()

DoubleArg intensity_tolerance	(	""	,
		"intensity-tolerance"	,
		"The accepted maximum difference between image intensities" " to use for the following regression tests." " (default: 2.0)"	,
		false	,
		2.	0,
		"<float>"	,
		true
	)

§ max_number_of_differences()

UIntArg max_number_of_differences	(	""	,
		"max-number-of-differences"	,
		"When comparing images specified with the following --compare	options,
		" " allow the given number of image elements to differ."	,
		false	,
		0	,
		"<n>"	,
		true
	)

§ max_number_of_threads()

UIntArg max_number_of_threads	(	""	,
		"max-number-of-threads"	,
		"Use at most <n> threads. Set explicitly to	n = `1 to disable" " multi-threading. Note that the test itself still may use" " more threads`,
		but the regression tests will not."	,
		false	,
		0	,
		"<n>"
	)

§ orientation_insensitive()

SwitchArg orientation_insensitive	(	""	,
		"orientation-insensitive"	,
		"Allow the test and baseline images to have different orientation." " When this option is	given,
		the orientation of both images is made" " identical before they are compared. It is suitable if the test" " and baseline images are simply stored with different	orientation,
		" " but with proper orientation information in the file header."
	)

§ redirect_output()

StringArg redirect_output	(	""	,
		"redirect-output"	,
		"Redirects the test output to the specified file."	,
		false	,
		""	,
		"<file>"
	)

§ testcmd()

PositionalArgs testcmd	(	"testcmd"	,
		"The name of the test to run and optional arguments." " Displays a list of available tests if this argument is omitted" " and waits for the user to input the number of the test to run." " Exist with error if an invalid test was specified." " Note that if the -- option is not given before the test	name,
		" " labeled arguments following the test name will be considered" " to be options of the test driver if known by the test driver." "	Otherwise,
		if the option is unknown to the test driver or the" " -- option has been given before the test	name,
		the remaining" " arguments are passed on to the test."	,
		false	,
		""	,
		" ]"	[--][< test name > [< arg >...]
	)

§ testdriversetup()

void testdriversetup	(	int *	argc,
		char **	argv[]
	)

Parse command-line arguments and initialize test driver.

Parameters

[in]	argc	Number of arguments.
[in]	argv	Command-line arguments.

Definition at line 42 of file testdriver.hxx.

§ text_diff_lines()

int text_diff_lines	(	const char *	testfile,
		const char *	baseline,
		unsigned int	max_number_of_differences = `0`
	)

Compare two text files line by line.

Parameters

[in]	testfile	File generated by test.
[in]	baseline	Baseline file.
[in]	max_number_of_differences	Number of lines that may differ at most.

Return values

-1	if the test file could not be read
-2	if the baseline file could not be read
0	if the two files differ in no more than `max_number_of_differences` lines
1	if the two files differ in more than the allowed number of lines

Definition at line 230 of file testdriver.hxx.

§ tolerance_radius()

UIntArg tolerance_radius	(	""	,
		"tolerance-radius"	,
		"At most one image element in the neighborhood specified by the" " given radius has to fulfill the criteria of the following" " regression tests"	,
		false	,
		0	,
		"<int>"	,
		true
	)

§ verbose()

MultiSwitchArg verbose	(	"v"	,
		"verbose"	,
		"Increase verbosity of output messages."	,
		false
	)

Variable Documentation

§ BASIS_MAX_TEST_IMAGE_DIMENSION

const unsigned int BASIS_MAX_TEST_IMAGE_DIMENSION = 6

Maximum dimension of images used for testing.

Definition at line 87 of file testdriver.h.

§ compare_visitor

CompareVisitor compare_visitor

Definition at line 161 of file testdriver.h.

§ diff_lines_visitor

LineDiffVisitor diff_lines_visitor

Definition at line 163 of file testdriver.h.

§ diff_visitor

BinaryDiffVisitor diff_visitor

Definition at line 162 of file testdriver.h.

§ regression_tests

vector<RegressionTest> regression_tests

Container storing added regression tests.

Definition at line 132 of file testdriver.h.

Classes

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

§ _BASIS_TESTDRIVER_H

Enumeration Type Documentation

§ TestMethod

Function Documentation

§ add_before_env()

§ add_before_env_with_sep()

§ add_before_libpath()

§ binary_diff()

§ clean_cwd_after_test()

§ clean_cwd_before_test()

§ compare()

§ diff()

§ diff_lines()

§ full_output()

§ get_baseline_filenames()

§ image_regression_test()

§ intensity_tolerance()

§ max_number_of_differences()

§ max_number_of_threads()

§ orientation_insensitive()

§ redirect_output()

§ testcmd()

§ testdriversetup()

§ text_diff_lines()

§ tolerance_radius()

§ verbose()

Variable Documentation

§ BASIS_MAX_TEST_IMAGE_DIMENSION

§ compare_visitor

§ diff_lines_visitor

§ diff_visitor

§ regression_tests