1 Conventions for writing test cases and using decorators for them.

     2 

     3 -----------------------------------------------------------------------

     4 

     5 ******************************************

     6 *     WHICH DECORATOR I SHOULD USE       *

     7 ******************************************

     8 #1 Do no use static test decorators. Decorators are used dynamically.

     9   - 1. Ok to use decorator -> Use PRFW_DECORATED_TEST

    10   - 2. nok to use decorator -> Use PRFW_NOT_DECORATED_TEST

    11 

    12 

    13 -----------------------------------------------------------------------

    14 ****************************************

    15 * HOW TO USE THE TEST CONTEXT WRAPPERS *

    16 ****************************************

    17 

    18 Relevant files:

    19 testcaseutils/prfwtestcontextwrapper.h

    20 testcaseutils/prfwtestcontextwrappermgr.h

    21 testcaseutils/prfwtestcontextwrapper.cpp

    22 testcaseutils/prfwtestcontextwrappermgr.cpp

    23    

    24     >>> Feel free to remove unused stuff or add more! <<<

    25 

    26 Main idea: simplify test code by wrapping each testing "context" in one

    27 class which contains:

    28   - prfw client

    29   - prfw context (not the same as testing "context")

    30   - the plugin instance

    31   - event listener

    32   - messenger (see below)

    33   - etc.

    34 

    35 For example usage see:

    36   t_sessionmng

    37   pr_prfwtestprotocol

    38 

    39 Mini how-to:

    40 

    41 1. Create wrappers with wrapper manager using CreateWrapperL call.

    42 

    43 2. Then access the wrappers using GetWrapper( TInt aIndex ). The caller is

    44 responsible for keeping note of which index is used for what (e.g. in

    45 the case of two connections).

    46 

    47 3. Wrapper has methods BindL and UnbindL if you just want to get the

    48    connection up:

    49 

    50    Somewhere, e.g. Setup method:

    51 

    52     iWrapperMgr = CPrFwTestContextWrapperMgr::NewL();

    53     iWrapperMgr->CreateWrapperL();

    54    

    55    Bind:

    56 

    57     CPrFwTestContextWrapper* wrapper0 = iWrapperMgr->GetWrapperL( 0 );

    58     wrapper0->BindL( 0 );

    59 

    60     // now you are "connected to network" (=faked by test plugin)

    61 

    62    Unbind:

    63     

    64     CPrFwTestContextWrapper* wrapper0 = iWrapperMgr->GetWrapperL( 0 );

    65     wrapper0->UnbindL();

    66 

    67     // now you are no longer connected. 

    68 

    69    Destructor:

    70      

    71     delete iWrapperMgr; 

    72 

    73 4. You can access messenger class etc. using the various Get* methods.

    74 

    75     IMPORT_C MXIMPContext* GetContext();

    76     IMPORT_C CPrFwTestStatusEventListener* GetEventListener();

    77     IMPORT_C CPrFwTestMessenger* GetMessenger();

    78     IMPORT_C MXIMPClient* GetClient();

    79     IMPORT_C RArray<TPrFwTestStatusEventSnapshot>* GetStatusTraits();

    80 

    81 5. Other convenience methods are also provided, please see t_sessionmng

    82    for illustrative code. The below method tests the bind with wait.

    83    The Assert* methods are used to check if test protocol plugin was

    84    correctly called.

    85 

    86 Setup:

    87 

    88     iWrapperMgr = CPrFwTestContextWrapperMgr::NewL();

    89     iWrapperMgr->CreateWrapperL();

    90 

    91 Teardown:

    92 

    93     delete iWrapperMgr;

    94 

    95 void T_SessionMng::T_Simple_Bind_Wait_Unbind_L()

    96     {

    97     EUNIT_PRINT( _L("Simple context Bind/Unbind test.") );

    98     EUNIT_PRINT( _L("Client side waits bind completion before issuing unbind.") );

    99 

   100     CPrFwTestContextWrapper* wrapper = iWrapperMgr->GetWrapperL( 0 );

   101     MXIMPContext* context = wrapper->GetContext();

   102     CPrFwTestStatusEventListener* eventListener = wrapper->GetEventListener();

   103     CPrFwTestMessenger* messenger = wrapper->GetMessenger();

   104     

   105     //Do bind, wait and verify events

   106     wrapper->SetupListenerL( EPrFwTestStatusEvents_BindingOk );

   107     messenger->SetNoError(); 

   108 

   109     messenger->SetPluginIndex( 0 );

   110     TUid protocol = { 0x1100ff55 };

   111     TXIMPRequestId reqId = context->BindToL( 

   112             protocol,

   113             _L("www.imps.no/wv"),

   114             _L("user"),

   115             _L("password"),

   116             1 );

   117 

   118     wrapper->WaitRequestAndStackEvents( reqId );

   119     wrapper->VerifyEventStackL( _L8("Binding single context: ") );

   120 

   121     AssertOpenSession( 0 );

   122 

   123     //Verify features availability

   124     MXIMPFeatureInfo* ctxFeats = context->GetContextFeaturesLC();

   125     EUNIT_ASSERT_DESC( ctxFeats->FeatureIds().MdcaCount() > 0, "No features from context" );

   126     CleanupStack::PopAndDestroy(); //ctxFeats

   127 

   128     //Do unbind, wait and verify events

   129     wrapper->SetupListenerL( EPrFwTestStatusEvents_UnbindingOk );

   130     messenger->SetNoError();

   131     reqId = context->UnbindL();

   132 

   133     wrapper->WaitRequestAndStackEvents( reqId );

   134     wrapper->VerifyEventStackL( _L8("Unbinding single context: ") );

   135 

   136     AssertCloseSession( 0 );

   137     AssertPluginDied( 0 );

   138     }

   139 

   140 The Assert* methods can be found from t_sessionmng (they should be moved

   141 elsewhere). See below for messenger functionality.

   142 

   143 -----------------------------------------------------------------------

   144 ***************************************************

   145 * HOW TO USE THE TEST CASE - PLUGIN COMMUNICATION *

   146 ***************************************************

   147 

   148 Relevant files:

   149 testcaseutils/prfwtestmessaging.h    - Keys, value enumerations etc.

   150 testcaseutils/prfwtestmessenger.h    - Messenger header (READ THIS)

   151 testcaseutils/prfwtestmessenger.cpp  - Messenger implementation

   152  

   153     >>> Feel free to remove unused stuff or add more! <<<

   154 

   155 For example usage see:

   156   t_sessionmng

   157   t_presencemng

   158   pr_prfwtestprotocol

   159 

   160 The idea is:

   161   - there's publish & subscribe facility to send messages from

   162     test code to plugin

   163   - test protocol reads the message and changes its behaviour

   164     accordingly, e.g. doing a leave on next HandleRequestCompleted

   165 

   166 More details:

   167 

   168 (prfwtestmessaging.h)

   169 

   170 * TPrFwTestPropertyKeys determines the keys.

   171   You can add more messages here.

   172 

   173 * TPrFwTestPropertyValues determines certain pre-defined values,

   174   e.g. EPrFwPrtValSessionLostReconnect (which is used to cause the

   175   plugin to signal a "session lost, try to reconnect" to the 

   176   Presence Framework.

   177 

   178 * TPrFwTestMsg is the protocol message. It consists of the key specifier

   179   and the value to be set. Currently only integer parameters are

   180   supported.

   181 

   182 * Each CPrFwTestMessenger takes an index into the constructor. This is

   183   needed to create a two-way communications channel from the test case

   184   to plugin and vice versa.

   185 

   186 * Creation of messenger is handled by the wrapper (which is created via

   187   wrapper manager).

   188 

   189 * MINIMAL USAGE:

   190  

   191   * To set "happy path", no errors will be artificially caused:

   192     SetNoError()

   193 

   194   * To make next operation fail with some error code: 

   195     SetError( TInt aErrorCOde )

   196 

   197   * To make next operation leave:

   198     SetLeave( TInt aLeaveCode )

   199 

   200   * Call HandleLeaveL in the test protocol plugin to automatically

   201     leave, if leave was requested. (So you don't have to do 

   202     "GetValueFor.. if (leave){User::Leave..")

   203 

   204   * To set a boolean-valued (1 or 0) key, use SetBoolean. Read with

   205     GetBoolean. These are used to signal the calling of some method,

   206     and to read whether the method was called or not.

   207 

   208   * For generic stuff use SetValueFor and GetValueFor.

   209 

   210 NOTES:

   211 

   212 If you add more keys, BE SURE TO RESET THEM IN THE MESSENGER

   213 CONSTRUCTION. 

   214 

   215 If you use multiple messengers, use different indexes!!!

   216 

   217 Please see t_sessionmng and t_presencemng for details.

   218 

   219 -----------------------------------------------------------------------

   220 ********************************************

   221 * HOW TO USE THE EVENT LISTENER CLASS      *

   222 ********************************************

   223 

   224 There are 2 event listener classes implemented:

   225 CPrFwTestListener

   226 CPrFwTestStatusEventListener

   227 

   228 The context wrapper has support for the CPrFwTestStatusEventListener.

   229 See the description there.

   230 

   231 CPrFwTestListener is the one which is more commonly used in the test cases.

   232 This listener supports creating exact events to be accepted by the test case,

   233 including the data inside the events, so use this class to verify the data.

   234 The event with the expected data can be send to the test protocol using

   235 the filetool, see below.

   236 

   237 The usage of the listener is fairly simple:

   238 

   239     // create the listener since not created by the wrapper

   240     CPrFwTestListener* listener2 = CPrFwTestListener::NewL( context );

   241     CleanupStack::PushL( listener2 );

   242 

   243     // initialize it to accept new events

   244     listener2->Reset();

   245 

   246     // create the event which is expected, here the RequestCompleteEvent

   247     // RequestID is not checked in the assertion! 

   248     TXIMPRequestId reqIdDummy;

   249     CXIMPRequestCompleteEventImp* evReqComplete =

   250                     CXIMPRequestCompleteEventImp::NewLC( reqIdDummy );

   251                     

   252     // add the created event to the listener, ownership is transfered

   253     listener2->ExpectL( evReqComplete );

   254     CleanupStack::Pop( evReqComplete );

   255 

   256     // call the desired XIMPFW method 

   257     TXIMPRequestId reqId = presPub->SubscribePresenceWatcherListL();

   258 

   259     // Wait for events on the request

   260     // Assertion is done based on the content on the event by comparing

   261     // the received event with the expected one.

   262     EUNIT_ASSERT_DESC( KErrNone == listener2->WaitAndAssertL(), "Subscribe failed" );

   263     

   264     // clean it up

   265     CleanupStack::PopAndDestroy( listener2 );

   266 

   267 -----------------------------------------------------------------------

   268 ********************************************

   269 * HOW TO USE THE PSEUDO-IPC FILETOOL CLASS *

   270 ********************************************

   271 

   272 The FileTool writes given serialized objects to a directory. It can also

   273 internalize them. Thus with FileTool you can check whether the presence

   274 data you put into the framework goes through OK.

   275 

   276 Server could also be used, and in a perfect world such a thing would

   277 have been written with big smiles, but in reality it would take much

   278 much longer to create and debug than this kind of FileTool, so here's

   279 FileTool!

   280 

   281 Relevant files:

   282 testcaseutils/prfwtestfiletool.h

   283 testcaseutils/prfwtestfiletool.cpp

   284 

   285 As of now, the FileTool is not yet integrated to any tests.

   286 

   287 FileTool API:

   288 

   289 Let's say you choose to use index 0. If you have two connections or

   290 such, then you would create two FileTools with indexes 0 and 1,

   291 respectively.

   292 

   293 Wipe old stuff away, destroy the directory, etc.:

   294   - CleanL( 0 )

   295 

   296 Create the new directory:

   297   - PrepareL( 0 ) 

   298 

   299 Store an object:

   300   - StoreL( 0, externalizedObjectAsTDesC8 )

   301 

   302 Get number of objects stored:

   303   - numObjects = NumObjectsL( 0 )

   304 

   305 Restore an object:

   306   - i is a looping from 0..NumObjectsL( 0 )-1.

   307   - CXIMPApiEventBase* restored = RestoreLC( 0, i );

   308   - For example in this way you can check the whole directory.

   309 

   310 After the object is restored, compare in test code side to that which it

   311 SHOULD HAVE been.

   312 

   313 -----------------------------------------------------------------------

   314 ********************************************

   315 * HOW TO USE THE "ROBUSTNESS HELPERS"      *

   316 ********************************************

   317 

   318 It's good to kill the servers and removing all temporary FileTool files

   319 when starting a test case. This ensures that there are no unexpected

   320 messages, events or state lingering in the server.

   321 

   322 1. Add to MMP file:

   323 

   324   #include "..\..\tsrcutils\processmaster\pm.h"

   325 

   326 If your stuff is not in internal\tsrc, then view the pm.h contents and

   327 adapt it.

   328 

   329 2. Add to test case:

   330 

   331   #include "prfwtestrobustnesstools.h"

   332 

   333 3. Add to test case SetupL as the first line:

   334 

   335   PrfwTestRobustness::DoPreCleaning();

   336