Writing test fixture

Files
file	HelperMacros.h
	Macros intended to ease the definition of test suites.

Classes
class	TestCaller< Fixture >
	Generate a test case from a fixture method.A test caller provides access to a test case method on a test fixture class. Test callers are useful when you want to run an individual test or add it to a suite. Test Callers invoke only one Test (i.e. test method) on one Fixture of a TestFixture. More...
class	TestFixture
	Wraps a test case with setUp and tearDown methods.A TestFixture is used to provide a common environment for a set of test cases. More...

Macros
#define	CPPUNIT_TEST_SUITE(ATestFixtureType)
	Begin test suite.
#define	CPPUNIT_TEST_SUB_SUITE(ATestFixtureType, ASuperClass)
	Begin test suite (includes parent suite)
#define	CPPUNIT_TEST_SUITE_END()
	End declaration of the test suite.
#define	CPPUNIT_TEST_SUITE_SETUP()
	Setup method that is executed before all tests.
#define	CPPUNIT_TEST_SUITE_TEARDOWN()
	Tear down method that is executed after all tests.
#define	CPPUNIT_TEST_SUITE_END_ABSTRACT()
	End declaration of an abstract test suite.
#define	CPPUNIT_TEST_SUITE_ADD_TEST(test)   context.addTest( test )
	Add a test to the suite (for custom test macro).
#define	CPPUNIT_TEST(testMethod)
	Add a method to the suite.
#define	CPPUNIT_TEST_EXCEPTION(testMethod, ExceptionType)
	Add a test which fail if the specified exception is not caught.
#define	CPPUNIT_TEST_FAIL(testMethod)   CPPUNIT_TEST_EXCEPTION( testMethod, CPPUNIT_NS::Exception )
	Adds a test case which is excepted to fail.
#define	CPPUNIT_TEST_SUITE_ADD_CUSTOM_TESTS(testAdderMethod)   testAdderMethod( context )
	Adds some custom test cases.
#define	CPPUNIT_TEST_SUITE_PROPERTY(APropertyKey, APropertyValue)
	Adds a property to the test suite builder context.

---

Detailed Description

---

Macro Definition Documentation

#define CPPUNIT_TEST

(

testMethod

)

Value:

CPPUNIT_TEST_SUITE_ADD_TEST(                           \
        ( new CPPUNIT_NS::TestCaller<TestFixtureType>(    \
                  context.getTestNameFor( #testMethod),   \
                  &TestFixtureType::testMethod,           \
                  context.makeFixture() ) ) )

Add a method to the suite.

Parameters:

testMethod

Name of the method of the test case to add to the suite. The signature of the method must be of type: void testMethod();

See also:

CPPUNIT_TEST_SUITE.

#define CPPUNIT_TEST_EXCEPTION	(		testMethod,
			ExceptionType
	)

Value:

CPPUNIT_TEST_SUITE_ADD_TEST(                                        \
      (new CPPUNIT_NS::ExceptionTestCaseDecorator< ExceptionType >(  \
          new CPPUNIT_NS::TestCaller< TestFixtureType >(             \
                               context.getTestNameFor( #testMethod ),  \
                               &TestFixtureType::testMethod,         \
                               context.makeFixture() ) ) ) )

Add a test which fail if the specified exception is not caught.

Example:

 #include <cppunit/extensions/HelperMacros.h>
 #include <vector>
 class MyTest : public CppUnit::TestFixture {
   CPPUNIT_TEST_SUITE( MyTest );
   CPPUNIT_TEST_EXCEPTION( testVectorAtThrow, std::out_of_range );
   CPPUNIT_TEST_SUITE_END();
 public:
   void testVectorAtThrow()
   {
     std::vector<int> v;
     v.at( 1 );     // must throw exception std::out_of_range
   }
 };

Parameters:

testMethod	Name of the method of the test case to add to the suite.
ExceptionType	Type of the exception that must be thrown by the test method.

Deprecated:

Use the assertion macro CPPUNIT_ASSERT_THROW instead.

#define CPPUNIT_TEST_FAIL

(

testMethod

)

CPPUNIT_TEST_EXCEPTION( testMethod, CPPUNIT_NS::Exception )

Adds a test case which is excepted to fail.

The added test case expect an assertion to fail. You usually used that type of test case when testing custom assertion macros.

 CPPUNIT_TEST_FAIL( testAssertFalseFail );
 
 void testAssertFalseFail()
 {
   CPPUNIT_ASSERT( false );
 }

See also:

Creating custom assertions.

Deprecated:

Use the assertion macro CPPUNIT_ASSERT_ASSERTION_FAIL instead.

#define CPPUNIT_TEST_SUB_SUITE	(		ATestFixtureType,
			ASuperClass
	)

Value:

public:                                                        \
    typedef ASuperClass ParentTestFixtureType;                   \
  private:                                                       \
    CPPUNIT_TEST_SUITE( ATestFixtureType );                      \
      ParentTestFixtureType::addTestsToSuite( baseContext )

Begin test suite (includes parent suite)

This macro may only be used in a class whose parent class defines a test suite using CPPUNIT_TEST_SUITE() or CPPUNIT_TEST_SUB_SUITE().

This macro begins the declaration of a test suite, in the same manner as CPPUNIT_TEST_SUITE(). In addition, the test suite of the parent is automatically inserted in the test suite being defined.

Here is an example:

 #include <cppunit/extensions/HelperMacros.h>
 class MySubTest : public MyTest {
   CPPUNIT_TEST_SUB_SUITE( MySubTest, MyTest );
   CPPUNIT_TEST( testAdd );
   CPPUNIT_TEST( testSub );
   CPPUNIT_TEST_SUITE_END();
 public:
   void testAdd();
   void testSub();
 };

Parameters:

ATestFixtureType	Type of the test case class. This type MUST be derived from TestFixture.
ASuperClass	Type of the parent class.

See also:

CPPUNIT_TEST_SUITE.

#define CPPUNIT_TEST_SUITE

(

ATestFixtureType

)

Value:

public:                                                                   \
    typedef ATestFixtureType TestFixtureType;                               \
                                                                            \
  private:                                                                  \
    static const CPPUNIT_NS::TestNamer &getTestNamer__()                    \
    {                                                                       \
      static CPPUNIT_TESTNAMER_DECL( testNamer, ATestFixtureType );         \
      return testNamer;                                                     \
    }                                                                       \
                                                                            \
  public:                                                                   \
    typedef CPPUNIT_NS::TestSuiteBuilderContext<TestFixtureType>            \
                TestSuiteBuilderContextType;                                \
                                                                            \
    static void                                                             \
    addTestsToSuite( CPPUNIT_NS::TestSuiteBuilderContextBase &baseContext ) \
    {                                                                       \
      TestSuiteBuilderContextType context( baseContext )

Begin test suite.

This macro starts the declaration of a new test suite. Use CPPUNIT_TEST_SUB_SUITE() instead, if you wish to include the test suite of the parent class.

Parameters:

ATestFixtureType

Type of the test case class. This type MUST be derived from TestFixture.

See also:

CPPUNIT_TEST_SUB_SUITE, CPPUNIT_TEST, CPPUNIT_TEST_SUITE_END,

CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_EXCEPTION, CPPUNIT_TEST_FAIL.

#define CPPUNIT_TEST_SUITE_ADD_CUSTOM_TESTS

(

testAdderMethod

)

testAdderMethod( context )

Adds some custom test cases.

Use this to add one or more test cases to the fixture suite. The specified method is called with a context parameter that can be used to name, instantiate fixture, and add instantiated test case to the fixture suite. The specified method must have the following signature:

 static void aMethodName( TestSuiteBuilderContextType &context );

TestSuiteBuilderContextType is typedef to TestSuiteBuilderContext<TestFixtureType> declared by CPPUNIT_TEST_SUITE().

Here is an example that add two custom tests:

 #include <cppunit/extensions/HelperMacros.h>

 class MyTest : public CppUnit::TestFixture {
   CPPUNIT_TEST_SUITE( MyTest );
   CPPUNIT_TEST_SUITE_ADD_CUSTOM_TESTS( addTimeOutTests );
   CPPUNIT_TEST_SUITE_END();
 public:
   static void addTimeOutTests( TestSuiteBuilderContextType &context )
   {
     context.addTest( new TimeOutTestCaller( context.getTestNameFor( "test1" ) ),
                                             &MyTest::test1,
                                             context.makeFixture(),
                                             5.0 );
     context.addTest( new TimeOutTestCaller( context.getTestNameFor( "test2" ) ),
                                             &MyTest::test2,
                                             context.makeFixture(),
                                             5.0 );
   }

   void test1()
   {
     // Do some test that may never end...
   }

   void test2()
   {
     // Do some test that may never end...
   }
 };

Parameters:

testAdderMethod

Name of the method called to add the test cases.

#define CPPUNIT_TEST_SUITE_ADD_TEST

(

test

)

context.addTest( test )

Add a test to the suite (for custom test macro).

The specified test will be added to the test suite being declared. This macro is intended for advanced usage, to extend CppUnit by creating new macro such as CPPUNIT_TEST_EXCEPTION()...

Between macro CPPUNIT_TEST_SUITE() and CPPUNIT_TEST_SUITE_END(), you can assume that the following variables can be used:

 typedef TestSuiteBuilder<TestFixtureType> TestSuiteBuilderType;
 TestSuiteBuilderType &context;

context can be used to name test case, create new test fixture instance, or add test case to the test fixture suite.

Below is an example that show how to use this macro to create new macro to add test to the fixture suite. The macro below show how you would add a new type of test case which fails if the execution last more than a given time limit. It relies on an imaginary TimeOutTestCaller class which has an interface similar to TestCaller.

 #define CPPUNITEX_TEST_TIMELIMIT( testMethod, timeLimit )            \
      CPPUNIT_TEST_SUITE_ADD_TEST( (new TimeOutTestCaller<TestFixtureType>(  \
                  namer.getTestNameFor( #testMethod ),                \
                  &TestFixtureType::testMethod,                   \
                  factory.makeFixture(),                              \
                  timeLimit ) ) )
   
 class PerformanceTest : CppUnit::TestFixture
 {
 public:
   CPPUNIT_TEST_SUITE( PerformanceTest );
   CPPUNITEX_TEST_TIMELIMIT( testSortReverseOrder, 5.0 );
   CPPUNIT_TEST_SUITE_END();

   void testSortReverseOrder();
 };

Parameters:

test	Test to add to the suite. Must be a subclass of Test. The test name should have been obtained using TestNamer::getTestNameFor().

#define CPPUNIT_TEST_SUITE_END

(

)

Value:

}                                                                          \
                                                                               \
    struct CppUnitExDeleter { /* avoid deprecated auto_ptr warnings */         \
        CPPUNIT_NS::TestSuite *suite;                                          \
        CppUnitExDeleter() : suite (0) {}                                      \
        ~CppUnitExDeleter() { delete suite; }                                  \
        CPPUNIT_NS::TestSuite *release() {                                     \
                CPPUNIT_NS::TestSuite *tmp = suite; suite = NULL; return tmp;  \
        }                                                                      \
    private:                                                                   \
        /*prevent copy c'tor and operator=*/                                   \
        CppUnitExDeleter(const CppUnitExDeleter&);                             \
        CppUnitExDeleter& operator=(const CppUnitExDeleter&);                  \
    };                                                                         \
                                                                               \
public:                                                                        \
    static CPPUNIT_NS::TestSuite *suite()                                      \
    {                                                                          \
      const CPPUNIT_NS::TestNamer &namer = getTestNamer__();                   \
      CppUnitExDeleter guard;                                                  \
      guard.suite = new CPPUNIT_NS::TestSuite( namer.getFixtureName() );       \
      CPPUNIT_NS::ConcretTestFixtureFactory<TestFixtureType> factory;          \
      CPPUNIT_NS::TestSuiteBuilderContextBase context( *guard.suite,           \
                                                       namer,                  \
                                                       factory );              \
      TestFixtureType::addTestsToSuite( context );                             \
      return guard.release();                                                  \
    }                                                                          \
  private: /* dummy typedef so that the macro can still end with ';'*/         \
    typedef int CppUnitDummyTypedefForSemiColonEnding__

End declaration of the test suite.

After this macro, member access is set to "private".

See also:

CPPUNIT_TEST_SUITE.

CPPUNIT_TEST_SUITE_REGISTRATION.

#define CPPUNIT_TEST_SUITE_END_ABSTRACT

(

)

Value:

}                                                                          \
  private: /* dummy typedef so that the macro can still end with ';'*/         \
    typedef int CppUnitDummyTypedefForSemiColonEnding__

End declaration of an abstract test suite.

Use this macro to indicate that the TestFixture is abstract. No static suite() method will be declared.

After this macro, member access is set to "private".

Here is an example of usage:

The abstract test fixture:

 #include <cppunit/extensions/HelperMacros.h>
 class AbstractDocument;
 class AbstractDocumentTest : public CppUnit::TestFixture {
   CPPUNIT_TEST_SUITE( AbstractDocumentTest );
   CPPUNIT_TEST( testInsertText );
   CPPUNIT_TEST_SUITE_END_ABSTRACT();
 public:
   void testInsertText();
 
   void setUp()
   {
     m_document = makeDocument();
   }

   void tearDown()
   {
     delete m_document;
   }
 protected:
   virtual AbstractDocument *makeDocument() =0;

   AbstractDocument *m_document;
 };

The concret test fixture:

 class RichTextDocumentTest : public AbstractDocumentTest {
   CPPUNIT_TEST_SUB_SUITE( RichTextDocumentTest, AbstractDocumentTest );
   CPPUNIT_TEST( testInsertFormatedText );
   CPPUNIT_TEST_SUITE_END();
 public:
   void testInsertFormatedText();
 protected:
   AbstractDocument *makeDocument()
   {
     return new RichTextDocument();
   }
 };

See also:

CPPUNIT_TEST_SUB_SUITE.

CPPUNIT_TEST_SUITE_REGISTRATION.

#define CPPUNIT_TEST_SUITE_PROPERTY	(		APropertyKey,
			APropertyValue
	)

Value:

context.addProperty( std::string(APropertyKey),                 \
                         std::string(APropertyValue) )

Adds a property to the test suite builder context.

Parameters:

APropertyKey	Key of the property to add.
APropertyValue	Value for the added property. Example: CPPUNIT_TEST_SUITE_PROPERTY("XmlFileName", "paraTest.xml");

#define CPPUNIT_TEST_SUITE_SETUP

(

)

Setup method that is executed before all tests.

Use this macro to add a method that will be executed exactly once in a test suite before any tests are executed

Here is an example of usage:

 #include <cppunit/extensions/HelperMacros.h>

 class Test : public CppUnit::TestFixture {
   CPPUNIT_TEST_SUITE( Test );
   CPPUNIT_TEST_SUITE_SETUP( suite_setUp );
   CPPUNIT_TEST( test1 );
   CPPUNIT_TEST( test2 );
   CPPUNIT_TEST_SUITE_END();
 public:
   void test1();
   void test2();

   void setUp()
   {
      // set up before each test
   }

   void tearDown()
   {
      // tear dowan after each test
   }

   void suite_setUp()
   {
      // set up before the first call to setUp()
   }

 };

See also:

CPPUNIT_TEST_SUITE

CPPUNIT_TEST_SUITE_TEARDOWN

#define CPPUNIT_TEST_SUITE_TEARDOWN

(

)

Tear down method that is executed after all tests.

Use this macro to add a method that will be executed exactly once in a test suite after all tests are executed

Here is an example of usage:

 #include <cppunit/extensions/HelperMacros.h>

 class Test : public CppUnit::TestFixture {
   CPPUNIT_TEST_SUITE( Test );
   CPPUNIT_TEST_SUITE_TEARDOWN( suite_tearDown );
   CPPUNIT_TEST( test1 );
   CPPUNIT_TEST( test2 );
   CPPUNIT_TEST_SUITE_END();
 public:
   void test1();
   void test2();

   void setUp()
   {
      // set up before each test
   }

   void tearDown()
   {
      // tear dowan after each test
   }

   void suite_tearDown()
   {
      // tear down after the last call to tearDown()
   }

 };

See also:

CPPUNIT_TEST_SUITE

CPPUNIT_TEST_SUITE_SETUP