Using TestInstanceDll
[Using instructions]

The Win32 DLL "TestInstanceDll.DLL" is responsible for creating and storing singleton instances of TestUtility objects. This is important when running a test environment which wants to make use of the test utilities also within some DLLs. More...

Collaboration diagram for Using TestInstanceDll:

The Win32 DLL "TestInstanceDll.DLL" is responsible for creating and storing singleton instances of TestUtility objects. This is important when running a test environment which wants to make use of the test utilities also within some DLLs.

Motivation:

Most of the TestUtilities are used as singletons in order to give simple access to the same object from any piece of your test code. Per default the following simple singleton pattern is used:

 class TestEvents
 {...
 static TestEvents* Get (void)
 {if (!s_pTestEvents) s_pTestEvents = new TestEvents;
  return s_pTestEvents;}
 static TestEvents* s_pTestEvents;
 ...}

This works well as long as you use the test utilities only within your main application. When making use of them also in user written DLL code the problem will arise, that each DLL gets its own singleton instance when calling TestEvents::Get(). In most cases this is not what you want. Usually you are interested to use singleton instances being unique within your whole Win32 process.

Solution:

Instead of storing simple static class members, instances are created and stored within the separate TestInstanceDLL.

To leave the client code unaffected the access to the instance DLL is encapsulated in the Get() methods and the changed behaviour is activated via preprocessor define USE_TEST_INSTANCE_DLL:

 // file TestEvents.h:

 // Declaration of methods within TestInstanceDll
 #ifdef USE_TEST_INSTANCE_DLL
 #    include "TestToolBox/TestInstanceDll.h"
 #endif
 
 class TestEvents
 {...
 #ifdef USE_TEST_INSTANCE_DLL
     static TestEvents* CreateNewInstanceForUsageInDll(void){return new TestEvents;};
     static TestEvents* Get (void)
     {return TTB_GetInstance_TestEvents();}
 #else
     static TestEvents* Get (void)
     {if (!s_pTestEvents) s_pTestEvents = new TestEvents;
      return s_pTestEvents;}
     static TestEvents* s_pTestEvents;
 #endif
 ...}

 // Use static memeber only when running without TestInstanceDLL
 #ifndef USE_TEST_INSTANCE_DLL
 __declspec(selectany) TestEvents* TestEvents::s_pTestEvents = 0;
 #endif

Necessary steps for using TestUtilities within DLLs:

• generate TestInstanceDLL and / or create dependency of your test project from it
• set define USE_TEST_INSTANCE_DLL within all your test projects
• currently the test utilities are used as explicit classes (and not only via virtual member functions). Therefore all projects have to include the implementation code (e.g. TestEventsImpl.h) and/or link with the used test libraries.
• access singleton instances via static class methods Get() (e.g. TestEvents::Get()); this is no difference compared to usage within a single main app!

See also:

TestInstanceDll.h (file documentation)

TestEnvWithMultipleDlls (test app)