''' Frequently Asked Questions about CppUnit '''

Feel free to add questions or answer ones that already exist

[[TableOfContents]]

== Concepts ==

=== What are Test Plug-ins for ===

Test plug-ins can provide two services:
 * test cases to run for the DllPlugInTester
 * specific test listeners to use when running the tests with the DllPlugInTester.

 This provides a very convenient mean to run unit tests contained in a dynamic library as a post-build step. Also the DllPlugInTester contains multiple command-line options to help getting the progress/output you want.

 Additional test listeners can be provided as plug-in to the DllPlugInTester. See {{{examples/ClockerPlugIn}}} for an example that measures how long each test case takes to run and integrate those measurement in the xml output.

Items 2 and 3 of CppUnit2 features provide more details: http://cppunit.sourceforge.net/cppunit2/features.html.

== Workings ==

=== How is flow of control when CppUnit runs tests? What can run in parallel, what is forced to be sequential. (Answer needed) ===

CppUnit seems to create one instance of the test class for each test function in it. Also, it seems to run setUp and tearDown in these different instances in parallell. Though it can't run tests in parallell, can it? I have trouble using global resource in test, which seems to be caused by
setUp/tearDown running in parallel. Would be nice to know exactly what CppUnit did here. Please replace this with a specification.

== How do I? ==

=== How do I run a subset of tests ===

Non interactive test runners accept one or many test cases to run. You need to figure out which one need to be run and only add those. The base Test class contains some 'find' methods which can be used to locate a specific test/suite.

=== How would I use CppUnit for automated testing (answer needed) ===
(more precision needed: what is exactly the meaning of automated testing ?)
Well, CppUnit is all about automatic tests, just avoid user interactions, visual checking and blocking (system) calls.

=== How do I print debug info (answer needed) ===
Like what test is it that makes an segmentation fault?

I see mostly two options:
 * run the tests using BriefTestProgressListener which print the name of each test before running it. In case of crash, the last name is the one of the test that crashed.
 * Implements a Protector used to capture system specific exception that occurs during crash (hard to implement this portably).

Here is a code fragment/diff showing how to add this to some of the cookbook recipes:
{{{#!cplusplus
+#include <cppunit/TestResult.h>
+#include <cppunit/BriefTestProgressListener.h>

... other setup code here ...

  // Adds the test to the list of test to run
  CppUnit::TextTestRunner runner;
  runner.addTest( suite );

+  // Shows a message as each test starts
+  CppUnit::BriefTestProgressListener listener;
+  runner.eventManager().addListener( &listener );
}}}

=== How do I stop abort() being called when a test fails? ===
Enable exceptions.  In GCC, compile with -fexceptions.  In VC++, use /EHsc (Enable C++ exceptions under Code Generation).

=== How do I get the name of the test from within the setUp function? ===
Neither the setUp() nor tearDown() functions know the name of the test being called, so you can't customize these for different tests.  If you need to setup the environment for a single test, include that setup with the test.  If several tests share the environment, then consider private data and functions, with each test calling the shared setup function.  If all but a few need the same environment, then consider putting it in setUp() and tearDown(), and adding extra code to the non-cooperative tests.  

=== How can I create test hierarchy (suite of tests that contains other suites)? ===
Use the CPPUNIT_TEST_SUB_SUITE() macro.  For instance:
{{{#!cplusplus
 #include <cppunit/extensions/HelperMacros.h>

 class MyTest {
   CPPUNIT_TEST_SUITE( MyTest );
   CPPUNIT_TEST( testBasic );
   CPPUNIT_TEST_SUITE_END();
 public:
   void testBasic();
 };

 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();
 };
}}}
My``Test will run testBasic, while My``Sub``Test will run testAdd, testSub, and testBasic.  See the [http://cppunit.sourceforge.net/doc/lastest/group___writing_test_fixture.html Writing Test Fixture] section of the documentation.  If you are testing a class heirarchy with abstract classes, CPPUNIT_TEST_SUITE_END_ABSTRACT() may also be useful, to create a test fixture that exercises pure virtual functions.

== Working With Other Programs ==

=== Is there a program, like JUnitDoclet, that will generate test skeletons automatically? ===
Probably not.  J``Unit``Doclet probably uses reflection, the ability of Java code to report information about itself.  For instance, you can query a Java class for all the public functions, then write a test framework with a test for each function.  

We don't have anything like reflection in C or C++, so writing a test skeleton generator would be a similar effort to writing a C/C++ compiler.  This is difficult, but not impossible, and there are probably commercial tools that generate test skeletons for their own programs.  But none for CppUnit, that we know of.

=== Can I integrate CppUnit with CruiseControl? ===
Yes, with a bit of leg work.

 1. You must be using a build process capable of being launched by cruisecontrol (nant works well)
 2. From within that build you should build cppunit, and build and run the unit tests.
 3. By setting the unit tests to output in junit format to a log directory (for example, using the xslt from the [http://sourceforge.net/project/shownotes.php?group_id=11795&release_id=342398 latest development release], or by modifying cppunit) cruise control will display nicely formatted test results. (Don't forget to [http://cruisecontrol.sourceforge.net/main/configxml.html#merge merge] the log results)

Using cruisecontrol as a continous integration process is very nice, even when compared to running nightly builds. Seeing the build results appear very quickly after checkins on integration branches is _very_ nice.
