SimTK defines some utilities to facilitate the creation of regression tests for SimTK facilities. More...

Classes
class	SimTK::Test
	This is the main class to support testing. More...
class	SimTK::Test::Subtest
	Internal utility class for generating test messages for subtests. More...
Functions
	SimTK::Test::Test (const std::string &name)
	SimTK::Test::~Test ()
template<class T >
static double	SimTK::Test::defTol ()
template<class T1 , class T2 >
static double	SimTK::Test::defTol2 ()
static bool	SimTK::Test::numericallyEqual (float v1, float v2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (double v1, double v2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (long double v1, long double v2, int n, double tol=defTol< long double >())
static bool	SimTK::Test::numericallyEqual (int i1, int i2, int n, double tol=0)
static bool	SimTK::Test::numericallyEqual (unsigned u1, unsigned u2, int n, double tol=0)
static bool	SimTK::Test::numericallyEqual (float v1, double v2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (double v1, float v2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (float v1, long double v2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (long double v1, float v2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (double v1, long double v2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (long double v1, double v2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (int i1, float f2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (float f1, int i2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (unsigned i1, float f2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (float f1, unsigned i2, int n, double tol=defTol< float >())
static bool	SimTK::Test::numericallyEqual (int i1, double f2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (double f1, int i2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (unsigned i1, double f2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (double f1, unsigned i2, int n, double tol=defTol< double >())
static bool	SimTK::Test::numericallyEqual (int i1, long double f2, int n, double tol=defTol< long double >())
static bool	SimTK::Test::numericallyEqual (long double f1, int i2, int n, double tol=defTol< long double >())
static bool	SimTK::Test::numericallyEqual (unsigned i1, long double f2, int n, double tol=defTol< long double >())
static bool	SimTK::Test::numericallyEqual (long double f1, unsigned i2, int n, double tol=defTol< long double >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const std::complex< P > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const conjugate< P > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const std::complex< P > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const conjugate< P > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const negator< P > &v1, const negator< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const P &v1, const negator< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const negator< P > &v1, const P &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const negator< std::complex< P > > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const negator< conjugate< P > > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const std::complex< P > &v1, const negator< conjugate< P > > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const conjugate< P > &v1, const negator< std::complex< P > > &v2, int n, double tol=defTol< P >())
template<int M, class E1 , int S1, class E2 , int S2>
static bool	SimTK::Test::numericallyEqual (const Vec< M, E1, S1 > &v1, const Vec< M, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int N, class E1 , int S1, class E2 , int S2>
static bool	SimTK::Test::numericallyEqual (const Row< N, E1, S1 > &v1, const Row< N, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int M, int N, class E1 , int CS1, int RS1, class E2 , int CS2, int RS2>
static bool	SimTK::Test::numericallyEqual (const Mat< M, N, E1, CS1, RS1 > &v1, const Mat< M, N, E2, CS2, RS2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int N, class E1 , int S1, class E2 , int S2>
static bool	SimTK::Test::numericallyEqual (const SymMat< N, E1, S1 > &v1, const SymMat< N, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const VectorView_< E1 > &v1, const VectorView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const Vector_< E1 > &v1, const Vector_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const RowVectorView_< E1 > &v1, const RowVectorView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const RowVector_< E1 > &v1, const RowVector_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const MatrixView_< E1 > &v1, const MatrixView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	SimTK::Test::numericallyEqual (const Matrix_< E1 > &m1, const Matrix_< E2 > &m2, int n, double tol=(defTol2< E1, E2 >()))
template<class P >
static bool	SimTK::Test::numericallyEqual (const Rotation_< P > &R1, const Rotation_< P > &R2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const Transform_< P > &T1, const Transform_< P > &T2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const UnitInertia_< P > &G1, const UnitInertia_< P > &G2, int n, double tol=defTol< P >())
template<class P >
static bool	SimTK::Test::numericallyEqual (const Inertia_< P > &I1, const Inertia_< P > &I2, int n, double tol=defTol< P >())
static Real	SimTK::Test::randReal ()
static Complex	SimTK::Test::randComplex ()
static Conjugate	SimTK::Test::randConjugate ()
static float	SimTK::Test::randFloat ()
static double	SimTK::Test::randDouble ()
template<int M>
static Vec< M >	SimTK::Test::randVec ()
template<int N>
static Row< N >	SimTK::Test::randRow ()
template<int M, int N>
static Mat< M, N >	SimTK::Test::randMat ()
template<int N>
static SymMat< N >	SimTK::Test::randSymMat ()
static Vector	SimTK::Test::randVector (int m)
static Matrix	SimTK::Test::randMatrix (int m, int n)
static Vec3	SimTK::Test::randVec3 ()
static Mat33	SimTK::Test::randMat33 ()
static SymMat33	SimTK::Test::randSymMat33 ()
static SpatialVec	SimTK::Test::randSpatialVec ()
static SpatialMat	SimTK::Test::randSpatialMat ()
static Rotation	SimTK::Test::randRotation ()
static Transform	SimTK::Test::randTransform ()
	SimTK::Test::Subtest::~Subtest ()

Detailed Description

SimTK defines some utilities to facilitate the creation of regression tests for SimTK facilities.

These utilities consist of a SimTK::Test class and related support macros.

Features include:

uniform, readable output including execution times
identical comparison tests for all numerical types, scalar and composite
careful treatment of numerical tolerances using relative and absolute comparisons, with provision for size-dependent, reduced accuracy expectations for matrix operations
default tolerance varies with precision (caller can override)
convenient generation of random test data
convenient testing of required argument checking (i.e., test fails unless an exception is thrown)

The Testing.h header file is not automatically included with SimTKcommon.h; you have to ask for it explicilty. Here's how you use this facility:

 #include "SimTKcommon/Testing.h"
 void myFirstSubtest() {...}
 void myNextSubtest() {...}
 int main() {
      SimTK_START_TEST("OverallTestName");
          SimTK_SUBTEST(myFirstSubtest);
          SimTK_SUBTEST(myNextSubtest);
      SimTK_END_TEST();
 }

The arguments to SimTK_SUBTEST are function names and will be called with "()" appended. If your subtest functions have arguments, use SimTK_SUBTEST1(name,arg) or SimTK_SUBTEST2(name,arg1,arg2) which will call name(arg) or name(arg1,arg2) as appropriate.

This will result in nice output including execution times for the overall test and the individual subtests, and arrange for any exceptions raised in the tests to be caught, properly reported, and cause a non-zero return from main(). If everything runs successfully, main() will return 0. Here is an example of the output produced:

 Starting test TestScalar ...
   testIsNaN            ... done. testIsNaN            time: 0ms.
   testIsInf            ... done. testIsInf            time: 0ms.
   testIsFinite         ... done. testIsFinite         time: 0ms.
   testSignBit          ... done. testSignBit          time: 0ms.
   testSign             ... done. testSign             time: 0ms.
   testSquareAndCube    ... done. testSquareAndCube    time: 0ms.
 Done. TestScalar time: 15ms.

(Admittedly the timings aren't much use in that example!)

Within your subtests, several useful macros and static functions are available. By using these macros, the resulting message will include the actual line number at which the test failure occurred.

      SimTK_TEST(cond)             -- this is like assert(cond)
      SimTK_TEST_FAILED("message") -- like assert(!"message")

      SimTK_TEST_EQ(a,b)           -- equal to within a default tolerance
      SimTK_TEST_NOTEQ(a,b)        -- not equal to within a default tolerance

      SimTK_TEST_EQ_SIZE(a,b,n)    -- equal to within n * default tolerance
      SimTK_TEST_NOTEQ_SIZE(a,b,n) -- not equal to within n * default tolerance

      SimTK_TEST_EQ_TOL(a,b,tol)   -- same as above with specified tolerance
      SimTK_TEST_NOTEQ_TOL(a,b,tol)

      SimTK_TEST_MUST_THROW(statement)    -- we expect the statement to throw some exception
      SimTK_TEST_MUST_THROW_EXC(statement, exception) -- we expect a particular exception type

The SimTK_TEST_EQ macros test scalar and composite numerical values for equality to within a numerical tolerance, using both relative and absolute tolerances. The default is the value of SignificantReal for the underlying numerical type. For composite types the equality test is done elementwise; that is, we apply it strictly to each pair of elements not to an overall norm.

The SimTK_TEST_EQ_SIZE macros allows you to specify a multiple of default tolerance to be used. This is necessary for most Matrix operations since attainable accuracy falls off with the size of the matrix. Typically, if the smallest dimension of the Matrix is n, then the tolerance you should allow is n*scalarTol where scalarTol is the default tolerance for a scalar operation. Note that you still need to specify size when comparing Vector or scalar values if those values were produced using a matrix computation.

The SimTK_TEST_EQ_TOL macros take a user-specified tolerance value for the elementwise tests, overriding the default.

The SimTK::Test class has a number of static methods that are useful in tests. Currently these are all for generating numerical objects filled with random numbers (all uniform between -1 and 1). These are:

      randReal()      randFloat()     randDouble()
      randComplex()   randConjugate()
      randVec<M>()    randRow<N>()    randMat<M,N>()  randSymMat<N>()
      randVector(m)   randMatrix(m,n)
      randVec3()      randMat33()
      randSpatialVec() randSpatialMat()
      randRotation()  randTransform()

These are invoked Test::randReal() etc.

Function Documentation

SimTK::Test::Test ( const std::string & name ) [inline, inherited]

SimTK::Test::~Test ( ) [inline, inherited]

template<class T >

static double SimTK::Test::defTol ( ) [inline, static, inherited]

template<class T1 , class T2 >

static double SimTK::Test::defTol2 ( ) [inline, static, inherited]

static bool SimTK::Test::numericallyEqual	(	float	v1,
		float	v2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	double	v1,
		double	v2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	long double	v1,
		long double	v2,
		int	n,
		double	tol = `defTol<long double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	int	i1,
		int	i2,
		int	n,
		double	tol = `0`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	unsigned	u1,
		unsigned	u2,
		int	n,
		double	tol = `0`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	float	v1,
		double	v2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	double	v1,
		float	v2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	float	v1,
		long double	v2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	long double	v1,
		float	v2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	double	v1,
		long double	v2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	long double	v1,
		double	v2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	int	i1,
		float	f2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	float	f1,
		int	i2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	unsigned	i1,
		float	f2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	float	f1,
		unsigned	i2,
		int	n,
		double	tol = `defTol<float>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	int	i1,
		double	f2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	double	f1,
		int	i2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	unsigned	i1,
		double	f2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	double	f1,
		unsigned	i2,
		int	n,
		double	tol = `defTol<double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	int	i1,
		long double	f2,
		int	n,
		double	tol = `defTol<long double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	long double	f1,
		int	i2,
		int	n,
		double	tol = `defTol<long double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	unsigned	i1,
		long double	f2,
		int	n,
		double	tol = `defTol<long double>()`
	)		`[inline, static, inherited]`

static bool SimTK::Test::numericallyEqual	(	long double	f1,
		unsigned	i2,
		int	n,
		double	tol = `defTol<long double>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const std::complex< P > &	v1,
		const std::complex< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const conjugate< P > &	v1,
		const conjugate< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const std::complex< P > &	v1,
		const conjugate< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const conjugate< P > &	v1,
		const std::complex< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const negator< P > &	v1,
		const negator< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const P &	v1,
		const negator< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const negator< P > &	v1,
		const P &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const negator< std::complex< P > > &	v1,
		const conjugate< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const negator< conjugate< P > > &	v1,
		const std::complex< P > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const std::complex< P > &	v1,
		const negator< conjugate< P > > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<class P >

static bool SimTK::Test::numericallyEqual	(	const conjugate< P > &	v1,
		const negator< std::complex< P > > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)		`[inline, static, inherited]`

template<int M, class E1 , int S1, class E2 , int S2>

static bool SimTK::Test::numericallyEqual	(	const Vec< M, E1, S1 > &	v1,
		const Vec< M, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)		`[inline, static, inherited]`

template<int N, class E1 , int S1, class E2 , int S2>

static bool SimTK::Test::numericallyEqual	(	const Row< N, E1, S1 > &	v1,
		const Row< N, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)		`[inline, static, inherited]`

template<int M, int N, class E1 , int CS1, int RS1, class E2 , int CS2, int RS2>

static bool SimTK::Test::numericallyEqual	(	const Mat< M, N, E1, CS1, RS1 > &	v1,
		const Mat< M, N, E2, CS2, RS2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)		`[inline, static, inherited]`

template<int N, class E1 , int S1, class E2 , int S2>

static bool SimTK::Test::numericallyEqual	(	const SymMat< N, E1, S1 > &	v1,
		const SymMat< N, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)		`[inline, static, inherited]`