Classes | Macros | Enumerations | Functions | Variables
testdriver.h File Reference

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< RegressionTestregression_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>"  ,
 
)

§ 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>"  ,
 
)

§ 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]testfileFile generated by test.
[in]baselineBaseline file.
Return values
-1if the test file could not be read
-2if the baseline file could not be read
0if the two files are identical
1if 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>"  ,
,
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>"  ,
,
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>"  ,
,
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:

  1. Strip the file name suffix.
  2. Append a suffix containing of a dot (.) and a digit, i.e., .x
  3. 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_templateFile 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]imagefileOutput image file of test run.
[in]baselineBaseline image file.
[in]intensity_toleranceMaximum tolerable intensity difference.
[in]max_number_of_differencesMaximum number of differing pixels.
[in]tolerance_radiusTolerance radius.
[in]orientation_insensitiveChange orientation of both images to a common coordinate orientation before comparing them.
[in]reportLevel 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  ,
,
"<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  ,
,
"<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]argcNumber of arguments.
[in]argvCommand-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]testfileFile generated by test.
[in]baselineBaseline file.
[in]max_number_of_differencesNumber of lines that may differ at most.
Return values
-1if the test file could not be read
-2if the baseline file could not be read
0if the two files differ in no more than max_number_of_differences lines
1if 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  ,
,
"<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.