Makefile.

makefile.am: added src/CppUnitLibraries.dsw, new contribution, and
src/qttestrunner.

* TODO: updated (doc).

* contrib/msvc/AddingUnitTestMethod.dsm: added, submitted by
bloodchen@hotmail.com.

* constrib/msvc/readme.txt: updated.

* include/cppunit/TestAsserter.h:
* include/cppunit/SourceLine.h: updated doc.

* include/cppunit/TestCaller.h: reindented. updated doc.

* include/cppunit/extensions/HelperMacros.h: relaxed constraint on fixture.
Fixture base class may be TestFixture instead of TestCase.

* include/cppunit/TestCase.h:
* src/cppunit/TestCase.h: TestCase inherits TestFixture for setUp() and
tearDown() definition. Moved documentation to TestFixture.

* include/cppunit/TestFixture.h: updated documentation.

* include/cppunit/TestRegistry.h:
* src/cppunit/TestRegistry.cpp: Removed. Replaced by TestFactoryRegistry.

* include/cppunit/TextTestRunner.h:
* src/cppunit/TextTestRunner.cpp: made printing progress using a
TextTestProgressListener optional.

* examples\cppunittest\ExceptionTest.h:
* examples\cppunittest\HelperMacrosTest.h:
* examples\cppunittest\HelperMacrosTest.cpp:
* examples\cppunittest\NotEqualException.h:
* examples\cppunittest\OrthodoxTest.h:
* examples\cppunittest\RepeatedTest.h:
* examples\cppunittest\TestAssertTest.h:
* examples\cppunittest\TestCallerTest.h:
* examples\cppunittest\TestDecoratorTest.h:
* examples\cppunittest\TestFailureTest.h:
* examples\cppunittest\TestResultCollectorTest.h:
* examples\cppunittest\TestResultTest.h:
* examples\cppunittest\TestSetUpTest.h:
* examples\cppunittest\TestSuiteTest.h:
* examples\cppunittest\XmlOutputterTest.h:
* examples\cppunittest\XmlOutputterTest.cpp:
* examples\cppunittest\XmlUniformizerTest.h:
* examples\cppunittest\XmlUniformizerTest.cpp: changed base class for fixture
from TestCase to TestFixture.

* examples\hierarchy\BoardGameTest.h:
* examples\hierarchy\ChessTest.h:
* examples\hierarchy\main.cpp: updated to use HelperMacros for correct
fixture instantiation (the ChessBoard::testReset test case was using
BoardGame fixture instance instead of ChessBoard).

1 files changed, 67 insertions, 0 deletions

diff --git a/include/cppunit/TestFixture.h b/include/cppunit/TestFixture.h
index db763de..309df2c 100644
--- a/include/cppunit/TestFixture.h
+++ b/include/cppunit/TestFixture.h
@@ -11,6 +11,73 @@ namespace CppUnit {
  * A TestFixture is used to provide a common environment for a set
  * of test cases.
  *
+ * To define a test fixture, do the following:
+ * - implement a subclass of TestCase 
+ * - the fixture is defined by instance variables 
+ * - initialize the fixture state by overriding setUp
+ *   (i.e. construct the instance variables of the fixture)
+ * - clean-up after a test by overriding tearDown.
+ *
+ * Each test runs in its own fixture so there
+ * can be no side effects among test runs.
+ * Here is an example:
+ * 
+ * \code
+ * class MathTest : public CppUnit::TestFixture {
+ * protected:
+ *   int m_value1;
+ *
+ * public:
+ *   MathTest() {}
+ *
+ *   void setUp () {
+ *     m_value1 = 2;
+ *     m_value2 = 3;
+ *   }
+ * }
+ * \endcode
+ *
+ * For each test implement a method which interacts
+ * with the fixture. Verify the expected results with assertions specified
+ * by calling CPPUNIT_ASSERT on the expression you want to test:
+ * 
+ * \code
+ * public: 
+ *   void testAdd () {
+ *     int result = m_value1 + m_value2;
+ *     CPPUNIT_ASSERT( result == 5 );
+ *   }
+ * \endcode
+ * 
+ * Once the methods are defined you can run them. To do this, use
+ * a TestCaller.
+ *
+ * \code
+ * CppUnit::Test *test = new CppUnit::TestCaller<MathTest>( "testAdd", 
+ *                                                          &MathTest::testAdd );
+ * test->run();
+ * \endcode
+ *
+ *
+ * The tests to be run can be collected into a TestSuite. 
+ * 
+ * \code
+ * public: 
+ *   static CppUnit::TestSuite *MathTest::suite () {
+ *      CppUnit::TestSuite *suiteOfTests = new CppUnit::TestSuite;
+ *      suiteOfTests->addTest(new CppUnit::TestCaller<MathTest>(
+ *                              "testAdd", &MathTest::testAdd));
+ *      suiteOfTests->addTest(new CppUnit::TestCaller<MathTest>(
+ *                              "testDivideByZero", &MathTest::testDivideByZero));
+ *      return suiteOfTests;
+ *  }
+ * \endcode
+ * 
+ * A set of macros have been created for convenience. They are located in HelperMacros.h.
+ *
+ * \see TestResult, TestSuite, TestCaller,
+ * \see CPPUNIT_TEST_SUB_SUITE, CPPUNIT_TEST, CPPUNIT_TEST_SUITE_END, 
+ * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_EXCEPTION, CPPUNIT_TEST_FAIL.
  */
 class CPPUNIT_API TestFixture
 {