Description

This class can create and execute tests, which are not limited to single function.

We can initialize target and start test programatically, and then the same way stop the target and analyze the target state (registers, variables, ...).

API implemented by this class is relatively low lever. Python clients are advised to use the PTestCase class.

Python example.

#include <CSystemTestController.h>

Inheritance diagram for isys::CSystemTestController:

Public Member Functions
void	clean ()

void	cleanPersistentVars ()
	Cleans persistent variables from the stack.

void	commitDeletedVars ()

void	createPersistentVariable (const std::string &variableName, const std::string &typeName)
	This method creates variable on stack.

CTestStubControllerSPtr	createStub (const std::string &functionName)
	Utility method for stub creation.

CTestStubControllerSPtr	createStub (IConnectTest::EStubFlags flags, const std::string &functionName)
	Utility method for stub creation.

void	createUserStub (const std::string &functionName, const std::string &stubFunctionName)
	Utility method for stub creation.

	CSystemTestController (std::shared_ptr< ConnectionMgr > connectionMgr)
	Instantiates object.

void	deletePersistentVariable (const std::string &variableName)

void	destroy ()
	Destroys all items related to test, for example stubs, and persistent variables.

std::string	evaluate (const std::string &expression, DWORD dwEvalFlags=0)
	Evaluates the given expression and returns result as a string.

CTestStubControllerSPtr	getActiveStub ()
	When test case execution stops at stub, this method returns the stub controller.

IConnectTest::EState	getStatus ()
	Returns the current execution status.

IConnectTest::EState	getStatus (DWORD flags)
	Returns the current execution status.

DWORD	getTestCaseHandle ()
	Returns the test case handle.

bool	init ()
	Applies created stubs on the target.

void	initPersistentVars ()
	Allocates persistent variables, which were created with createPersistentVariable(), on the stack.

std::string	modify (const std::string &expression, const std::string &value, DWORD dwEvalFlags=0)
	Modifies expression to the given value.

void	modifyAsString (const std::string &expression, const std::string &value, DWORD dwEvalFlags=0)
	Sets lval to rval.

void	run ()
	Runs the target.

void	setTestTimeout (int timeout)
	Sets timeout in ms.

void	stop ()
	Stops the target.

bool	waitUntilStopped (int timeoutMs=0, DWORD pollingIntervalMs=100)
	This method polls test execution status with the given polling interval and returns when the target stops or timeout expires.

	~CSystemTestController ()
	Destructor automatically calls destroy().

Constructor & Destructor Documentation

◆ CSystemTestController()

isys::CSystemTestController::CSystemTestController ( std::shared_ptr< ConnectionMgr > connectionMgr )

Instantiates object.

Parameters

connectionMgr connection to winIDEA

◆ ~CSystemTestController()

isys::CSystemTestController::~CSystemTestController ( )

Destructor automatically calls destroy().

No objects created by this object may be used after this call.

Member Function Documentation

◆ clean()

void isys::CSystemTestController::clean ( )

virtual

Deprecated: call destroy() instead.

If this method is not called, objects are destroyed in destructor.

Implements isys::ITestCaseController.

◆ cleanPersistentVars()

void isys::CSystemTestController::cleanPersistentVars ( )

virtual

Cleans persistent variables from the stack.

Python example.

Implements isys::ITestCaseController.

◆ commitDeletedVars()

void isys::CSystemTestController::commitDeletedVars ( )

virtual

See also: ITestCaseController::commitDeletedVars() Python example.

Implements isys::ITestCaseController.

◆ createPersistentVariable()

void isys::CSystemTestController::createPersistentVariable	(	const std::string &	variableName,
		const std::string &	typeName )

virtual

This method creates variable on stack.

The variable object created with this method is destroyed when the parent CSystemTestController object is destroyed. This method may not be called when unit test is in progress. Call initPersistentVars() and modify() to initialize the created variable.

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).

Python example.

Implements isys::ITestCaseController.

◆ createStub() [1/2]

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

virtual

Utility method for stub creation.

The stub object created with this method is destroyed when the parent CSystemTestController object is destroyed. When this stub is hit, control is transferred to script running on PC - it can modify parameters, set return value and restart execution.

The stub is implemented as breakpoint at the first method instruction.

Parameters

functionName name of the stubbed function

Python example: stubs_and_user_stubs_in_sys_tests.py
Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

◆ createStub() [2/2]

CTestStubControllerSPtr isys::CSystemTestController::createStub	(	IConnectTest::EStubFlags	flags,
		const std::string &	functionName )

virtual

Utility method for stub creation.

The stub object created with this method is destroyed when the parent CSystemTestController object is destroyed. When this stub is hit, control is transferred to script running on PC - it can modify parameters, set return value and restart execution.

The stub is implemented as breakpoint at the first method instruction. Breakpoint handling can be automatic or custom controlled - see flags.

Parameters

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

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

◆ createUserStub()

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

virtual

Utility method for stub creation.

The stub object created with this method is destroyed when the parent CSystemTestController object is destroyed. When this stub is hit, execution continues in stub function on the target, which replaces stubbed function. We have to provide additional functions with the same prototype as stubbed functions to be used as stubs.

The stub is implemented as replacement of the first instruction in the stubbed function with jump to the stub function.

Parameters

functionName	name of the stubbed function
stubFunctionName	name of the function, which should be called instead of the stubbed function

Python example: test_create_user_stub.py

Implements isys::ITestCaseController.

◆ deletePersistentVariable()

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

virtual

See also: ITestCaseController::deletePersistentVariable() Python example.

Implements isys::ITestCaseController.

◆ destroy()

void isys::CSystemTestController::destroy ( )

virtual

Destroys all items related to test, for example stubs, and persistent variables.

If this method is not called, objects are destroyed in destructor. Python example.

Implements isys::ITestCaseController.

◆ evaluate()

std::string isys::CSystemTestController::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 createPersistentVariable().

Parameters

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

Returns: evaluation result

Python example: persistent_vars.py
Python example: test_evaluate.py

Implements isys::ITestCaseController.

◆ getActiveStub()

CTestStubControllerSPtr isys::CSystemTestController::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::CSystemTestController::getStatus ( )

virtual

Returns the current execution status.

Python example: stubs_and_user_stubs_in_sys_tests.py
Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

◆ getStatus() [2/2]

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

virtual

Returns the current execution status.

Parameters

flags use IConnectTest::EStatusFlags

Python example: stubs_and_user_stubs_in_sys_tests.py

Implements isys::ITestCaseController.

◆ getTestCaseHandle()

DWORD isys::CSystemTestController::getTestCaseHandle ( )

virtual

Returns the test case handle.

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

Implements isys::ITestCaseController.

◆ init()

bool isys::CSystemTestController::init ( )

virtual

Applies created stubs on the target.

Call this method before running target. Python example.

Implements isys::ITestCaseController.

◆ initPersistentVars()

void isys::CSystemTestController::initPersistentVars ( )

virtual

Allocates persistent variables, which were created with createPersistentVariable(), on the stack.

When persistent variables are no longer needed, call cleanPersistentVars(). Python example.

Implements isys::ITestCaseController.

◆ modify()

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

virtual

Modifies expression to the given value.

Expression must be an lvalue.

Parameters

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

Returns: evaluation result

Python example: test_modify.py

Implements isys::ITestCaseController.

◆ modifyAsString()

void isys::CSystemTestController::modifyAsString	(	const std::string &	expression,
		const std::string &	value,
		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

expression	left-value, for example name of variable, register, ...
value	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_modify.py

Implements isys::ITestCaseController.

◆ run()

void isys::CSystemTestController::run ( )

virtual

Runs the target.

Python example: test_get_active_stub.py

Implements isys::ITestCaseController.

◆ setTestTimeout()

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

virtual

Sets timeout in ms.

Python example.

Implements isys::ITestCaseController.

◆ stop()

void isys::CSystemTestController::stop ( )

Stops the target.

Python example: stubs_and_user_stubs_in_sys_tests.py

◆ waitUntilStopped()

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

virtual

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

The execution 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.

Description

Public Member Functions

Constructor & Destructor Documentation

◆ CSystemTestController()

◆ ~CSystemTestController()

Member Function Documentation

◆ clean()

◆ cleanPersistentVars()

◆ commitDeletedVars()

◆ createPersistentVariable()

◆ createStub() [1/2]

◆ createStub() [2/2]

◆ createUserStub()

◆ deletePersistentVariable()

◆ destroy()

◆ evaluate()

◆ getActiveStub()

◆ getStatus() [1/2]

◆ getStatus() [2/2]

◆ getTestCaseHandle()

◆ init()

◆ initPersistentVars()

◆ modify()

◆ modifyAsString()

◆ run()

◆ setTestTimeout()

◆ stop()

◆ waitUntilStopped()