Calling Methods and Properties of Open Applications' Objects

Applies to TestComplete 15.70, last modified on December 17, 2024

With TestComplete you can call methods and properties of Open Applications’ objects directly from test scripts. This topic describes the specifics of these calls.

About Method Invoke Timeout

All libraries supported by TestComplete, WinForms, VCL, AWT, Swing and others, have an important specific: calls to methods of the forms and controls must be performed within a specific thread. Which thread is used for this purpose depends on the application. For instance, in VCL applications, calls to the methods that are responsible for drawing forms and controls must be performed within the main application’s thread. Java applications use a special thread for these operations.

When you call a method of an Open Application’s object from scripts, the testing engine attempts to execute the method within the appropriate thread of the application’s process. In general, this thread can be busy when the call is made, so TestComplete has to wait until the thread can start executing the method. This may make you think that TestComplete froze, when it is not the case.

This situation typically happens when a test script simulates a mouse click over a button on the tested application’s form and the OnClick event handler of this button performs a prolonged operation. If the test script calls internal methods of the tested application, this method will be executed until the OnClick event handler is over and the test execution will be paused. If the event handler hangs, the test execution will also “hang”.

To avoid the problem, you can specify the time to wait by using the project's Method invoke timeout property. This property belongs to the Open Applications | General group of the project’s properties. It specifies the number of milliseconds to wait after a test script calls a method and before the application starts executing the method. If the waiting time exceeds the specified limit, TestComplete considers it as an error and posts a notification to the test log. If the described problem occurs when testing your application, you can increase the project’s Method invoke timeout property to increase the amount of time. An alternative approach is to write script code that will wait for the application to be ready for further testing. See Waiting for Object State Changes and Waiting for a Process or Window Activation for examples of this code.

The Method invoke timeout setting also works when you retrieve or set Open Applications’ object properties from scripts, because these actions are performed through the properties’ get and set methods.

Also, the Method invoke timeout setting works when you explore methods and properties of the tested application in the Object Browser or in the Object Spy window, since retrieving and displaying of property values is performed through method calls.

Converting Types

TestComplete retrieves information about methods and their parameters from debug information. Sometimes, the debug information is generated incorrectly and this causes errors when calling methods from scripts:

  • Some methods can have parameters that are pointers to one- or two-byte values (for instance, a short int *, wchar_t * or bool * in C++ or PWideChar, PSmallInt or PWordBool in Delphi). The debug information treats these parameters as a pointer to a string, so when calling the method from scripts, TestComplete attempts to pass a string to the parameter and the method call will fail.

    To avoid this problem, call the DebugAgent.TreatPCharAsVType method before calling your application’s method. It specifies whether the scripting engine should treat these parameters as integer, boolean or string values. The desired type is specified by the VType of the TreatPCharAsVType method. This parameter can be one of the following constants:

    Constant Value Description
    varInteger or VT_I4 3 The parameters are treated as pointers to integer values.
    varOleStr or VT_BSTR 8 The parameters are treated as pointers to strings.
    varBoolean or VT_BOOL 11 The parameters are treated as pointers to boolean values.

    You call DebugAgent.TreatPCharAsVType before calling your methods from scripts to command TestComplete to automatically convert the parameter value, which is specified in your script code, to the value of the type that is specified by the VType parameter of the DebugAgent.TreatPCharAsVType method.

    After calling your method, you call TreatPCharAsVType and pass the varOleStr value to restore the default parameter processing.

  • Some methods may return pointers to objects or interfaces (for instance, to the IDispatch interface or to a TForm object). In certain cases, TestComplete is unable to determine the resulting type of a method and this may cause an error when you call the method from scripts.

    To avoid the problem, use the DebugAgent.TreatResultPointersAs method. It specifies whether the scripting engine should treat the resulting pointer as a reference to an object or to an interface. The desired processing type is specified by the method’s Value parameter, which can be one of the following constants:

    Constant Description
    0 TestComplete uses its own algorithm to determine the resulting value type.
    1 TestComplete treats the resulting pointer as a pointer to an interfaced object.
    2 TestComplete treats the resulting pointer as a pointer to an object.

    You call DebugAgent.TreatResultPointersAs before calling your application’s method from scripts to specify how the scripting engine should treat the resulting value. To restore the default processing, call TreatResultPointersAs and pass 0 as a parameter.

  • Methods can use various calling conventions (stdcall, safecall and so on). Sometimes, the debug information reports that a method uses the stdcall convention while the method really uses the safecall convention. Calling such methods from scripts will cause an error.

    To avoid the problem, you can use the DebugAgent.TreatStdCallAsSafeCall method.

    You call the DebugAgent.TreatStdCallAsSafeCall(True) method before calling your application’s method from your script to command TestComplete to call stdcall methods as safecall.

    After calling your method, call DebugAgent.TreatStdCallAsSafeCall(False) to restore the default processing. If you do not do this, the calls to other methods (non-problem) will fail.

Handling Exceptions

For information on handling exceptions when calling methods of Open Application’s objects, see Handling Exceptions in Scripts.

See Also

About Open Applications
Addressing Objects of Open Applications

Highlight search results