Writing Test Plug-in

Classes
struct	CppUnitTestPlugIn
	Test plug-in interface.This class define the interface implemented by test plug-in. A pointer to that interface is returned by the function exported by the test plug-in. More...
class	TestPlugInDefaultImpl
	Default implementation of test plug-in interface.Override getSuiteName() to specify the suite name. Default is "All Tests". More...

Macros
#define	CPPUNIT_PLUGIN_EXPORT   extern "C"
	A macro to export a function from a dynamic library.
#define	CPPUNIT_PLUGIN_EXPORTED_NAME   cppunitTestPlugIn
	Name of the function exported by a test plug-in.The signature of the exported function is:
#define	CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL(TestPlugInInterfaceType)
	Implements the function exported by the test plug-in.
#define	CPPUNIT_PLUGIN_IMPLEMENT()
	Implements and exports the test plug-in interface.This macro exports the test plug-in function using the subclass, and implements the 'main' function for the plug-in using CPPUNIT_PLUGIN_IMPLEMENT_MAIN().

Typedefs
typedef CppUnitTestPlugIn *(*	TestPlugInSignature )()
	Type of the function exported by a plug-in.

---

Detailed Description

Creating a test plug-in is really simple:

• make your project a dynamic library (with VC++, choose Win32 Dynamic Library in the project wizard), and link against the dynamic library version of CppUnit (cppunit*_dll.lib for VC++).
• in a cpp file, include TestPlugIn.h, and use the macro CPPUNIT_PLUGIN_IMPLEMENT() to declare the test plug-in.
• That's it, you're done! All the tests registered using the TestFactoryRegistry, CPPUNIT_TEST_SUITE_NAMED_REGISTRATION, or CPPUNIT_TEST_SUITE_REGISTRATION will be visible to other plug-in and to the DllPlugInRunner.

Example:

 #include <cppunit/include/plugin/TestPlugIn.h>

 CPPUNIT_PLUGIN_IMPLEMENT();

The interface CppUnitTestPlugIn is automatically implemented by the previous macro. You can define your own implementation.

To provide your custom implementation of the plug-in interface, you must:

• create a class that implements the CppUnitTestPlugIn interface
• use CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL() with your class to export the plug-in interface
• implements the 'main' function with CPPUNIT_PLUGIN_IMPLEMENT_MAIN().

Some of the reason you may want to do this:

• You do not use the TestFactoryRegistry to register your test.
• You want to create a custom listener to use with DllPlugInRunner.
• You want to do initialize some globale resources before running the test (setting up COM for example).

See CppUnitTestPlugIn for further detail on how to do this.

Creating your own test plug-in with VC++:

• Create a new "Win32 Dynamic Library" project, choose the empty template
• For the Debug Configuration, add cppunitd_dll.lib to 'Project Settings/Link/Object/Libariries modules', and for the Release Configuration, add cppunit_dll.lib.
• For All Configuration, in 'C++/Preprocessor/Preprocessors definitions', add the symbol 'CPPUNIT_DLL' at the end of the line (it means that you are linking against cppunit dll).
• Create a 'main' file that contains:

  #include <cppunit/plugin/TestPlugIn.h>
  
  CPPUNIT_PLUGIN_IMPLEMENT();

• Add your tests
• You're done !

See examples/simple/simple_plugin.dsp for an example.

Notes to VC++ users:

• you can run a post-build check on the plug-in. Add the following line to your post-build tab: "DllPlugInTesterd_dll.exe $(TargetPath)". DllPlugInTesterd_dll.exe need to be some place were it can be found (path, ...), or you need to indicate the correct path. is the filename of your plug-in.
• you can debug your DLL, set the executable for debug session to the plug-in runner, and the name of the DLL in the program arguments ( won't work this time).

How does it works ?

When CppUnit is linked as a DLL, the singleton used for the TestFactoryRegistry is the same for the plug-in runner (also linked against CppUnit DLL). This means that the tests registered with the macros (at static initialization) are registered in the same registry. As soon as a DLL is loaded by the PlugInManager, the DLL static variable are constructed and the test registered to the TestFactoryRegistry.

After loading the DLL, the PlugInManager look-up a specific function exported by the DLL. That function returns a pointer on the plug-in interface, which is later used by the PlugInManager.

See also:

Creating TestSuite.

---

Macro Definition Documentation

#define CPPUNIT_PLUGIN_EXPORT   extern "C"

A macro to export a function from a dynamic library.

This macro export the C function following it from a dynamic library. Exporting the function makes it accessible to the DynamicLibraryManager.

Example of usage:

 #include <cppunit/include/plugin/TestPlugIn.h>

 CPPUNIT_PLUGIN_EXPORT CppUnitTestPlugIn *CPPUNIT_PLUGIN_EXPORTED_NAME(void)
 {
   ...
   return &myPlugInInterface;
 }

#define CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL

(

TestPlugInInterfaceType

)

Value:

CPPUNIT_PLUGIN_EXPORT CppUnitTestPlugIn *CPPUNIT_PLUGIN_EXPORTED_NAME(void)  \
  {                                                                            \
    static TestPlugInInterfaceType plugIn;                                     \
    return &plugIn;                                                            \
  }                                                                            \
  typedef char __CppUnitPlugInExportFunctionDummyTypeDef

Implements the function exported by the test plug-in.

#define CPPUNIT_PLUGIN_EXPORTED_NAME   cppunitTestPlugIn

Name of the function exported by a test plug-in.The signature of the exported function is:

 CppUnitTestPlugIn *CPPUNIT_PLUGIN_EXPORTED_NAME(void);

#define CPPUNIT_PLUGIN_IMPLEMENT

(

)

Value:

CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL( CPPUNIT_NS::TestPlugInDefaultImpl );  \
  CPPUNIT_PLUGIN_IMPLEMENT_MAIN()

Implements and exports the test plug-in interface.This macro exports the test plug-in function using the subclass, and implements the 'main' function for the plug-in using CPPUNIT_PLUGIN_IMPLEMENT_MAIN().

When using this macro, CppUnit must be linked as a DLL (shared library). Otherwise, tests registered to the TestFactoryRegistry in the DLL will not be visible to the DllPlugInTester.

See also:

CppUnitTestPlugIn

CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL(), CPPUNIT_PLUGIN_IMPLEMENT_MAIN().

---

Typedef Documentation

typedef CppUnitTestPlugIn*(* TestPlugInSignature)()

Type of the function exported by a plug-in.