1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

    15 *

    16 */

    17 #ifndef SYMBIANUNITTEST_H

    18 #define SYMBIANUNITTEST_H

    19 

    20 // INCLUDES

    21 #include <symbianunittestinterface.h>

    22 #include <symbianunittestmacros.h>

    23 #include <e32base.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class CSymbianUnitTestResult;

    27 

    28 // CLASS DECLARATION

    29 /**

    30 * The base class for unit test classes.

    31 * The classes inheriting from this class should call 

    32 * CSymbianUnitTest::ConstructL from their ConstructL.

    33 * Although the functions implemented in this class 

    34 * for unit test assertions and adding test cases 

    35 * can be called directly from the subclasses,

    36 * the macros defined in symbianunittestmacros.h should be used instead.

    37 *

    38 * @lib symbianunittestfw.lib

    39 */

    40 class CSymbianUnitTest : public CBase, public MSymbianUnitTestInterface

    41     {

    42     public: // Typedefs

    43     

    44         typedef void ( CSymbianUnitTest::*FunctionPtr )();      

    45     

    46     public: // Destructor

    47 

    48         /**

    49         * Destructor

    50         */        

    51         IMPORT_C ~CSymbianUnitTest();

    52     

    53     public: // From MSymbianUnitTestInterface

    54 

    55         /**

    56         * Function called by the framework to execute 

    57         * the unit tests in the subclass.

    58         * There is no need to call this function directly 

    59         * from the unit test classes.

    60         * 

    61         * @param aObserver an observer for the test progress 

    62         * @param aResult the test result

    63         * @param aFailureSimulation the type of failure simulation to be used

    64 	* @param aTestCaseNames the test cases to run

    65 	* @param aTimeout the time out value for test execution

    66         */        

    67         IMPORT_C void ExecuteL( 

    68             MSymbianUnitTestObserver& aObserver,

    69             CSymbianUnitTestResult& aResult,

    70             MSymbianUnitTestInterface::TFailureSimulation aFailureSimulation,

    71 	    const CDesCArray& aTestCaseNamesi,

    72 	    TInt aTimeout );

    73 

    74         /**

    75         * Returns the number of unit test cases contained in this object. 

    76         * @return The number of unit test cases in this object

    77         */        

    78         IMPORT_C TInt TestCaseCount();

    79 

    80         /**

    81         * @return The name of this unit test class

    82         */        

    83         IMPORT_C const TDesC& Name() const;

    84 

    85         

    86     protected: // Constructors

    87 

    88         /**

    89         * Constructor

    90         */        

    91         IMPORT_C CSymbianUnitTest();

    92         

    93         /**

    94         * This function should be called 

    95         * from the ConstructL of the subclass

    96         * 

    97         * @param aName the name of the unit test class

    98         */        

    99         IMPORT_C void ConstructL( const TDesC8& aName );

   100     

   101     protected: // New functions    

   102 

   103         /**

   104         * This function should be overidden in the actual unit test classes.

   105         * It is the default setup function that gets executed 

   106         * by the framework before each unit test case.

   107         */        

   108         IMPORT_C virtual void SetupL();

   109         

   110         /**

   111         * This function should be overidden in the actual unit test classes.

   112         * It is the default teardown function that gets executed 

   113         * by the framework after each unit test case.

   114         */        

   115         IMPORT_C virtual void Teardown();

   116 

   117         /**

   118         * Checks whteher the test case is being run using memory 

   119         * allocation failure simulation.

   120         * @return ETrue if the test case is being run using memory 

   121         *         allocation failure simulation, EFalse if not

   122         */        

   123         IMPORT_C TBool IsMemoryAllocationFailureSimulationUsed() const;

   124         

   125         /**

   126         * Adds a new unit test case to this unit test.

   127         * Use macro ADD_SYMBIAN_UT in symbianunittestmacros.h 

   128         * instead to avoid the need to pass 

   129         * the name of the unit test case as a parameter.

   130         * 

   131         * @param aName the name of the unit test case

   132         * @param aSetupFunction a function pointer to the setup function 

   133         *        that will be executed before the actual unit test case

   134         * @param aTestFunction a function pointer to the unit test case

   135         * @param aTeardownFunction a function pointer to the teardown function

   136         *        that will be executed after the actual unit test case

   137         */        

   138         IMPORT_C void AddTestCaseL( 

   139             const TDesC& aName,

   140             CSymbianUnitTest::FunctionPtr aSetupFunction,

   141             CSymbianUnitTest::FunctionPtr aTestFunction,

   142             CSymbianUnitTest::FunctionPtr aTeardownFunction );

   143 

   144         /**

   145         * Asserts that two TInt values are equal.

   146         * Leaves with a Symbian unit test framework specific error code

   147         * if the values are not equal.

   148         * In case of a failed assertion, the framework records 

   149         * the failure reason, line number and file name to the test results.

   150         * Use macro SYMBIAN_UT_ASSERT_EQUALS in symbianunittestmacros.h 

   151         * instead to avoid the need to pass the other parameters 

   152         * than the actual asserted values.  

   153         * 

   154         * @param aExpectedValue the expected value

   155         * @param aActualValue the actual value

   156         * @param aLineNumber the line number of the assertion

   157         * @param aFileName the name of the file where the assertion is located

   158         */        

   159         IMPORT_C void AssertEqualsL( 

   160             TInt aExpectedValue,

   161             TInt aActualValue,

   162             TInt aLineNumber,

   163             const TDesC8& aFileName );        

   164 

   165         /**

   166         * Asserts that two TDesC8 values are equal.

   167         * Leaves with a Symbian unit test framework specific error code

   168         * if the values are not equal.

   169         * In case of a failed assertion, the framework records 

   170         * the failure reason, line number and file name to the test results.

   171         * Use macro SYMBIAN_UT_ASSERT_EQUALS in symbianunittestmacros.h 

   172         * instead to avoid the need to pass the other parameters 

   173         * than the actual asserted values.  

   174         * 

   175         * @param aExpectedValue the expected value

   176         * @param aActualValue the actual value

   177         * @param aLineNumber the line number of the assertion

   178         * @param aFileName the name of the file where the assertion is located

   179         */ 

   180         IMPORT_C void AssertEqualsL(

   181             const TDesC8& aExpectedValue,

   182             const TDesC8& aActualValue, 

   183             TInt aLineNumber, 

   184             const TDesC8& aFileName );

   185 

   186         /**

   187         * Asserts that two TDesC16 values are equal.

   188         * Leaves with a Symbian unit test framework specific error code

   189         * if the values are not equal.

   190         * In case of a failed assertion, the framework records 

   191         * the failure reason, line number and file name to the test results.

   192         * Use macro SYMBIAN_UT_ASSERT_EQUALS in symbianunittestmacros.h 

   193         * instead to avoid the need to pass the other parameters 

   194         * than the actual asserted values.  

   195         * 

   196         * @param aExpectedValue the expected value

   197         * @param aActualValue the actual value

   198         * @param aLineNumber the line number of the assertion

   199         * @param aFileName the name of the file where the assertion is located

   200         */        

   201         IMPORT_C void AssertEqualsL(

   202             const TDesC16& aExpectedValue,

   203             const TDesC16& aActualValue,

   204             TInt aLineNumber,

   205             const TDesC8& aFileName );       

   206 

   207         /**

   208         * Asserts that a statement leaves an expected value.

   209         * Leaves with a Symbian unit test framework specific error code

   210         * if the leave code is not the expected one.

   211         * In case of a failed assertion, the framework records 

   212         * the failure reason, line number and file name to the test results.

   213         * Use macro SYMBIAN_UT_ASSERT_LEAVE in symbianunittestmacros.h 

   214         * instead to avoid the need to pass the other parameters 

   215         * than the actual statement that is checked for the leave.  

   216         * 

   217         * @param aStatement textual presentation of the statement

   218         * @param aActualLeaveCode the actual leave code from the statement

   219         * @param aExpectedLeaveCode the expected leave code

   220         * @param aLineNumber the line number of the assertion

   221         * @param aFileName the name of the file where the assertion is located

   222         */        

   223         IMPORT_C void AssertLeaveL(

   224             const TDesC8& aStatement,

   225             TInt aActualLeaveCode,

   226             TInt aExpectedLeaveCode,

   227             TInt aLineNumber,

   228             const TDesC8& aFileName );        

   229        

   230         /**

   231         * Records a failed assertion to the test results and

   232         * leaves with a Symbian unit test framework specific error code

   233         * to quit the execution of the test function.

   234         * Use macro SYMBIAN_UT_ASSERT in symbianunittestmacros.h 

   235         * to perform the actual assertion.  

   236         * 

   237         * @param aFailureMessage the failed assertion as text

   238         * @param aLineNumber the line number of the assertion

   239         * @param aFileName the name of the file where the assertion is located

   240         */        

   241         IMPORT_C void AssertionFailedL( 

   242             const TDesC8& aFailureMessage,

   243             TInt aLineNumber,

   244             const TDesC8& aFileName );        

   245 

   246         /**

   247         * Records a non-leaving statement to the test results and

   248         * leaves with a Symbian unit test framework specific error code

   249         * to quit the execution of the test function.

   250         * This function is called from macro SYMBIAN_UT_ASSERT_LEAVE 

   251         * in symbianunittestmacros.h to record the result of a failed assertion.

   252         * There is usually no need to call this function directly.

   253         * 

   254         * @param aStatement textual presentation of the statement

   255         * @param aLineNumber the line number of the assertion

   256         * @param aFileName the name of the file where the assertion is located

   257         */        

   258         IMPORT_C void RecordNoLeaveFromStatementL(

   259             const TDesC8& aStatement,

   260             TInt aLineNumber,

   261             const TDesC8& aFileName ); 

   262         

   263     private: // Internal class for a unit test function's data

   264         

   265         class CSymbianUnitTestCase : public CBase

   266             {            

   267             public: // Constructors and destructor

   268                 

   269                 static CSymbianUnitTestCase* NewL( 

   270                     const TDesC& aName,

   271                     CSymbianUnitTest::FunctionPtr aSetupFunction,

   272                     CSymbianUnitTest::FunctionPtr aTestFunction,

   273                     CSymbianUnitTest::FunctionPtr aTeardownFunction );

   274                 

   275                 ~CSymbianUnitTestCase();

   276             

   277             public: // New functions

   278                 

   279                 const TDesC& Name() const;

   280                 

   281             public: // Data

   282                 

   283                 CSymbianUnitTest::FunctionPtr iSetupFunction;

   284                 CSymbianUnitTest::FunctionPtr iTestFunction;

   285                 CSymbianUnitTest::FunctionPtr iTeardownFunction;

   286             

   287             private: // Constructors

   288                 

   289                 CSymbianUnitTestCase( 

   290                     CSymbianUnitTest::FunctionPtr aSetupFunction,

   291                     CSymbianUnitTest::FunctionPtr aTestFunction,

   292                     CSymbianUnitTest::FunctionPtr aTeardownFunction );

   293                 void ConstructL( const TDesC& aName );

   294                 

   295             private: // Data

   296                 

   297                 HBufC* iName;

   298             };

   299         

   300         private: // New functions

   301         

   302             HBufC8* NotEqualsMessageLC( const TDesC16& aExpected,

   303                                         const TDesC16& aActual );

   304         

   305             void ExecuteTestCaseInThreadL( 

   306                 CSymbianUnitTestCase& aTestCase,

   307                 CSymbianUnitTestResult& aResult,

   308 	        TInt aTimeout);

   309             

   310             static TInt TestThreadEntryFunction( TAny* aPtr );

   311             

   312             void ExecuteTestCaseL();

   313             

   314             void DoExecuteTestCaseL( TInt& aLeaveCodeFromTest );

   315             

   316             void StartAllocFailureSimulation();

   317             

   318             void StopAllocFailureSimulation();

   319 

   320 	    static TInt TimerThreadEntryFunction( TAny* aPtr);

   321         

   322     private: // Data

   323     

   324         HBufC* iName;

   325         RHeap::TAllocFail iAllocFailureType;

   326         TUint iAllocFailureRate;

   327         TInt iLeakedMemory;

   328         TInt iHeapCellsReservedByAssertFailure;

   329         RPointerArray< CSymbianUnitTestCase > iTestCases;

   330         CSymbianUnitTestResult* iTestResult; // Not owned

   331         CSymbianUnitTestCase* iCurrentTestCase; // Not owned

   332 

   333     private: // Test

   334         

   335         SYMBIAN_UNIT_TEST_CLASS( UT_CSymbianUnitTest )

   336     };

   337 

   338 #endif // SYMBIANUNITTEST_H