Testing.h File Reference

This file defines a SimTK::Test class and some related macros which provide functionality useful in regression tests. More...

Go to the source code of this file.

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...

Namespaces
	SimTK
	This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with other symbols.

Macros
#define	SimTK_START_TEST(testName)
	Invoke this macro before anything else in your test's main(). More...
#define	SimTK_END_TEST()
	Invoke this macro as the last thing in your test's main(). More...
#define	SimTK_SUBTEST(testFunction)    do {SimTK::Test::Subtest sub(#testFunction); (testFunction)();} while(false)
	Invoke a subtest in the form of a no-argument function, arranging for some friendly output and timing information. More...
#define	SimTK_SUBTEST1(testFunction, arg1)    do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1);} while(false)
	Invoke a subtest in the form of a 1-argument function, arranging for some friendly output and timing information. More...
#define	SimTK_SUBTEST2(testFunction, arg1, arg2)    do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2);} while(false)
	Invoke a subtest in the form of a 2-argument function, arranging for some friendly output and timing information. More...
#define	SimTK_SUBTEST3(testFunction, arg1, arg2, arg3)    do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2,arg3);} while(false)
	Invoke a subtest in the form of a 3-argument function, arranging for some friendly output and timing information. More...
#define	SimTK_SUBTEST4(testFunction, arg1, arg2, arg3, arg4)    do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2,arg3,arg4);} while(false)
	Invoke a subtest in the form of a 4-argument function, arranging for some friendly output and timing information. More...
#define	SimTK_TEST(cond)   {SimTK_ASSERT_ALWAYS((cond), "Test condition failed.");}
	Test that some condition holds and complain if it doesn't. More...
#define	SimTK_TEST_FAILED(msg)   {SimTK_ASSERT_ALWAYS(!"Test case failed.", msg);}
	Call this if you have determined that a test case has failed and just need to report it and die. More...
#define	SimTK_TEST_FAILED1(fmt, a1)   {SimTK_ASSERT1_ALWAYS(!"Test case failed.",fmt,a1);}
	Call this if you have determined that a test case has failed and just need to report it and die. More...
#define	SimTK_TEST_FAILED2(fmt, a1, a2)   {SimTK_ASSERT2_ALWAYS(!"Test case failed.",fmt,a1,a2);}
	Call this if you have determined that a test case has failed and just need to report it and die. More...
#define	SimTK_TEST_EQ(v1, v2)
	Test that two numerical values are equal to within a reasonable numerical error tolerance, using a relative and absolute error tolerance. More...
#define	SimTK_TEST_EQ_SIZE(v1, v2, n)
	Test that two numerical values are equal to within a specified multiple of the default error tolerance. More...
#define	SimTK_TEST_EQ_TOL(v1, v2, tol)
	Test that two numerical values are equal to within a specified numerical error tolerance, using a relative and absolute error tolerance. More...
#define	SimTK_TEST_NOTEQ(v1, v2)
	Test that two numerical values are NOT equal to within a reasonable numerical error tolerance, using a relative and absolute error tolerance. More...
#define	SimTK_TEST_NOTEQ_SIZE(v1, v2, n)
	Test that two numerical values are NOT equal to within a specified multiple of the default error tolerance, using a relative and absolute error tolerance. More...
#define	SimTK_TEST_NOTEQ_TOL(v1, v2, tol)
	Test that two numerical values are NOT equal to within a specified numerical error tolerance, using a relative and absolute error tolerance. More...
#define	SimTK_TEST_MUST_THROW(stmt)
	Test that the supplied statement throws an std::exception of some kind. More...
#define	SimTK_TEST_MUST_THROW_SHOW(stmt)
	Test that the supplied statement throws an std::exception of some kind, and show what message got thrown. More...
#define	SimTK_TEST_MUST_THROW_EXC(stmt, exc)
	Test that the supplied statement throws a particular exception. More...
#define	SimTK_TEST_MAY_THROW(stmt)
	Allow the supplied statement to throw any std::exception without failing. More...
#define	SimTK_TEST_MAY_THROW_EXC(stmt, exc)
	Allow the supplied statement to throw a particular exception without failing. More...
#define	SimTK_TEST_MUST_THROW_DEBUG(stmt)   SimTK_TEST_MUST_THROW(stmt)
	Include a bad statement when in Debug and insist that it get caught, but don't include the statement at all in Release. More...
#define	SimTK_TEST_MUST_THROW_EXC_DEBUG(stmt, exc)    SimTK_TEST_MUST_THROW_EXC(stmt,exc)
	Include a bad statement when in Debug and insist that it get caught, but don't include the statement at all in Release. More...

Detailed Description

This file defines a SimTK::Test class and some related macros which provide functionality useful in regression tests.

Macro Definition Documentation

SimTK_START_TEST

#define SimTK_START_TEST

(

testName

)

Value:

    SimTK::Test simtk_test_(testName);  \
    try {

Invoke this macro before anything else in your test's main().

SimTK_END_TEST

#define SimTK_END_TEST

(

)

Value:

    } catch(const std::exception& e) {                  \
        std::cerr << "Test failed due to exception: "   \
                  << e.what() << std::endl;             \
        return 1;                                       \
    } catch(...) {                                      \
        std::cerr << "Test failed due to unrecognized exception.\n";    \
        return 1;                                       \
    }                                                   \
    return 0;

Invoke this macro as the last thing in your test's main().

SimTK_SUBTEST

#define SimTK_SUBTEST

(

testFunction

)

do {SimTK::Test::Subtest sub(#testFunction); (testFunction)();} while(false)

Invoke a subtest in the form of a no-argument function, arranging for some friendly output and timing information.

SimTK_SUBTEST1

#define SimTK_SUBTEST1	(		testFunction,
			arg1
	)		do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1);} while(false)

Invoke a subtest in the form of a 1-argument function, arranging for some friendly output and timing information.

SimTK_SUBTEST2

#define SimTK_SUBTEST2	(		testFunction,
			arg1,
			arg2
	)		do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2);} while(false)

Invoke a subtest in the form of a 2-argument function, arranging for some friendly output and timing information.

SimTK_SUBTEST3

#define SimTK_SUBTEST3	(		testFunction,
			arg1,
			arg2,
			arg3
	)		do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2,arg3);} while(false)

Invoke a subtest in the form of a 3-argument function, arranging for some friendly output and timing information.

SimTK_SUBTEST4

#define SimTK_SUBTEST4	(		testFunction,
			arg1,
			arg2,
			arg3,
			arg4
	)		do {SimTK::Test::Subtest sub(#testFunction); (testFunction)(arg1,arg2,arg3,arg4);} while(false)

Invoke a subtest in the form of a 4-argument function, arranging for some friendly output and timing information.

SimTK_TEST

#define SimTK_TEST

(

cond

)

{SimTK_ASSERT_ALWAYS((cond), "Test condition failed.");}

Test that some condition holds and complain if it doesn't.

SimTK_TEST_FAILED

#define SimTK_TEST_FAILED

(

msg

)

{SimTK_ASSERT_ALWAYS(!"Test case failed.", msg);}

Call this if you have determined that a test case has failed and just need to report it and die.

Pass the message as a string in quotes.

SimTK_TEST_FAILED1

#define SimTK_TEST_FAILED1	(		fmt,
			a1
	)		{SimTK_ASSERT1_ALWAYS(!"Test case failed.",fmt,a1);}

Call this if you have determined that a test case has failed and just need to report it and die.

The message is a printf format string in quotes; here with one argument expected.

SimTK_TEST_FAILED2

#define SimTK_TEST_FAILED2	(		fmt,
			a1,
			a2
	)		{SimTK_ASSERT2_ALWAYS(!"Test case failed.",fmt,a1,a2);}

Call this if you have determined that a test case has failed and just need to report it and die.

The message is a printf format string in quotes; here with two arguments expected.

SimTK_TEST_EQ

#define SimTK_TEST_EQ	(		v1,
			v2
	)

Value:

    {SimTK_ASSERT_ALWAYS(SimTK::Test::numericallyEqual((v1),(v2),1),   \
     "Test values should have been numerically equivalent at default tolerance.");}

Test that two numerical values are equal to within a reasonable numerical error tolerance, using a relative and absolute error tolerance.

In the case of composite types, the test is performed elementwise.

SimTK_TEST_EQ_SIZE

#define SimTK_TEST_EQ_SIZE	(		v1,
			v2,
			n
	)

Value:

    {SimTK_ASSERT1_ALWAYS(SimTK::Test::numericallyEqual((v1),(v2),(n)),   \
     "Test values should have been numerically equivalent at size=%d times default tolerance.",(n));}

Test that two numerical values are equal to within a specified multiple of the default error tolerance.

SimTK_TEST_EQ_TOL

#define SimTK_TEST_EQ_TOL	(		v1,
			v2,
			tol
	)

Value:

    {SimTK_ASSERT1_ALWAYS(SimTK::Test::numericallyEqual((v1),(v2),1,(tol)),   \
     "Test values should have been numerically equivalent at tolerance=%g.",(tol));}

Test that two numerical values are equal to within a specified numerical error tolerance, using a relative and absolute error tolerance.

In the case of composite types, the test is performed elementwise.

SimTK_TEST_NOTEQ

#define SimTK_TEST_NOTEQ	(		v1,
			v2
	)

Value:

    {SimTK_ASSERT_ALWAYS(!SimTK::Test::numericallyEqual((v1),(v2),1),   \
     "Test values should NOT have been numerically equivalent (at default tolerance).");}

Test that two numerical values are NOT equal to within a reasonable numerical error tolerance, using a relative and absolute error tolerance.

In the case of composite types, the equality test is performed elementwise.

SimTK_TEST_NOTEQ_SIZE

#define SimTK_TEST_NOTEQ_SIZE	(		v1,
			v2,
			n
	)

Value:

    {SimTK_ASSERT1_ALWAYS(!SimTK::Test::numericallyEqual((v1),(v2),(n)),   \
     "Test values should NOT have been numerically equivalent at size=%d times default tolerance.",(n));}

Test that two numerical values are NOT equal to within a specified multiple of the default error tolerance, using a relative and absolute error tolerance.

In the case of composite types, the equality test is performed elementwise.

SimTK_TEST_NOTEQ_TOL

#define SimTK_TEST_NOTEQ_TOL	(		v1,
			v2,
			tol
	)

Value:

    {SimTK_ASSERT1_ALWAYS(!SimTK::Test::numericallyEqual((v1),(v2),1,(tol)),   \
     "Test values should NOT have been numerically equivalent at tolerance=%g.",(tol));}

Test that two numerical values are NOT equal to within a specified numerical error tolerance, using a relative and absolute error tolerance.

In the case of composite types, the equality test is performed elementwise.

SimTK_TEST_MUST_THROW

#define SimTK_TEST_MUST_THROW

(

stmt

)

Value:

    do {int threw=0; try {stmt;}                \
        catch(const std::exception&){threw=1;}  \
        catch(...){threw=2;}                    \
        if (threw==0) SimTK_TEST_FAILED1("Expected statement\n----\n%s\n----\n  to throw an exception but it did not.",#stmt); \
        if (threw==2) SimTK_TEST_FAILED1("Expected statement\n%s\n  to throw an std::exception but it threw something else.",#stmt); \
    }while(false)

Test that the supplied statement throws an std::exception of some kind.

SimTK_TEST_MUST_THROW_SHOW

#define SimTK_TEST_MUST_THROW_SHOW

(

stmt

)

Value:

    do {int threw=0; try {stmt;}                \
        catch(const std::exception& e) {threw=1; \
            std::cout << "(OK) Threw: " << e.what() << std::endl;}  \
        catch(...){threw=2;}                    \
        if (threw==0) SimTK_TEST_FAILED1("Expected statement\n----\n%s\n----\n  to throw an exception but it did not.",#stmt); \
        if (threw==2) SimTK_TEST_FAILED1("Expected statement\n%s\n  to throw an std::exception but it threw something else.",#stmt); \
    }while(false)

Test that the supplied statement throws an std::exception of some kind, and show what message got thrown.

SimTK_TEST_MUST_THROW_EXC

#define SimTK_TEST_MUST_THROW_EXC	(		stmt,
			exc
	)

Value:

    do {int threw=0; try {stmt;}                \
        catch(const exc&){threw=1;}             \
        catch(...){threw=2;}                    \
        if (threw==0) SimTK_TEST_FAILED1("Expected statement\n----\n%s\n----\n  to throw an exception but it did not.",#stmt); \
        if (threw==2) SimTK_TEST_FAILED2("Expected statement\n----\n%s\n----\n  to throw exception type %s but it threw something else.",#stmt,#exc); \
    }while(false)

Test that the supplied statement throws a particular exception.

SimTK_TEST_MAY_THROW

#define SimTK_TEST_MAY_THROW

(

stmt

)

Value:

    do {int threw=0; try {stmt;}                \
        catch(const std::exception&){threw=1;}  \
        catch(...){threw=2;}                    \
        if (threw==2) SimTK_TEST_FAILED1("Expected statement\n%s\n  to throw an std::exception but it threw something else.",#stmt); \
    }while(false)

Allow the supplied statement to throw any std::exception without failing.

SimTK_TEST_MAY_THROW_EXC

#define SimTK_TEST_MAY_THROW_EXC	(		stmt,
			exc
	)

Value:

    do {int threw=0; try {stmt;}                \
        catch(const exc&){threw=1;}             \
        catch(...){threw=2;}                    \
        if (threw==2) SimTK_TEST_FAILED2("Expected statement\n----\n%s\n----\n  to throw exception type %s but it threw something else.",#stmt,#exc); \
    }while(false)

Allow the supplied statement to throw a particular exception without failing.

SimTK_TEST_MUST_THROW_DEBUG

#define SimTK_TEST_MUST_THROW_DEBUG

(

stmt

)

SimTK_TEST_MUST_THROW(stmt)

Include a bad statement when in Debug and insist that it get caught, but don't include the statement at all in Release.

SimTK_TEST_MUST_THROW_EXC_DEBUG

#define SimTK_TEST_MUST_THROW_EXC_DEBUG	(		stmt,
			exc
	)		SimTK_TEST_MUST_THROW_EXC(stmt,exc)

Include a bad statement when in Debug and insist that it get caught, but don't include the statement at all in Release.