RTest Class Reference

#include <e32test.h>

class RTest

Public Member Functions
	RTest(const TDesC &, TInt, const TText *)
	RTest(const TDesC &, TInt)
	RTest(const TDesC &)
IMPORT_C void	Close()
IMPORT_C TInt	CloseHandleAndWaitForDestruction(RHandleBase &)
IMPORT_C TInt	CompletePostBootSystemTasks()
CConsoleBase *	Console()
IMPORT_C void	End()
IMPORT_C TKeyCode	Getch()
void	HandleError(TInt, TInt, const TText *)
void	HandleFailedCompare(TInt, const TText , TInt, TInt, const TText )
void	HandleNotEqual(TInt, TInt, TInt, const TText *)
void	HandleNull(TInt, const TText *)
void	HandleValue(TInt, TInt, const TText *)
TBool	Logged()
IMPORT_C void	Next(const TDesC &)
IMPORT_C void	Panic(TInt, TRefByValue< const TDesC >, ...)
IMPORT_C void	Panic(TRefByValue< const TDesC >, ...)
IMPORT_C void	Printf(TRefByValue< const TDesC >, ...)
void	SetConsole(CConsoleBase *)
void	SetLogged(TBool)
IMPORT_C void	Start(const TDesC &)
const TAny *	String(TInt, const TText8 , const TText16 )
IMPORT_C void	Title()
IMPORT_C void	operator()(TInt, TInt, const TText *)
IMPORT_C void	operator()(TInt, TInt)
IMPORT_C void	operator()(TInt)

Protected Member Functions
void	CheckConsoleCreated()
void	DisplayLevel()
void	Pop()
void	Push()

Detailed Description

Test console.

The class creates a console window to which test results can be logged through the various overloads of the operator().

Constructor & Destructor Documentation

RTest ( const TDesC &, TInt, const TText * )

IMPORT_C	RTest	(	const TDesC &	aTitle,
			TInt	aThrowaway,
			const TText *	anOtherThrowaway
		)

Constructor.

Parameters
aTitle	A title describing this use of RTest. This is also referred to as the console title.
aThrowaway	Not used.
anOtherThrowaway	Not used.

RTest ( const TDesC &, TInt )

IMPORT_C	RTest	(	const TDesC &	aTitle,
			TInt	aThrowaway
		)

Constructor.

Parameters
aTitle	A title describing this use of RTest. This is also referred to as the console title.
aThrowaway	Not used.

RTest ( const TDesC & )

IMPORT_C

RTest

(

const TDesC &

aTitle

)

Constructor.

Parameters
aTitle	A title describing this use of RTest. This is also referred to as the console title.

Member Function Documentation

CheckConsoleCreated ( )

void

CheckConsoleCreated

(

)

[protected]

Close ( )

IMPORT_C void

(

)

Closes the console and frees any resources acquired.

CloseHandleAndWaitForDestruction ( RHandleBase & )

IMPORT_C TInt

CloseHandleAndWaitForDestruction

(

RHandleBase &

)

[static]

CompletePostBootSystemTasks ( )

IMPORT_C TInt

CompletePostBootSystemTasks

(

)

This should be called before using the __KHEAP_MARK macro in tests that check for kernel heap leaks.

It will complete deferred background tasks that would ordinarily run at some point after boot and that would lead to kernel heap allocs/deallocs. For example, unload of lazily loaded DLLs and running the reaper.

Console ( )

CConsoleBase *

Console

(

)

const [inline]

Gets the console.

Return Value: A pointer to the console object.

DisplayLevel ( )

void

DisplayLevel

(

)

[protected]

End ( )

IMPORT_C void

End

(

)

Ends the current set of tests.

If this set of tests is not nested within another set, then a message reporting success is written to the console.

Panic Codes
USER	84 if there was no matching call to

Getch ( )

IMPORT_C TKeyCode

Getch

(

)

Gets an input key stroke.

Return Value: The input key code.

HandleError ( TInt, TInt, const TText * )

void	HandleError	(	TInt	aError,
			TInt	aLine,
			const TText *	aFileName
		)	[inline]

Prints a failure message, including an error code at the console and raises a panic.

Parameters
aError	The error code to be printed in the failure massage.
aFileName	A file name that is printed in the failure message.

Panic Codes
USER	84 Always.

HandleFailedCompare ( TInt, const TText , TInt, TInt, const TText )

void	HandleFailedCompare	(	TInt	aLeft,
			const TText *	aComp,
			TInt	aRight,
			TInt	aLine,
			const TText *	aFileName
		)	[inline]

Prints a failure message indicating that a comparison between two values (also printed) resulted in EFalse, at the console and raises a panic.

Parameters
aLeft	The left value of the comparison.
aComp	A string representing the comparison operator.
aRight	The right value of the comparison.
aFileName	A file name that is printed in the failure message.

Panic Codes
USER	84 Always.

HandleNotEqual ( TInt, TInt, TInt, const TText * )

void	HandleNotEqual	(	TInt	aExpected,
			TInt	aActual,
			TInt	aLine,
			const TText *	aFileName
		)	[inline]

Prints a failure message indicating that two value (also printed) where not equal, at the console and raises a panic.

Parameters
aExpected	The value that is to be printed as expected.
aActual	The value that is to be printed as being actually received.
aFileName	A file name that is printed in the failure message.

Panic Codes
USER	84 Always.

HandleNull ( TInt, const TText * )

void	HandleNull	(	TInt	aLine,
			const TText *	aFileName
		)	[inline]

Prints a failure message indicating null was encountered, at the console and raises a panic.

Parameters
aFileName	A file name that is printed in the failure message.

Panic Codes
USER	84 Always.

HandleValue ( TInt, TInt, const TText * )

void	HandleValue	(	TInt	aValue,
			TInt	aLine,
			const TText *	aFileName
		)	[inline]

Prints a failure message indicating that aValue was not an expected value, at the console and raises a panic.

Parameters
aValue	The value that is to be printed as not being an expected value.
aFileName	A file name that is printed in the failure message.

Panic Codes
USER	84 Always.

Logged ( )

TBool

Logged

(

)

const [inline]

Tests whether the logging flag is set.

If the logging flag is set, console output is also written to the debug output as represented by a RDebug object.

Return Value: True, if the logging flag is set, false otherwise.

Next ( const TDesC & )

IMPORT_C void

(

const TDesC &

aHeading

)

Marks the start of the next test.

Parameters
aHeading	A heading describing the test; this is printed at the console. This function is also called by Start(), which passes the text that describes the set of tests.

Panic ( TInt, TRefByValue< const TDesC >, ... )

IMPORT_C void	Panic	(	TInt	anError,
			TRefByValue< const TDesC >	aFmt,
			...
		)

Prints an error message and an error code, and raises a USER 84 panic.

Parameters
anError	The error code.
aFmt	A format list.

Panic ( TRefByValue< const TDesC >, ... )

IMPORT_C void	Panic	(	TRefByValue< const TDesC >	aFmt,
			...
		)

Prints an error message, and raises a USER 84 panic.

Parameters
aFmt	A format list.

Pop ( )

void

Pop

(

)

[protected, inline]

Printf ( TRefByValue< const TDesC >, ... )

IMPORT_C void	Printf	(	TRefByValue< const TDesC >	aFmt,
			...
		)

Prints text to the console.

If the logging flag is set, the string is also written to the debug output as represented by an RDebug object.

See also: RTest::SetLogged() Rtest::Logged() RDebug

Parameters
aFmt	A format list.

Push ( )

void

Push

(

)

[protected, inline]

SetConsole ( CConsoleBase * )

void

SetConsole

(

CConsoleBase *

aConsole

)

[inline]

Sets the console.

Parameters
aConsole	A pointer to the console object to be used.

SetLogged ( TBool )

void

SetLogged

(

TBool

aToLog

)

[inline]

Sets the logging flag.

If the logging flag is set, console output is also written to the debug output as represented by a RDebug object.

Parameters
aToLog	ETrue, if the logging flag is to be set, EFalse, otherwise.

Start ( const TDesC & )

IMPORT_C void

Start

(

const TDesC &

aHeading

)

Marks the start of a set of tests.

Note that sets of tests can be nested.

A call to this function must be matched by a call to RTest::End() to mark the end of this set of tests.

Parameters
aHeading	A heading describing the set of tests; this is printed at the console.

String ( TInt, const TText8 , const TText16 )

const TAny *	String	(	TInt	aSel,
			const TText8 *	aBuf1,
			const TText16 *	aBuf2
		)	[static, inline]

Utility function that returns a pointer to the specified TText8* argument or the TText16* argument depending on the value of the aSel argument.

Parameters
aSel	An integer containing the size of a TText8 type or TText16 type.
aBuf1	A pointer to 8-bit text.
aBuf2	A pointer to 16-bit text.

Return Value: A pointer to aBuf1, if the value of aSel is the size of a TText8 type, otherwise a pointer to aBuf2.

Title ( )

IMPORT_C void

Title

(

)

Prints out the console title and version number.

The format of the text is:

RTEST TITLE: XXX YYY
Epoc/32 YYY

where XXX is the console title, and YYY is the version number, formatted as described by TVersion::Name().

operator() ( TInt, TInt, const TText * )

IMPORT_C void	operator()	(	TInt	aResult,
			TInt	aLineNum,
			const TText *	aFileName
		)

Checks the result of a condition and, if this is false, prints a failure message at the console and raises a panic.

Before checking the condition passed in, the operator increments a check number. This is a value that is set to zero at the start of a test and is incremented by this operator (and by all variants of it). It identifies the check being made within the current test. This value is printed on a failure message.

Typically, the operator is called, passing a test condition, for example:

RTest test(... heading text...,line number... file name)
TInt r;
...some operation to be tested that returns a value in r...
test(r==KErrNone);

The failure message has the format:

: FAIL : XXX failed check N in FFF at line Number: M
RTEST: Checkpoint-fail

where XXX is the console title, N is the check number, FFF is the filename, and M is the line number passed in.

operator() ( TInt, TInt )

IMPORT_C void	operator()	(	TInt	aResult,
			TInt	aLineNum
		)

Checks the result of a condition and, if this is false, prints a failure message at the console and raises a panic.

Typically, the operator is called, passing a test condition, for example:

RTest test(... heading text...,line number)
TInt r;
...some operation to be tested that returns a value in r...
test(r==KErrNone);

The failure message has the format:

: FAIL : XXX failed check N at line Number: M
RTEST: Checkpoint-fail

where XXX is the console title, N is the check number, and M is the line number passed in.

operator() ( TInt )

IMPORT_C void

operator()

(

TInt

aResult

)

Checks the result of a condition and, if this is false, prints a failure message at the console and raises a panic.

Typically, the operator is called, passing a test condition, for example:

RTest test(... heading text...)
TInt r;
...some operation to be tested that returns a value in r...
test(r==KErrNone);

The failure message has the format:

: FAIL : XXX failed check N
RTEST: Checkpoint-fail

where XXX is the console title, and N is the check number.

Parameters
aResult	The condition being tested. This is interpreted as a true or false value.
aLineNum	A line number that is printed in the failure message if the condition being tested is false.
aFileName	A file name that is printed in the failure message if the condition being tested is false.

RTest Class Reference

Detailed Description

Constructor & Destructor Documentation

RTest ( const TDesC &, TInt, const TText * )

RTest ( const TDesC &, TInt )

RTest ( const TDesC & )

Member Function Documentation

CheckConsoleCreated ( )

Close ( )

CloseHandleAndWaitForDestruction ( RHandleBase & )

CompletePostBootSystemTasks ( )

Console ( )

DisplayLevel ( )

End ( )

Getch ( )

HandleError ( TInt, TInt, const TText * )

HandleFailedCompare ( TInt, const TText *, TInt, TInt, const TText * )

HandleNotEqual ( TInt, TInt, TInt, const TText * )

HandleNull ( TInt, const TText * )

HandleValue ( TInt, TInt, const TText * )

Logged ( )

Next ( const TDesC & )

Panic ( TInt, TRefByValue< const TDesC >, ... )

Panic ( TRefByValue< const TDesC >, ... )

Pop ( )

Printf ( TRefByValue< const TDesC >, ... )

Push ( )

SetConsole ( CConsoleBase * )

SetLogged ( TBool )

Start ( const TDesC & )

String ( TInt, const TText8 *, const TText16 * )

Title ( )

operator() ( TInt, TInt, const TText * )

operator() ( TInt, TInt )

operator() ( TInt )

HandleFailedCompare ( TInt, const TText , TInt, TInt, const TText )

String ( TInt, const TText8 , const TText16 )