Writing Test Plug-in

Detailed Description

• 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 one 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.

Define Documentation

 #include <cppunit/include/plugin/TestPlugIn.h>
 CPPUNIT_PLUGIN_EXPORT CppUnitTestPlugIn *CPPUNIT_PLUGIN_EXPORTED_NAME(void)
 {
 ...
 return &myPlugInInterface;
 }

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

 CppUnitTestPlugIn *CPPUNIT_PLUGIN_EXPORTED_NAME(void);

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

Typedef Documentation