williamr@2: // Copyright (c) 1994-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of the License "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: // e32\include\e32test.h
williamr@2: // 
williamr@2: //
williamr@2: 
williamr@2: /**
williamr@2:  @file e32test.h
williamr@2:  @publishedAll
williamr@2:  @released
williamr@2: */
williamr@2: 
williamr@2: #ifndef __E32TEST_H__
williamr@2: #define __E32TEST_H__
williamr@2: #include <e32std.h>
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <e32std_private.h>
williamr@4: #include <e32base_private.h>
williamr@4: #endif
williamr@2: #include <e32base.h>
williamr@2: #include <e32cons.h>
williamr@2: #include <e32kpan.h>
williamr@2: #include <e32debug.h>
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <e32def_private.h>
williamr@4: #include <e32event_private.h>
williamr@4: #endif
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Test console.
williamr@2: 
williamr@2: The class creates a console window to which test results can be logged
williamr@2: through the various overloads of the operator().
williamr@2: */
williamr@2: class RTest
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C RTest(const TDesC &aTitle,TInt aThrowaway,const TText* anOtherThrowaway);
williamr@2: 	IMPORT_C RTest(const TDesC &aTitle,TInt aThrowaway);
williamr@2: 	IMPORT_C RTest(const TDesC &aTitle);
williamr@2: 	IMPORT_C void Close();
williamr@2: 	IMPORT_C void Title();
williamr@2: 	IMPORT_C void Start(const TDesC &aHeading);
williamr@2: 	IMPORT_C void Next(const TDesC &aHeading);
williamr@2: 	IMPORT_C void End();
williamr@2: 	IMPORT_C void operator()(TInt aResult,TInt aLineNum,const TText* aFileName);
williamr@2: 	IMPORT_C void operator()(TInt aResult,TInt aLineNum);
williamr@2: 	IMPORT_C void operator()(TInt aResult);
williamr@2: 	IMPORT_C void Panic(TInt anError,TRefByValue<const TDesC> aFmt,...);
williamr@2: 	IMPORT_C void Panic(TRefByValue<const TDesC> aFmt,...);
williamr@2: 	IMPORT_C void Printf(TRefByValue<const TDesC> aFmt,...);
williamr@2: 	IMPORT_C TKeyCode Getch();
williamr@2: 	inline static const TAny* String(TInt aSel,const TText8 *aBuf1,const TText16 *aBuf2);
williamr@2: 	inline CConsoleBase* Console() const;
williamr@2: 	inline void SetConsole(CConsoleBase* aConsole);
williamr@2: 	inline TBool Logged() const;
williamr@2: 	inline void SetLogged(TBool aToLog);
williamr@2: 	inline void HandleError(TInt aError, TInt aLine, const TText* aFileName);
williamr@2: 	inline void HandleNull(TInt aLine, const TText* aFileName);
williamr@2: 	inline void HandleNotEqual(TInt aExpected, TInt aActual, TInt aLine, const TText* aFileName);
williamr@2: 	inline void HandleFailedCompare(TInt aLeft, const TText* aComp, TInt aRight, TInt aLine, const TText* aFileName);
williamr@4: 	inline void HandleValue(TInt aValue,  TInt aLine, const TText* aFileName);
williamr@2: 
williamr@2: 	IMPORT_C static TInt CloseHandleAndWaitForDestruction(RHandleBase& aH);	/**< @internalTechnology */
williamr@2: 
williamr@2: protected:
williamr@2: 	void CheckConsoleCreated();
williamr@2: 	void DisplayLevel();
williamr@2: 	inline void Push();
williamr@2: 	inline void Pop();
williamr@2: private:
williamr@2: 	enum {EMaxStack=0x100,EMaxBuffer=0x100};
williamr@2: private:
williamr@2: 	TInt	iTest;
williamr@2: 	TInt	iCheck;
williamr@2: 	TInt	iLevel;
williamr@2: 	TBool	iLogging;
williamr@2: 	CConsoleBase *iConsole;
williamr@2: 	TBuf<0x40> iTitle;
williamr@2: 	TInt iStack[EMaxStack];
williamr@2: 	TText iBuf[EMaxBuffer];
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Gets the console.
williamr@2: 
williamr@2: @return A pointer to the console object.
williamr@2: */
williamr@2: inline CConsoleBase* RTest::Console() const
williamr@2: 	{ return(iConsole); }
williamr@2: 
williamr@2: 	
williamr@2: 	
williamr@2: 	
williamr@2: /**
williamr@2: Utility function that returns a pointer to the specified TText8* argument
williamr@2: or the TText16* argument depending on the value of the aSel argument.
williamr@2: 
williamr@2: @param aSel  An integer containing the size of a TText8 type or TText16 type.
williamr@2: @param aBuf1 A pointer to 8-bit text.
williamr@2: @param aBuf2 A pointer to 16-bit text.
williamr@2: 
williamr@2: @return A pointer to aBuf1, if the value of aSel is the size of a TText8 type,
williamr@2:         otherwise a pointer to aBuf2.
williamr@2: */	
williamr@2: inline const TAny *RTest::String(TInt aSel,const TText8 *aBuf1,const TText16 *aBuf2)
williamr@2: 	{ return(aSel == sizeof(TText8) ? (TAny *)aBuf1 : (TAny *)aBuf2); }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: inline void RTest::Push()
williamr@2: 	{ iStack[iLevel++] = iTest; iTest = 0; }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: inline void RTest::Pop()
williamr@2: 	{ iTest = iStack[--iLevel]; }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Sets the console.
williamr@2: 
williamr@2: @param aConsole A pointer to the console object to be used.
williamr@2: */	
williamr@2: inline void RTest::SetConsole(CConsoleBase* aConsole)
williamr@2:     { iConsole = aConsole; }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Tests whether the logging flag is set.
williamr@2: 
williamr@2: If the logging flag is set, console output is also written to
williamr@2: the debug output as represented by a RDebug object.
williamr@2: 
williamr@2: @return True, if the logging flag is set, false otherwise.
williamr@2: */	
williamr@2: inline TBool RTest::Logged() const
williamr@2: 	{ return(iLogging); }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Sets the logging flag.
williamr@2: 
williamr@2: If the logging flag is set, console output is also written to
williamr@2: the debug output as represented by a RDebug object.
williamr@2: 
williamr@2: @param aToLog ETrue, if the logging flag is to be set, EFalse, otherwise.
williamr@2: */	
williamr@2: inline void RTest::SetLogged(TBool aToLog)
williamr@2: 	{ iLogging = aToLog; }
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: // test equivalent of _L
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define _TL(a) (S*)RTest::String(sizeof(S),(TText8*)a,(TText16*)L ## a) 
williamr@2: 
williamr@2: // the next two, slightly confusing, macros are necessary in order
williamr@2: // to enable proper string merging with certain compilers.
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define __test(x,l,f) test(x,l,_S(f))
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define test(x) __test(x,__LINE__,__FILE__)
williamr@2: 
williamr@2: 
williamr@2: #ifdef __E32TEST_EXTENSION__
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define __S(f) _S(f)
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if x is less then zero (Indicating an error code).
williamr@2: */
williamr@2: #define test_NotNegative(x) { TInt _r = (x); if (_r < 0) test.HandleError(_r, __LINE__,__S(__FILE__)); }
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if x is not equal to KErrNone.
williamr@2: */
williamr@2: #define test_KErrNone(x) { TInt _r = (x); if (_r !=KErrNone) test.HandleError(_r, __LINE__,__S(__FILE__)); }
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if the trapped statement/block x leaves.
williamr@2: */
williamr@4: #define test_TRAP(x) { TRAPD(_r, x); if (_r != KErrNone) test.HandleError(_r, __LINE__,__S(__FILE__)); }
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if x is not equal to NULL.
williamr@2: */
williamr@2: #define test_NotNull(x) { TAny* _a = (TAny*)(x); if (_a == NULL) test.HandleNull(__LINE__,__S(__FILE__)); }
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if e (expected) is not equal to a (actual).
williamr@2: */
williamr@2: #define test_Equal(e, a) { TInt _e = TInt(e); TInt _a = TInt(a); if (_e != _a) test.HandleNotEqual(_e, _a, __LINE__,__S(__FILE__)); }
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message if the comparison specified with operator b, between a and c, is EFalse.
williamr@2: */
williamr@2: #define test_Compare(a,b,c)  {TInt _a = TInt(a); TInt _c = TInt(c); if (!(_a b _c)) test.HandleFailedCompare(_a, __S(#b), _c, __LINE__,__S(__FILE__)); }
williamr@4: 
williamr@4: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: 
williamr@4: Panics and displays an appropriate error message displaying v, if the expression e is false.
williamr@4: */
williamr@4: #define test_Value(v, e) if (!(e)) test.HandleValue(v,  __LINE__,__S(__FILE__));
williamr@4: 
williamr@4: /**
williamr@4: @internalComponent
williamr@4: 
williamr@4: If expression e is false, statement s is executed then a Panic is raised.
williamr@2: */
williamr@2: #define test_Assert(e,s) if(!(e)) {s; test.operator()(EFalse, __LINE__,__S(__FILE__)); }
williamr@2: 	
williamr@2: 	
williamr@2: 
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Prints a failure message, including an error code at the console and raises a panic.
williamr@2: 
williamr@2: 
williamr@2: @param aError	 The error code to be printed in the failure massage.
williamr@2: @param aLineNum  A line number that is printed in the failure message.
williamr@2: @param aFileName A file name that is printed in the failure message.
williamr@2:                  
williamr@2: @panic USER 84 Always.
williamr@2: */
williamr@2: inline void RTest::HandleError(TInt aError, TInt aLine, const TText* aFileName)
williamr@2: 	{
williamr@2: 	RDebug::Printf("RTEST: Error %d at line %d", aError,aLine);
williamr@2: 	Printf(_L("RTEST: Error %d\n"), aError);
williamr@2: 	operator()(EFalse, aLine, aFileName);
williamr@2: 	}
williamr@2: /**
williamr@2: Prints a failure message indicating null was encountered, at the console and raises a panic.
williamr@2: 
williamr@2: @param aLineNum  A line number that is printed in the failure message.
williamr@2: @param aFileName A file name that is printed in the failure message.
williamr@2:                  
williamr@2: @panic USER 84 Always.
williamr@2: */
williamr@2: 
williamr@2: inline void RTest::HandleNull(TInt aLine, const TText* aFileName)
williamr@2: 	{
williamr@2: 	RDebug::Printf("RTEST: Null value at line %d", aLine);
williamr@2: 	Printf(_L("RTEST: Null value\n"));
williamr@2: 	operator()(EFalse, aLine, aFileName);
williamr@2: 	}
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Prints a failure message indicating that two value (also printed) where not equal, at the console and raises a panic.
williamr@2: 
williamr@2: @param aExpected The value that is to be printed as expected.
williamr@2: @param aActual	 The value that is to be printed as being actually received.
williamr@2: @param aLineNum  A line number that is printed in the failure message.
williamr@2: @param aFileName A file name that is printed in the failure message.
williamr@2:                  
williamr@2: @panic USER 84 Always.
williamr@2: */
williamr@2: 
williamr@2: inline void RTest::HandleNotEqual(TInt aExpected, TInt aActual, TInt aLine, const TText* aFileName)
williamr@2: 	{
williamr@2: 	RDebug::Printf("RTEST: Expected 0x%x (%d) but got 0x%x (%d) at line %d", aExpected,aExpected,aActual,aActual,aLine);
williamr@2: 	Printf(_L("RTEST: Expected 0x%x (%d) but got 0x%x (%d)\n"), aExpected,aExpected,aActual,aActual);
williamr@2: 	operator()(EFalse, aLine, aFileName);
williamr@2: 	}
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Prints a failure message indicating that a comparison between two values (also printed) resulted in EFalse,
williamr@2: at the console and raises a panic.
williamr@2: 
williamr@2: @param aLeft 	 The left value of the comparison.
williamr@2: @param aComp	 A string representing the comparison operator.
williamr@2: @param aRight	 The right value of the comparison.
williamr@2: @param aLineNum  A line number that is printed in the failure message.
williamr@2: @param aFileName A file name that is printed in the failure message.
williamr@2:                  
williamr@2: @panic USER 84 Always.
williamr@2: */
williamr@2: inline void RTest::HandleFailedCompare(TInt aLeft, const TText* aComp, TInt aRight, TInt aLine, const TText* aFileName)
williamr@2: 	{
williamr@2: 	RDebug::Printf("RTEST: (0x%x (%d) %s 0x%x (%d)) == EFalse at line %d", aLeft,aLeft,aComp,aRight,aRight,aLine);
williamr@2: 	Printf(_L("RTEST: (0x%x (%d) %s 0x%x (%d)) == EFalse\n"), aLeft,aLeft,aComp, aRight,aRight);
williamr@2: 	operator()(EFalse, aLine, aFileName);
williamr@2: 	}
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@4: Prints a failure message indicating that aValue was not an expected value, at the console and raises a panic.
williamr@4: 
williamr@4: @param aValue The value that is to be printed as not being an expected value.
williamr@4: @param aLineNum  A line number that is printed in the failure message.
williamr@4: @param aFileName A file name that is printed in the failure message.
williamr@4:                  
williamr@4: @panic USER 84 Always.
williamr@4: */
williamr@4: inline void RTest::HandleValue(TInt aValue,  TInt aLine, const TText* aFileName)
williamr@4: 	{
williamr@4: 	Printf(_L("RTEST: %d (0x%x) was not an expected value.\n"), aValue, aValue);
williamr@4: 	operator()(EFalse, aLine, aFileName);
williamr@4: 	}
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@2: @internalTechnology
williamr@2: */
williamr@2: _LIT(KLitCloseAndWait,"Close&Wait");
williamr@2: 
williamr@2: /**
williamr@2: @internalTechnology
williamr@2: */
williamr@2: #define CLOSE_AND_WAIT(h)	((void)(RTest::CloseHandleAndWaitForDestruction(h) && (User::Panic(KLitCloseAndWait,__LINE__),1)))
williamr@2: 
williamr@4: 
williamr@4: 
williamr@2: #endif
williamr@4: