isys::CTestCaseController Class Reference

Description

This class provides low level interface for configuration and execution of unit tests.

Tests are executed on target without code instrumentation.

Each test case has its life-cycle composed of several possible states. The figure below shows available states and events, which trigger transition between states. Event names with '()' are methods from this class, which trigger the transition.

The following rules apply for data access:

• Function parameters may be created and evaluated only in state initialized.
• Return value is only available in state ended.
• local variables (created with createVariable())can be accessed in any state except offline.

Python example with script callbacks: script_callback_methods.py
Python example: test_init_close.py

#include <CTestCaseController.h>

Inheritance diagram for isys::CTestCaseController:

Public Member Functions
	CTestCaseController (std::shared_ptr< ConnectionMgr > connectionMgr, const std::string &functionName, const std::string &retValName)
	Creates test case for the given function. More...
	CTestCaseController (std::shared_ptr< ConnectionMgr > connectionMgr, DWORD testCaseHandle)
	Creates test case controller for the given handle. More...
void	destroy ()
	Destroys object on the target. More...
DWORD	getTestCaseHandle ()
	Returns the test case handle. More...
void	createParameter (DWORD parameterIndex, const std::string &parameterName, const std::string &parameterValue="")
	Creates function parameter and assignes a name to it, because debug information does not provide it. More...
void	createVariable (const std::string &variableName, const std::string &typeName, DWORD flags=IConnectTest::cveRegularVariable)
	Utility method for variable creation. More...
void	deletePersistentVariable (const std::string &variableName)
void	commitDeletedVars ()
void	setTestTimeout (int timeout)
	Sets timeout in which the test should be terminated if it does not end normally. More...
CTestStubControllerSPtr	createStub (const std::string &functionName)
	Utility method for stub creation. More...
CTestStubControllerSPtr	createStub (IConnectTest::EStubFlags flags, const std::string &stubbedFunctionName)
	Utility method for stub creation. More...
void	createUserStub (const std::string &functionName, const std::string &stubFunctionName)
	This method creates user stub. More...
CTestStubControllerSPtr	getActiveStub ()
	When test case execution stops at stub, this method returns the stub controller. More...
void	createPersistentVariable (const std::string &variableName, const std::string &typeName)
	Python example: test_persistent_vars.py
void	initPersistentVars ()
	Python example: test_persistent_vars.py
void	cleanPersistentVars ()
	Python example: test_persistent_vars.py
std::string	evaluate (const std::string &expression, DWORD dwEvalFlags=0)
	Evaluates the given expression and returns result as a string. More...
std::string	modify (const std::string &expression, const std::string &value, DWORD dwEvalFlags=0)
	Modifies expression to the given value. More...
void	modifyAsString (const std::string &lval, const std::string &rval, DWORD dwEvalFlags=0)
	Sets lval to rval. More...
IConnectTest::EState	getStatus ()
	Returns the current test case status. More...
IConnectTest::EState	getStatus (DWORD flags)
	Returns the current test case status. More...
bool	init ()
	Initializes the test case by initializing environment on the target according to function under test. More...
void	clean ()
void	setTestBatchNS (bool isBatchBegin)
	Marks start of test batch. More...
void	setDebugModeOn ()
	Turns debug mode on for the next test case. More...
void	run ()
	Runs an initialized test case; it has no effect if the test case is not initialized (i.e. More...
bool	waitUntilStopped (int timeoutMs=0, DWORD pollingIntervalMs=100)
	This method polls test execution status with the given polling interval and returns when the test stops or timeout expires. More...
std::string	stubState2str (IConnectTest::EStubState state)
	Converts stub state to enum string. More...

Static Public Member Functions
static void	setTestBatch (ConnectionMgrSPtr connectionMgr, bool isBatchBegin)
	Static variant of setTestBatchNS(bool). More...
static void	clearAllTests (std::shared_ptr< ConnectionMgr > connection)
	Removes all test data from isystem.connect. More...
static std::string	testState2str (IConnectTest::EState state)
	Converts test state to enum string. More...
static int64_t	s2i64 (const std::string &numStr)
	Utility method for string to number conversion. More...

Constructor & Destructor Documentation

CTestCaseController() [1/2]

isys::CTestCaseController::CTestCaseController	(	std::shared_ptr< ConnectionMgr >	connectionMgr,
		const std::string &	functionName,
		const std::string &	retValName
	)

Creates test case for the given function.

The test case declaration is stored in winIDEA buffer, and does not get on target until it is initialized. Only one test case may be in initialized state.

Parameters

connectionMgr	connection to winIDEA
functionName	name of the function to test
retValName	name of the variable used to store the function return value, so that it can be used after test for verification. May be empty string if it is not used by test or function is of type void.

Python example: test_init_close.py

CTestCaseController() [2/2]

isys::CTestCaseController::CTestCaseController	(	std::shared_ptr< ConnectionMgr >	connectionMgr,
		DWORD	testCaseHandle
	)

Creates test case controller for the given handle.

When using this ctor, test case controller with the given handle must exist, and this instance is valid only as long as the original controller exists. The purpose of this ctor is to be used from Python, when original controller was created in testIDEA. We can not pass pointers to other processes, so we pass a handle when Python script functions are being called during test.

Parameters

connectionMgr	connection to winIDEA
testCaseHandle	handle of existing test case Python example: test_set_test_batch.py

Member Function Documentation

clean()

void isys::CTestCaseController::clean ( )

virtual

Deprecated:

call destroy() instead.

Python example: test_persistent_vars.py

Implements isys::ITestCaseController.

clearAllTests()

static void isys::CTestCaseController::clearAllTests ( std::shared_ptr< ConnectionMgr >  connection )

static

Removes all test data from isystem.connect.

All existing instances of this class should be destroyed, because their handles are no longer valid. Use this method when the state of the iconnect.test is not known, for example at application startup, to remove any data that remained from the previous run.

Python example: test_init_close.py

commitDeletedVars()

void isys::CTestCaseController::commitDeletedVars ( )

virtual

See also

ITestCaseController::commitDeletedVars() Python example: test_persistent_vars.py

Implements isys::ITestCaseController.

createParameter()

void isys::CTestCaseController::createParameter	(	DWORD	parameterIndex,
		const std::string &	parameterName,
		const std::string &	parameterValue = ""
	)

Creates function parameter and assignes a name to it, because debug information does not provide it.

Parameters

parameterIndex	0-based index of parameter in function parameter list
parameterName	name of parameter to be used when setting it's value.
parameterValue	Value of parameter; default value is "".

Python example: test_create_parameter.py

createStub() [1/2]

CTestStubControllerSPtr isys::CTestCaseController::createStub ( const std::string &  functionName )

virtual

Utility method for stub creation.

The stub object created with this method is destroyed when the parent CTestCaseController object is destroyed. Breakpoints for stubs created with this method are managed automatically by winIDEA.

Parameters

functionName

name of the stubbed function

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

createStub() [2/2]

CTestStubControllerSPtr isys::CTestCaseController::createStub ( IConnectTest::EStubFlags  flags, const std::string &  stubbedFunctionName  )

virtual

Utility method for stub creation.

The stub object created with this method is destroyed when the parent CTestCaseController object is destroyed.

Parameters

flags	see IConnectTest::EStubFlags
stubbedFunctionName	name of the stubbed function

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

createUserStub()

void isys::CTestCaseController::createUserStub ( const std::string &  functionName, const std::string &  stubFunctionName  )

virtual

This method creates user stub.

If stubFunctionName parameter is not empty, then execution continues on stub method on the target, when this stub is hit. If the stubFunctionName parameter is empty string, then return instruction is inserted at the start of the stubbed function.

For the first approach with target function name in stubFunctionName, we have to provide additional function on target, with the same prototype as stubbed methods.

The second approach with immediate return should be used only for void functions without output parameters.

Parameters

functionName	name of the stubbed function
stubFunctionName	name of the function, which should be called instead of the stubbed function, or an empty string

Python example: test_create_user_stub.py

Implements isys::ITestCaseController.

createVariable()

void isys::CTestCaseController::createVariable	(	const std::string &	variableName,
		const std::string &	typeName,
		DWORD	flags = IConnectTest::cveRegularVariable
	)

Utility method for variable creation.

The variable object created with this method is destroyed when the parent CTestCaseController object is destroyed.

Parameters

variableName	name of the variable to be created
typeName	type of the variable. This should be one of the existing types in the application under test (defined in debug symbol table).
flags	see IConnectTest::ECreateVariableExFlags

Python example: test_modify.py
Python example: test_case_controller_example.py

deletePersistentVariable()

void isys::CTestCaseController::deletePersistentVariable ( const std::string &  variableName )

virtual

See also

ITestCaseController::deletePersistentVariable()

Python example: test_persistent_vars.py

Implements isys::ITestCaseController.

destroy()

void isys::CTestCaseController::destroy ( )

virtual

Destroys object on the target.

If this method is not called, the object is destroyed by destructor.

Python example: test_control.py

Implements isys::ITestCaseController.

evaluate()

std::string isys::CTestCaseController::evaluate ( const std::string &  expression, DWORD  dwEvalFlags = 0  )

virtual

Evaluates the given expression and returns result as a string.

This method is similar to IConnectDebug::Evaluate(). The difference is in variable scope, since this method takes into account also variables created by createVariable() and the test case return value.

See state descriptions above for data accessibility.

Important: Returned string depends on GUI settings for integer types, for example for value -11 of type short the function returns 0xFFF5 if hex mode is selected in winIDEA watch window. To avoid this dependency, add format postfix to the the expression, for example d: evaluate("counter,d").

Parameters

expression	the expression to be evaluated
dwEvalFlags	see IConnectTest::EEvaluateFlags

Returns

evaluation result

Python example: test_case_controller_example.py
Python example: test_evaluate.py

Implements isys::ITestCaseController.

getActiveStub()

CTestStubControllerSPtr isys::CTestCaseController::getActiveStub ( )

virtual

When test case execution stops at stub, this method returns the stub controller.

It can be used to set stub return value and other variables. This method should only be called when the method getStatus() returns IConnectTest::stateStub.

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

getStatus() [1/2]

IConnectTest::EState isys::CTestCaseController::getStatus ( )

virtual

Returns the current test case status.

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

getStatus() [2/2]

IConnectTest::EState isys::CTestCaseController::getStatus ( DWORD  flags )

virtual

Returns the current test case status.

Parameters

flags

use IConnectTest::EStatusFlags

Implements isys::ITestCaseController.

getTestCaseHandle()

DWORD isys::CTestCaseController::getTestCaseHandle ( )

virtual

Returns the test case handle.

To be used when there is a need for other processes to access the test case info.

Python example: test_get_test_case_handle.py

Implements isys::ITestCaseController.

init()

bool isys::CTestCaseController::init ( )

virtual

Initializes the test case by initializing environment on the target according to function under test.

Brings the test from limbo state or reinitializes an already initialized test case.

Exceptions

IllegalStateException

if there already exists an initialized test case. Call clean() on the active test case first.

Returns

false if ret val was specified and function returns void. Returns true otherwise.

Python example: test_modify.py

Implements isys::ITestCaseController.

modify()

std::string isys::CTestCaseController::modify ( const std::string &  expression, const std::string &  value, DWORD  dwEvalFlags = 0  )

virtual

Modifies expression to the given value.

Expression must be an lvalue.

See state descriptions above for data accessibility.

Parameters

expression	lvalue to be modified
value	the value to be assigned to 'expression'
dwEvalFlags	see IConnectTest::EEvaluateFlags

Returns

evaluation result

Python example with callback methods: script_callback_methods.py
Python example: test_modify.py

Implements isys::ITestCaseController.

modifyAsString()

void isys::CTestCaseController::modifyAsString ( const std::string &  lval, const std::string &  rval, DWORD  dwEvalFlags = 0  )

virtual

Sets lval to rval.

If rval is double quoted string, then lval must be pointer or array. Assignments lval[i] = 'rval[i]' for each element in rval are made. Normal assignment (lval = rval) is performed if rval does not start and end with double quote.

Parameters

lval	left-value, for example name of variable, register, ...
rval	value to assign. Can be "double quoted" string for string array assignments or array of values for array assignment: {0, 1, 2, 3, 4}
dwEvalFlags	see IConnectTest::EEvaluateFlags

Python example: test_case_controller_example.py
Python example: test_modify.py

Implements isys::ITestCaseController.

run()

void isys::CTestCaseController::run ( )

virtual

Runs an initialized test case; it has no effect if the test case is not initialized (i.e.

in limbo); valid only if the test case is clean initialized (not valid for resume).

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

s2i64()

static int64_t isys::CTestCaseController::s2i64 ( const std::string &  numStr )

static

Utility method for string to number conversion.

It accepts numbers in decimal, hexadecimal formats and character formats, for example: "16", "0x10", and "\xFF". No leading spaces are allowed or signs for decimal numbers.

Python example: test_s2i64.py

setDebugModeOn()

void isys::CTestCaseController::setDebugModeOn ( )

virtual

Turns debug mode on for the next test case.

Speed optimizations will be disabled, so winIDEA UI will be refreshed. This method must be called after method init() to have effect.

Python example: test_set_debug_mode_on.py

Implements isys::ITestCaseController.

setTestBatch()

static void isys::CTestCaseController::setTestBatch ( ConnectionMgrSPtr  connectionMgr, bool  isBatchBegin  )

static

Static variant of setTestBatchNS(bool).

See also

setTestBatchNS(bool)

setTestBatchNS()

void isys::CTestCaseController::setTestBatchNS ( bool  isBatchBegin )

virtual

Marks start of test batch.

When isBatchBegin = true, winIDEA remembers the batch start and saves target state, but it does not restore it at the end of the test, but only when this method is called again with isBatchBegin is false. This method can be called several times with isBatchBegin = true, but it must be called the same number of times with isBatchBegin = false to restore the state. Postfix NS stands for non-static. Use ctor CTestCaseController(std::shared_ptr<ConnectionMgr> connectionMgr, 0) to instantiate object for calling this method.

Parameters

isBatchBegin

when true, winIDEA saves target state, when false, it is restored.

See also

setTestBatch(ConnectionMgrSPtr, bool)

Python example: test_set_test_batch.py

Implements isys::ITestCaseController.

setTestTimeout()

void isys::CTestCaseController::setTestTimeout ( int  timeout )

virtual

Sets timeout in which the test should be terminated if it does not end normally.

Python example: test_set_test_timeout.py

Implements isys::ITestCaseController.

stubState2str()

std::string isys::CTestCaseController::stubState2str

(

IConnectTest::EStubState

state

)

Converts stub state to enum string.

This is a utility function for logging and error reporting. Program logic should always use enum directly. If enum value can't be mapped to one of defined values, the return string contains its integer representation. Python example: test_get_active_stub.py

testState2str()

static std::string isys::CTestCaseController::testState2str ( IConnectTest::EState  state )

static

Converts test state to enum string.

This is a utility function for logging and error reporting. Program logic should always use enum directly. If enum value can't be mapped to one of defined values, the return string contains its integer representation. Python example: test_get_active_stub.py

waitUntilStopped()

bool isys::CTestCaseController::waitUntilStopped ( int  timeoutMs = 0, DWORD  pollingIntervalMs = 100  )

virtual

This method polls test execution status with the given polling interval and returns when the test stops or timeout expires.

The test may stop for several reasons. To get the reason, call the getStatus() method.

Parameters

timeoutMs	timeout in milliseconds. 0 means infinite timeout
pollingIntervalMs	time in milliseconds between two readings of the test status

Returns

true if the test is in stopped state, false if timeout expired

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.