Description

This interface defines methods for unit testing without code instrumentation.

#include <i_Connect.h>

Inherits IUnknown.

Public Types
enum	EErrorCode
	Defines constants describing test case status.

enum	EEvaluateFlags { efVagueFloatEqual = isys::IConnectTest::EEvaluateFlags::efVagueFloatEqual , efIgnoreLocalScope = isys::IConnectTest::EEvaluateFlags::efIgnoreLocalScope , efUseRealTimeAccess = isys::IConnectTest::EEvaluateFlags::efUseRealTimeAccess , efModifyParameter = isys::IConnectTest::EEvaluateFlags::efModifyParameter }

enum	EControlFlags { controlReset = 0x00000000 , controlTestCaseInit = 0x00000001 , controlTestCaseClean = 0x00000002 , controlTestCaseRun = 0x00000003 , controlTestCaseAbort = 0x00000004 , controlTestCasePause = 0x00000005 , controlTestCaseSetDebugMode = 0x00000006 , controlTestBatchBegin = 0x00000014 , controlTestBatchEnd = 0x00000015 , controlPersistentVariablesInit = 0x00000065 , controlPersistentVariablesClean = 0x00000066 , controlPersistentVariablesApply = 0x00000067 , controlSystemTest = 0x00000100 , controlSystemTestInit = controlSystemTest \| controlTestCaseInit , controlSystemTestClean = controlSystemTest \| controlTestCaseClean , controlSystemTestRun = controlSystemTest \| controlTestCaseRun , controlSystemTestStop = 0x00000104 }
	Defines constants for test case actions. More...

enum	EStatusFlags { sfQueryTestCase = isys::IConnectTest::EStatusFlags::sfQueryTestCase , sfQueryStub = isys::IConnectTest::EStatusFlags::sfQueryStub , sfTestCase = isys::IConnectTest::EStatusFlags::sfTestCase , sfStub = isys::IConnectTest::EStatusFlags::sfStub , sfException = isys::IConnectTest::EStatusFlags::sfException }

enum	EState { stateOffline = isys::IConnectTest::EState::stateOffline , stateInitialized = isys::IConnectTest::EState::stateInitialized , stateRunning = isys::IConnectTest::EState::stateRunning , stateEnded = isys::IConnectTest::EState::stateEnded , stateStub = isys::IConnectTest::EState::stateStub , stateUnexpectedStop = isys::IConnectTest::EState::stateUnexpectedStop , stateAborted = isys::IConnectTest::EState::stateAborted , statePaused = isys::IConnectTest::EState::statePaused , statePersistentReady = isys::IConnectTest::EState::statePersistentReady , stateSystemTest = isys::IConnectTest::EState::stateSystemTest , stateStop = isys::IConnectTest::EState::stateStop , stateException = isys::IConnectTest::EState::stateException , stateTimeOut = isys::IConnectTest::EState::stateTimeOut }

enum	EStubState { stateStubNotActive = isys::IConnectTest::EStubState::stateStubNotActive , stateStubActive = isys::IConnectTest::EStubState::stateStubActive }

enum	EInfoFlags { infoSupported = 1 }
	Defines the flags used by the GetInfo function. More...

enum	ECreateVariableExFlags { cveRegularVariable = isys::IConnectTest::ECreateVariableExFlags::cveRegularVariable , cvePersistentVariable = isys::IConnectTest::ECreateVariableExFlags::cvePersistentVariable }

enum	EDeleteVariableExFlags { dveRegularVariable = 0x0001 , dvePersistentVariable = 0x0002 }
	Defines the flags used in the DeleteVariableEx function. More...

enum	EStubFlags { sfeAutoBreakpoints = isys::IConnectTest::EStubFlags::sfeAutoBreakpoints , sfeCustomBreakpoints = isys::IConnectTest::EStubFlags::sfeCustomBreakpoints }

Public Member Functions
virtual HRESULT	GetLastError (DWORD dwErrorFlags, DWORD *pdwErrorCode, LPSTR pszError, DWORD dwErrorLen) PURE
	Gets the last error code and it's string description. More...

virtual HRESULT	CreateTestCase (DWORD *pdwTestCase, LPCSTR pszFunctionName) PURE
	Creates a new test case. More...

virtual HRESULT	DestroyTestCase (DWORD dwTestCase) PURE
	Deletes test case created by CreateTestCase(). More...

virtual HRESULT	CreateParameter (DWORD dwTestCase, DWORD dwIndex, LPCSTR pszName, LPCSTR pszType="") PURE
	Creates a name for a parameter that can be used for accessing it. More...

virtual HRESULT	CreateReturnValue (DWORD dwTestCase, LPCSTR pszName) PURE
	Creates a name for the function return value that can be used for accessing it during evaluation and modification. More...

virtual HRESULT	CreateVariable (DWORD *pdwVariable, LPCSTR pszName, LPCSTR pszType) PURE
	Creates temporary variable, which can be used as a function parameter. More...

virtual HRESULT	DestroyVariable (DWORD dwVariable) PURE
	Destroys variable created by CreateVariable(). More...

virtual HRESULT	CreateStub (DWORD *pdwStub, LPCSTR pszFunctionName) PURE
	Creates stub for function called by function under test. More...

virtual HRESULT	DestroyStub (DWORD dwStub) PURE
	Destroys a stub. More...

virtual HRESULT	CreateStubParameter (DWORD dwStub, DWORD dwIndex, LPCSTR pszName) PURE
	This method assigns a name to stub parameter at the given position. More...

virtual HRESULT	CreateStubReturnValue (DWORD dwStub, LPCSTR pszName) PURE
	This method assigns a name to stub return value. More...

virtual HRESULT	EvaluateExpression (DWORD dwEvaluateFlags, LPCSTR pszExpression, LPSTR pszResult, DWORD dwResultLen) PURE
	Evaluates the given expression and returns result as a string. More...

virtual HRESULT	ModifyExpression (DWORD dwModifyFlags, LPCSTR pszExpression, LPSTR pszResult, DWORD dwResultLen, LPCSTR pszValue) PURE
	Modifies expression to the given value. More...

virtual HRESULT	Control (DWORD dwControlFlags, DWORD dwHandle) PURE
	This method modifies the state of the test case. More...

virtual HRESULT	GetStatus (DWORD dwStatusFlags, DWORD dwHandle, DWORD *pdwStatus) PURE
	Provides status information. More...

virtual HRESULT	CreateRealtimeStub (DWORD *pdwStub, LPCSTR pszFunctionName) PURE
	Obsolete.

virtual HRESULT	CreateUserStub (DWORD *pdwStub, LPCSTR pszFunctionName, LPCSTR pszUserFunctionName) PURE
	Creates stub for function called by function under test. More...

virtual HRESULT	GetInfo (DWORD dwInfoFlags, DWORD *pdwInfo, LPSTR pszInfo, DWORD dwInfoLen) PURE
	Gets information about the iTest module and the TestManager. More...

virtual HRESULT	CreateVariableEx (DWORD dwCreateVariableExFlags, DWORD *pdwVariable, LPCSTR pszName, LPCSTR pszType) PURE
	Creates temporary variable, which can be used as a function parameter. More...

virtual HRESULT	DeleteVariableEx (DWORD dwDeleteVariableExFlags, LPCSTR pszName) PURE
	Delete temporary variable, which can be used as a function parameter. More...

virtual HRESULT	SetTestCaseTimeOut (DWORD dwTimeOut=0) PURE
	Set a timeout for a testcase. More...

virtual HRESULT	CreateStubEx (DWORD dwStubFlags, LPCSTR pszFunctionName, DWORD *pdwStub) PURE
	Creates stub for function called by function under test. More...

Member Enumeration Documentation

◆ EControlFlags

enum IConnectTest::EControlFlags

Defines constants for test case actions.

Enumerator
controlReset	Clean the active test case from the target if any and destroy all test cases, variables and stubs.
controlTestCaseInit	Initialize a test case, from offline status.
controlTestCaseClean	Cleanup the test case from the target make it offline.
controlTestCaseRun	Run a test case or resume an initialized, paused, stopped or at stub test case; no effect if the test case is offline;.
controlTestCaseAbort	Abort the the test case, no matter it's status; it has no effect if the test case is not initialized.
controlTestCasePause	Pause a running test case; valid only if the test case is initialized and running.
controlTestCaseSetDebugMode	Indicates execution in debug mode. Optimizations should be disabled.
controlTestBatchBegin	a series of test case runs will follow
controlTestBatchEnd	a series of test case runs has ended
controlPersistentVariablesInit	Initialize persistent variables; only possible from from offline status.
controlPersistentVariablesClean	Cleanup persistent variables; only possible from offline status or ended status.
controlPersistentVariablesApply	Apply changes on persistent variables; only possible from offline status or ended status.
controlSystemTest	indicates that this is a system test
controlSystemTestInit	Initialize a system test case, from offline status.
controlSystemTestClean	Cleanup the system test case from the target make it offline.
controlSystemTestRun	Run the initialized system test.
controlSystemTestStop	stop the running system test

◆ ECreateVariableExFlags

enum IConnectTest::ECreateVariableExFlags

Deprecated:: For C++ use flags from isys::IConnectTest::ECreateVariableExFlags (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
cveRegularVariable	See isys::IConnectTest::ECreateVariableExFlags.
cvePersistentVariable	See isys::IConnectTest::ECreateVariableExFlags.

◆ EDeleteVariableExFlags

enum IConnectTest::EDeleteVariableExFlags

Defines the flags used in the DeleteVariableEx function.

Enumerator
dveRegularVariable	The function will behave as DeleteVariable.
dvePersistentVariable	The persistent variable will be deleted.

◆ EEvaluateFlags

enum IConnectTest::EEvaluateFlags

Deprecated:: For C++ use flags from isys::IConnectTest::EEvaluateFlags (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
efVagueFloatEqual	See isys::IConnectTest::EEvaluateFlags.
efIgnoreLocalScope	See isys::IConnectTest::EEvaluateFlags.
efUseRealTimeAccess	See isys::IConnectTest::EEvaluateFlags.
efModifyParameter	See isys::IConnectTest::EEvaluateFlags.

◆ EInfoFlags

enum IConnectTest::EInfoFlags

Defines the flags used by the GetInfo function.

Enumerator
infoSupported	Queries if the currently selected processor architecture in winIDEA is supported by iTest.

◆ EState

enum IConnectTest::EState

Deprecated:: For C++ use flags from isys::IConnectTest::EState (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
stateOffline	See isys::IConnectTest::EState.
stateInitialized	See isys::IConnectTest::EState.
stateRunning	See isys::IConnectTest::EState.
stateEnded	See isys::IConnectTest::EState.
stateStub	See isys::IConnectTest::EState.
stateUnexpectedStop	See isys::IConnectTest::EState.
stateAborted	See isys::IConnectTest::EState.
statePaused	See isys::IConnectTest::EState.
statePersistentReady	See isys::IConnectTest::EState.
stateSystemTest	See isys::IConnectTest::EState.
stateStop	See isys::IConnectTest::EState.
stateException	See isys::IConnectTest::EState.
stateTimeOut	See isys::IConnectTest::EState.

◆ EStatusFlags

enum IConnectTest::EStatusFlags

Deprecated:: For C++ use flags from isys::IConnectTest::EStatusFlags (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
sfQueryTestCase	See isys::IConnectTest::EStatusFlags.
sfQueryStub	See isys::IConnectTest::EStatusFlags.
sfTestCase	See isys::IConnectTest::EStatusFlags.
sfStub	See isys::IConnectTest::EStatusFlags.
sfException	See isys::IConnectTest::EStatusFlags.

◆ EStubFlags

enum IConnectTest::EStubFlags

Deprecated:: For C++ use flags from isys::IConnectTest::EStubFlags (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
sfeAutoBreakpoints	See isys::IConnectTest::EStubFlags.
sfeCustomBreakpoints	See isys::IConnectTest::EStubFlags.

◆ EStubState

enum IConnectTest::EStubState

Deprecated:: For C++ use flags from isys::IConnectTest::EStubState (i_ConnectTypes.h), for other languages the right type is automatically used. Provided for backwards compatibility.

Enumerator
stateStubNotActive	See isys::IConnectTest::EStubState.
stateStubActive	See isys::IConnectTest::EStubState.

Member Function Documentation

◆ Control()

virtual HRESULT IConnectTest::Control	(	DWORD	dwControlFlags,
		DWORD	dwHandle
	)

virtual

This method modifies the state of the test case.

Returns: S_OK for success, ICONNECT_S_STATUS_1 if the tested function is void and return value was created

Parameters

dwControlFlags	defines action to be performed. See IConnectTest::EControlFlags for valid values.
dwHandle	handle, depending on the control flags

◆ CreateParameter()

virtual HRESULT IConnectTest::CreateParameter	(	DWORD	dwTestCase,
		DWORD	dwIndex,
		LPCSTR	pszName,
		LPCSTR	pszType = `""`
	)

virtual

Creates a name for a parameter that can be used for accessing it.

If the variable name with this name already exists, it is hidden by the created variable.

Parameters

dwTestCase	test case handle as returned by CreateTestCase()
dwIndex	zero based index of the parameter
pszName	name of the parameter to be created
pszType	type of parameter to be created

◆ CreateReturnValue()

virtual HRESULT IConnectTest::CreateReturnValue	(	DWORD	dwTestCase,
		LPCSTR	pszName
	)

virtual

Creates a name for the function return value that can be used for accessing it during evaluation and modification.

If the variable name with this name already exists, it is hidden by the created variable.

Parameters

dwTestCase	test case handle as returned by CreateTestCase()
pszName	name of the variable to be created

◆ CreateStub()

virtual HRESULT IConnectTest::CreateStub	(	DWORD *	pdwStub,
		LPCSTR	pszFunctionName
	)

virtual

Creates stub for function called by function under test.

Since no code instrumentation is allowed, only breakpoint is set at the given function. When the function is called, the test case execution stops, and then the test framework can define next actions. Usually it will simulate desired side effects of a stubbed function (for example set global variables), and then continue execution of the function under test.

This method must be called BEFORE test case is initialized by method Control(controlTestCaseInit).

Parameters

pdwStub	contains a new stub handle on return
pszFunctionName	name of the stubbed function

◆ CreateStubEx()

virtual HRESULT IConnectTest::CreateStubEx	(	DWORD	dwStubFlags,
		LPCSTR	pszFunctionName,
		DWORD *	pdwStub
	)

virtual

Creates stub for function called by function under test.

Since no code instrumentation is allowed, breakpoint is set automatically or manually (depending on flags) at the given function. When the function is called, the test case execution stops, and then the test framework can define next actions. Usually it will simulate desired side effects of a stubbed function (for example set global variables), and then continue execution of the function under test.

This method must be called BEFORE test case is initialized by method Control(controlTestCaseInit).

Parameters

pdwStub	contains a new stub handle on return
pszFunctionName	name of the stubbed function
dwStubFlags	flags used for specified stub

◆ CreateStubParameter()

virtual HRESULT IConnectTest::CreateStubParameter	(	DWORD	dwStub,
		DWORD	dwIndex,
		LPCSTR	pszName
	)

virtual

This method assigns a name to stub parameter at the given position.

This could be done only with regular stubs. This is not supported in real-time or user stubs. The assigned name may be used in expressions by EvaluateExpression() and ModifyExpression(). This function can be called anytime after the stub is setup and before it is hit.

Parameters

dwStub	stub handle as returned by CreateStub()
dwIndex	0 - based parameter index
pszName	name assigned to parameter

◆ CreateStubReturnValue()

virtual HRESULT IConnectTest::CreateStubReturnValue	(	DWORD	dwStub,
		LPCSTR	pszName
	)

virtual

This method assigns a name to stub return value.

This could be done only with regular stubs. This is not supported in real-time or user stubs. The assigned name may be used in expressions by EvaluateExpression() and ModifyExpression() to define value returned to the function under test. This function can be called anytime after the stub is setup and before it is hit.

Parameters

dwStub	stub handle as returned by CreateStub()
pszName	name assigned to return value

◆ CreateTestCase()

virtual HRESULT IConnectTest::CreateTestCase	(	DWORD *	pdwTestCase,
		LPCSTR	pszFunctionName
	)

virtual

Creates a new test case.

Parameters

pdwTestCase	contains a new test case handle on return
pszFunctionName	name of the function to be tested

◆ CreateUserStub()

virtual HRESULT IConnectTest::CreateUserStub	(	DWORD *	pdwStub,
		LPCSTR	pszFunctionName,
		LPCSTR	pszUserFunctionName
	)

virtual

Creates stub for function called by function under test.

User stubs are used to replace a function with another. Both functions have to have the same parameters and return value. When setting up the stub, code will be patched to achieve this behavior. This could be used to test parts of the code with alternative implementations of functions.

This method must be called BEFORE test case is initialized by method Control(controlTestCaseInit).

Parameters

pdwStub	contains a new stub handle on return
pszFunctionName	name of the stubbed function
pszUserFunctionName	name of replacement function

◆ CreateVariable()

virtual HRESULT IConnectTest::CreateVariable	(	DWORD *	pdwVariable,
		LPCSTR	pszName,
		LPCSTR	pszType
	)

virtual

Creates temporary variable, which can be used as a function parameter.

If the variable name with this name already exists, it is hidden by the created variable.

Parameters

pdwVariable	variable handle as returned by CreateVariable()
pszName	name of the variable to be created
pszType	type of the variable. This should be one of the existing types in the application under test.

◆ CreateVariableEx()

virtual HRESULT IConnectTest::CreateVariableEx	(	DWORD	dwCreateVariableExFlags,
		DWORD *	pdwVariable,
		LPCSTR	pszName,
		LPCSTR	pszType
	)

virtual

Creates temporary variable, which can be used as a function parameter.

If the variable name with this name already exists, it is hidden by the created variable.

Parameters

dwCreateVariableExFlags	flags to set variable type (regular or persistent)
pdwVariable	variable handle as returned by CreateVariable()
pszName	name of the variable to be created
pszType	type of the variable. This should be one of the existing types in the application under test.

◆ DeleteVariableEx()

virtual HRESULT IConnectTest::DeleteVariableEx	(	DWORD	dwDeleteVariableExFlags,
		LPCSTR	pszName
	)

virtual

Delete temporary variable, which can be used as a function parameter.

If the variable name with this name already exists, it is hidden by the created variable.

Parameters

dwDeleteVariableExFlags	flags to set variable type (regular or persistent)
pszName	name of the variable to be created

◆ DestroyStub()

virtual HRESULT IConnectTest::DestroyStub ( DWORD dwStub )

virtual

Destroys a stub.

Parameters

dwStub stub handle as returned by CreateStub(), CreateRealtimeStub() or CreateUserStub().

◆ DestroyTestCase()

virtual HRESULT IConnectTest::DestroyTestCase ( DWORD dwTestCase )

virtual

Deletes test case created by CreateTestCase().

Parameters

dwTestCase test case handle as returned by CreateTestCase()

◆ DestroyVariable()

virtual HRESULT IConnectTest::DestroyVariable ( DWORD dwVariable )

virtual

Destroys variable created by CreateVariable().

Parameters

dwVariable variable handle as returned by CreateVariable().

◆ EvaluateExpression()

virtual HRESULT IConnectTest::EvaluateExpression	(	DWORD	dwEvaluateFlags,
		LPCSTR	pszExpression,
		LPSTR	pszResult,
		DWORD	dwResultLen
	)

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() or CreateParameter(), return value, and stub related data.

Parameters

dwEvaluateFlags	modifies the behavior of the evaluate function. See IConnectTest::EEvaluateFlags
pszExpression	the expression to be evaluated
pszResult	pointer to string, which will contain evaluation result
dwResultLen	the length of allocated array pointed to by pszResult

Returns: result in string form. Numbers may be returned in hex or decimal format, depending on setting in winIDEA's Watch window.

◆ GetInfo()

virtual HRESULT IConnectTest::GetInfo	(	DWORD	dwInfoFlags,
		DWORD *	pdwInfo,
		LPSTR	pszInfo,
		DWORD	dwInfoLen
	)

virtual

Gets information about the iTest module and the TestManager.

This method can be called independently of the status of the TestManager

Parameters

dwInfoFlags	specifies the type of information that is being queried
pdwInfo	returns numeric information
pszInfo	returns string information to a user allocated buffer
dwInfoLen	length of the user allocated buffer

◆ GetLastError()

virtual HRESULT IConnectTest::GetLastError	(	DWORD	dwErrorFlags,
		DWORD *	pdwErrorCode,
		LPSTR	pszError,
		DWORD	dwErrorLen
	)

virtual

Gets the last error code and it's string description.

Call this method, when other methods of this interface do not return S_OK, to get detailed error code and description.

Parameters

dwErrorFlags	flags that modify the behavior of the function
pdwErrorCode	error code
pszError	buffer for the error string
dwErrorLen	length of the error string buffer

◆ GetStatus()

virtual HRESULT IConnectTest::GetStatus	(	DWORD	dwStatusFlags,
		DWORD	dwHandle,
		DWORD *	pdwStatus
	)

virtual

Provides status information.

Parameters

dwStatusFlags	the function operation and the meaning of the other parameters depend on this, for more information see IConnectTest::EStatusFlags
dwHandle	handle to a test object (test case, variable, stub, call), its meaning depends on the flags passed to the function
pdwStatus	contains data on return

◆ ModifyExpression()

virtual HRESULT IConnectTest::ModifyExpression	(	DWORD	dwModifyFlags,
		LPCSTR	pszExpression,
		LPSTR	pszResult,
		DWORD	dwResultLen,
		LPCSTR	pszValue
	)

virtual

Modifies expression to the given value.

Expression must be an lvalue.

Parameters

dwModifyFlags	modifies the behavior of the modify function. See IConnectTest::EEvaluateFlags
pszExpression	lvalue to be modified
pszResult	result of evaluated pszValue is stored here. May be NULL, if we don't need the evaluation result.
dwResultLen	the length of allocated array pointed to by pszResult
pszValue	the value to be assigned to pszExpression

◆ SetTestCaseTimeOut()

virtual HRESULT IConnectTest::SetTestCaseTimeOut ( DWORD dwTimeOut = 0 )

virtual

Set a timeout for a testcase.

Parameters

dwTimeOut when to timeout in ms

Description

Public Types

Public Member Functions

Member Enumeration Documentation

◆ EControlFlags

◆ ECreateVariableExFlags

◆ EDeleteVariableExFlags

◆ EEvaluateFlags

◆ EInfoFlags

◆ EState

◆ EStatusFlags

◆ EStubFlags

◆ EStubState

Member Function Documentation

◆ Control()

◆ CreateParameter()

◆ CreateReturnValue()

◆ CreateStub()

◆ CreateStubEx()

◆ CreateStubParameter()

◆ CreateStubReturnValue()

◆ CreateTestCase()

◆ CreateUserStub()

◆ CreateVariable()

◆ CreateVariableEx()

◆ DeleteVariableEx()

◆ DestroyStub()

◆ DestroyTestCase()

◆ DestroyVariable()

◆ EvaluateExpression()

◆ GetInfo()

◆ GetLastError()

◆ GetStatus()

◆ ModifyExpression()

◆ SetTestCaseTimeOut()