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

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

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

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// This file contains the definition of the class CUnitTest

// This file comment is for DOxygen only and is ignored by EDoc.

// 

//

/**

 @test

*/

#ifndef __UNITTEST_H__

#define __UNITTEST_H__

#include <e32base.h>

#include <f32file.h>

#include <e32test.h>

#include <ecom/test_bed/testutilities.h>

#include <ecom/test_bed/transition.h>

#include <ecom/test_bed/unittestinfo.h>

#include <ecom/test_bed/unittestobserver.h>

class CTransition;

class CDataLogger;

/**

	@internalAll	

	Comments : Abstract base class upon which a test developer can base his unit test class.

	Most functionality is implemented in this base class, to write a derived class just implement 

	a NewL() and a ConstructL() on the new object.  ConstructL() should first call 

	UnitTestConstructL() and then create the transitions which make up this unit test.

	Eg. 

	@code

		_LIT(KExampleUnitTest,"CExampleUnitTest");

		CExampleUnitTest* CExampleUnitTest::NewL(CDataLogger&		aDataLogger,

												 MUnitTestObserver& aObserver)

			{

			CExampleUnitTest* self = new(ELeave) CExampleUnitTest(aDataLogger,

																  aObserver);

			self->ConstructL();

			return self; 

			}

		TInt CExampleUnitTest::RunError(TInt aError)

			{

			// The RunL left so chain to the base first and then cleanup

			TInt error = CUnitTest::RunError(aError);	// Chain to base

			delete iTestClass;

			iTestClass = NULL;

			return error;

			}

		CExampleUnitTest::~CExampleUnitTest()

			{

			// delete the test context information

			delete iStateAccessor;

			delete iUTContext;

			delete iValidator;

			// Simply delete our test class instance

			delete iTestClass;

			}

		CExampleUnitTest::CExampleUnitTest(CDataLogger& aDataLogger,

											MUnitTestObserver& aObserver, 

											MStateAccessor& aStateAccessor)

		: CUnitTest(KExampleUnitTest, aDataLogger, aObserver, aStateAccessor)

			{

			//Do nothing

			}

		// Now the Individual transitions need to be added.

		void CExampleUnitTest::ConstructL()

			{

			// Perform base class initialization

			UnitTestConstructL();

			// Create the input variables to the transition creation

			iStateAccessor = new(ELeave) TExampleStateAccessor();

			iUTContext = new(ELeave) CUnitTestContext(iDataLogger, *iStateAccessor, *this);

			iValidator = new(ELeave) TTransitionValidator(*iUTContext);

			// Add the Transitions in the order they are to run

			// C'tor first, D'tor last...

			AddTransitionL(new(ELeave)CExampleNewLTransition(*iUTContext, *iValidator, iTestClass));

			AddTransitionL(new(ELeave)CExampleDtorTransition(*iUTContext, *iValidator, iTestClass));

			}

	@endcode

 */

class CUnitTest : public CTimer, public MTransitionObserver

	{

public:

/**

	@fn				~CUnitTest()

	Intended Usage	:	Standard Destructor

	@since			7.0

 */

	IMPORT_C ~CUnitTest();

/**

	@fn				void RunTest(TTimeIntervalMicroSeconds32 aTimeAfter = 0)

	Intended Usage	:	Sets up the Timer Object request to cause the test to run.

	Error Condition	:	

	@since			7.0

	@param			aTimeAfter The time after which the unit test should be run

	@pre 			None

	@post			RunL() will be set up to run after the specified time.

 */

	IMPORT_C void RunTest(TTimeIntervalMicroSeconds32 aTimeAfter = 0);

/**

	@fn				inline const TDesC& UnitTestName() const

	Intended Usage	:	Return the name identifier of this Unit Test

	Error Condition	:	

	@since			7.0

	@return			TDesC& The identifier of this unit test

	@pre 			None

 */

	inline const TDesC& UnitTestName() const;

/**

	@fn				TransitionSetL() const

	Intended Usage	:	Creates and returns a CUnitTestInfo containing information on this 

					UnitTest.  Passes ownership of the CUnitTestInfo to the calling object.

	Error Condition	:	

	@since			7.0

	@return			CUnitTestInfo* Information on this unit test

	@pre 			None

 */

	CUnitTestInfo* TransitionSetL() const;

/**

	@fn				GetCurrentTransition() const

	Intended Usage	: Retrieve a reference to the transition whose RunL() method 

					is currently executing.

					This allows transition information can be retrieved and 

					RepeatOnce() can be called on the transition.

	@since			7.0

	@return			CTransition& a reference to the currently executing transition. 

	@pre 			None

	@post			No change.

 */

	IMPORT_C CTransition& GetCurrentTransition() const;

/**

	@fn				SetCurrentTransition(CTransition& aTransition)

	Intended Usage	: MTransitionObserver override that recieves a reference to

					the transition whose RnunL() method is executing.

					This allows transition information can be retrieved and 

					RepeatOnce() can be called on the transition.

	@since			7.0

	@param			aTransition A reference to the transition to set as current

	@return			void 

	@pre 			None

	@post			aTransition will be recorded as the currently 

					executing transition.

 */

	IMPORT_C void SetCurrentTransition(CTransition& aTransition);

/**

	@fn				Complete(CTransition& aTransition, TInt aAsyncPostCheckError)

	Intended Usage	: MTransitionObserver override that is called to indicate 

					that an asynchronous function on the specified

					transition has completed.	

	@since			7.0

	@param			aTransition The transition which has completed an async function.

	@param			aAsyncPostCheckError An error code from the second phase of post-condition

					validation done after the transition's asynchronous request had completed.

					Used for asynchronous transitions only - for synchronous transitions, 2-phase

					post-condition checking does not apply, and a value of KErrNone is supplied.

	@pre 			The specified transition has launched an asynchronous function

	@post			The transition has fully completed, if all transitions are complete

					then the unittest is complete.

 */

	IMPORT_C void Complete(CTransition& aTransition, TInt aAsyncPostCheckError);

/**

	@fn				SetParametersL(TAny* aParams)

	Intended Usage	:	Should be overridden in the derived unit test to accept parameters

	to be used in the unit test.  The default implementation is to do nothing.

	Error Condition	:	

	@since			7.0

	@param			aParams The parameter block which the unit test will use

	@pre 			This CUnitTest is constructed

	@post			The parameters are stored and ready for use in the test

 */

	IMPORT_C virtual void SetParametersL(TAny* aParams);

/**

	@fn				inline void SetRtest(RTest* aRTest)

	Intended Usage	:	Used by Component Tester to initialise the iRTest

					attribute so it coul dbe used in assessing unit test results.

	Error Condition	:	

	@since			7.0s

	@param			aRTest	Pointer to RTest object 

	@pre 			None

	@post			None

 */

	inline void SetRTest(RTest* aRTest);

/**

	@fn				PrepareUnitTestL()

	Intended Usage	:	May be overidden in the derived unit test to perform any unit test

					specific environment setup (eg copying data files into place).  The 

					default implementation is to do nothing.

	Error Condition	:	Depends on implementation.

	@since			7.0

	@pre 			This CUnitTest is constructed

	@post			Depends on implementation

 */

	virtual void PrepareUnitTestL();

protected:

/**

	@fn				inline CUnitTest(const TDesC&		  aName, 

									 CDataLogger&		  aDataLogger, 

									 MUnitTestObserver&   aUnitTestObserver)

	Intended Usage	:	Standard Constructor

	Error Condition	:	

	@param			aName The identifier of this unit test

	@param			aDataLogger Provides the logging capability

	@param			aUnitTestObserver Is informed when this unit test completes

	@since			7.0

 */

	inline CUnitTest(const TDesC&		  aName, 

					 CDataLogger&		  aDataLogger, 

					 MUnitTestObserver&   aUnitTestObserver);

/**

	@fn				virtual void RunL()

	Intended Usage	:	Implementation of CActive method.  Each iteration of RunL() causes one transition

	to be run.

	Error Condition	:	

	@since			7.0

	@pre 			Preconditions are ensured by RunTest()

	@post			Transition has been activated

 */

	IMPORT_C virtual void RunL();

/**

	@fn				IMPORT_C virtual void ConstructL() = 0

	Intended Usage	:	Must be overridden in derived class to complete construction

	Error Condition	:	

	@since			7.0

 */

	IMPORT_C virtual void ConstructL() = 0;

/**

	@fn				IMPORT_C void UnitTestConstructL()

	Intended Usage	:	Called from derived class construction to perform all base

						class initialisation.

	Error Condition	:	

	@since			7.0

	@pre 			Should be called during construction of the derived class to perform base class

					initialisation.

	@post			Unspecified

 */

	IMPORT_C void UnitTestConstructL();

/**

	@fn				IMPORT_C void AddTransitionL(CTransition* aTransition)

	Intended Usage	:	Adds the transition to the list to be run during this unit test

	@leave  		KErrNoMemory

	@since			7.0

	@param			aTransition The transition to be added to the list

	@pre 			Should be used in developer implemented ConstructL() to add transitions to the

					Unit Test

	@post			The specified transition is added to the list to be run for this unit test

 */

	IMPORT_C void AddTransitionL(CTransition* aTransition);

/**

	@fn				IMPORT_C void AddBlockingTransitionL(CTransition* aTransition)

	Intended Usage	:	Adds a transition to the unit test which will block until all

					previous asynchronous transitions have completed before running.

	@leave  		KErrNoMemory

	@since			7.0

	@param			aTransition The transition to be added to the list

	@pre 			Should be used in developer implemented ConstructL() to add transitions to the

					Unit Test

	@post			The specified transition is added to the list to be run for this unit test

 */

	IMPORT_C void AddBlockingTransitionL(CTransition* aTransition);

/**

	@fn				virtual void DoCancel()

	Intended Usage	:	Standard Active Object method for cancelling the current request

	@since			7.0

	@pre 			None

	@post			Any outstanding requests are cancelled

 */

	IMPORT_C virtual void DoCancel();

	IMPORT_C void AddLeaveErrorCodeL(TInt aLeaveErrorCode);

protected:

/** The identifier of this Unit Test*/

	const TDesC&	iUnitTestName;

/** List of the transitions which make up this Unit Test*/

	RPointerArray<CTransition>* iTransitions;

/** The test logging mechanism*/

	CDataLogger&	iDataLogger;

/** Used to call back to the test controller that the test has finished*/

	MUnitTestObserver&	iUnitTestObserver;

/** The index in iTransitions of the next transition to be run */

	TInt					iNextTransitionIndex;

/** List of the asyncronous transitions which have requests outstanding */

	RPointerArray<CTransition>* iOutstandingTransitions;

/** Indicates that the next transition is waiting for the completion of async requests 

	before it will be run*/

	TBool iWaitingForCompletion;

/** The currently executing transition : NOT OWNED */

	CTransition* iCurrentlyExecutingTransition;

/** List of all the acceptable error codes */	

	RArray<TInt> iLeaveErrorArray;

/** Connection to the file server - required by iFileMan */	

	RFs iFs;

/** File manager - useful in PrepareUnitTestL if copying files is required */

	CFileMan* iFileMan;

/** Optional reference to the RTest object used in the EXE test harness code which

	kicked off this test framework */

	RTest* iRTest;

	friend class TUnitTest_StateAccessor;

	};

#include <ecom/test_bed/unittest.inl>

#endif