''' 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 to run by the DllPlugInTester
 * specific test-listener to use when running the tests with the DllPlugInTester.

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

 Additional test listener can be provided as plug-in to the DllPlugInTester. See  examples/ClockerPlugIn for an example that measure 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.

== 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 ?)

=== 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 test 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).

=== 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 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? ===
What languague are you using?  CppUnit is designed for [:CeePlusPlus: C++] applications alone.  The [http://cruisecontrol.sourceforge.net/index.html CruiseControl page on SourceForge] claims that CruiseControl is for [:JavaLanguage: Java] programs, so [:JayUnit: JUnit] and Ant are better fits (the CruiseControl documentation includes instructions for doing this).

There is also a port or CruiseControl to the .Net platform - see the [http://ccnet.sourceforge.net/ SourceForge page].  In that case, a good fit is probably NUnit and NAnt.  There is a page on the
[http://confluence.public.thoughtworks.org/display/CCNET/Welcome%2Bto%2BCruiseControl.NET CruiseControl Wiki]
that describes how to 
[http://confluence.public.thoughtworks.org/display/CCNET/Using+CruiseControl.NET+with+NUnit Use CruiseControl.NET with NUnit].

If you still need that integratation, then you have some work to do:
 1. Add the CppUnit project to the builds
 2. Add running the CppUnit executable to the build loop, using XML output
 3. Ensure that CruiseControl is configured to read the XML output.
You may have better luck looking at the CruiseControl documentation, wiki, and mailing lists, to determine how to accomplish these steps.
