TestComplete samples (both built-in and additional) are located in the <Users>\Public\Public Documents\TestComplete 15 Samples folder.
Some file managers display the Public Documents folder as Documents.
This topic is a starting point in understanding of how to write scripts. It provides brief information on how to perform common actions in scripts and gives you links to more detailed descriptions. The topic includes the following sections:
Note: | We recommend that you read About Script Tests before you proceed. |
General Notes
To write scripts, you must have the Script project item in your project. By default, TestComplete adds this item to all the created project. If you do not have the item in your project, add it manually.
A script is a routine written in one of the supported scripting languages. Script routines are organized in units that are shown as child nodes of the Script project item in the Project Explorer panel.
You create and edit scripts in the Code Editor of TestComplete. It offers a great number of features for editing script code: syntax highlighting, code completion, code templates, outlining, bookmarks, etc. To debug the script code, you can use conditional breakpoints, evaluate and watch dialogs and some other means provided by TestComplete. For more information on editing and debugging capabilities, see About Code Editor and Debugging Tests.
1. Run Tested Applications
Each TestComplete project has a list of tested applications. This is a way for you to keep track of which applications the project deals with, and for TestComplete to launch the applications on the list automatically (you can uncheck any application you do not want to be launched automatically). To ensure that the tested applications are running before you perform any action on them, add the following code at the beginning of your script:
JavaScript, JScript
TestedApps.RunAll();
Python
TestedApps.RunAll()
VBScript
TestedApps.RunAll
DelphiScript
TestedApps.RunAll;
C++Script, C#Script
TestedApps["RunAll"]();
To run a single tested application, use the TestedApps.Items(Index).Run
statement (the Index parameter specifies the index of the desired application in the tested applications list of your project). The following code demonstrates how to run one instance of the first tested application in the list:
JavaScript, JScript
TestedApps.Items(0).Run(1);
Python
TestedApps.Items[0].Run(1)
VBScript
TestedApps.Items(0).Run(1)
DelphiScript
TestedApps.Items[0].Run(1);
C++Script, C#Script
Using the Run
method you can launch one or more application instances. Also, using the method’s Timeout parameter you can specify the number of milliseconds to wait until all application instances have been launched. For more information, see the method description.
For more information on tested applications, see About Tested Applications and Working With Tested Applications in Tests.
2. Access Processes, Windows and Controls
In your script, before you start simulating user actions over your tested application, get a program object that provides a scripting interface to the tested application’s UI elements (for example, windows or controls). To do this, you should first obtain the process to which the desired window belongs.
In the TestComplete object model, processes of desktop and web applications are children of the System (Sys
object). Processes of mobile applications are children of the Devices (Device
object). Device nodes in their turn are children of the Mobile (Mobile
object).
Activities, windows and controls are children of processes and so on.
If you started the tested desktop application by calling the Run
method of the TestedApp
object in your script code, the method will return the process
object corresponding to the launched application:
JavaScript, JScript
var p = TestedApps.Items(0).Run(1);
Python
p = TestedApps.Items[0].Run(1)
VBScript
Set p = TestedApps.Items(0).Run(1)
DelphiScript
var p;
begin
p := TestedApps.Items[0].Run(1);
end;
C++Script, C#Script
var p = TestedApps["Items"](0)["Run"](1);
To obtain a scripting interface to any process running in the system (including those processes that were started from TestComplete), use the Sys.Process
or Sys.WaitProcess
methods. To obtain processes of open mobile applications running on connected mobile devices, use the Mobile.Device.Process
or Mobile.Device.WaitProcess
method.
They return a process
object that provides scripting interface to the process specified by its name and index. The index is used to distinguish several instances of the same application. If there is only one instance of the application running, the index can be omitted. Below is the typical code for obtaining the process
object that provides a scripting interface for the Notepad application:
JavaScript, JScript
var p = Sys.Process("Notepad");
Python
p = Sys.Process("Notepad")
VBScript
Set p = Sys.Process("Notepad")
DelphiScript
var p;
begin
p := Sys.Process('Notepad');
…
end;
C++Script, C#Script
var p = Sys["Process"]("Notepad")
If the specified process does not exist, the Process
method will post an error message to the test log and return an empty stub object containing only one property named Exists
. If you then attempt to call any other methods or properties using this stub object, TestComplete will post an error message to the test log.
To wait until the desired process starts up, you can use the WaitProcess
method. This method pauses the script execution until the specified process is created or the specified timeout is over. If the process is not created, the method does not post an error message to the log, it just returns an empty object:
JavaScript, JScript
p = Sys.WaitProcess("Notepad", 2000);
if (! p.Exists)
// Process does not exist
...
Python
p = Sys.WaitProcess("Notepad", 2000)
if not p.Exists:
# Process does not exist
...
VBScript
Set p = Sys.WaitProcess("Notepad", 2000)
If Not p.Exists Then
' Process does not exist
...
End If
DelphiScript
var p;
begin
p := Sys.WaitProcess('Notepad', 2000);
if not p.Exists then
// Process does not exist
...
end;
C++Script, C#Script
var p;
p = Sys["Process"]("Notepad", 2000);
if (! p["Exists"])
// Process does not exist
...
A possible alternative to the WaitProcess
method is to specify the wait time using the Timeout parameter of the TestedApp.Run
method.
After you get the process, you can obtain windows and controls belonging to this process. The way you do this depends on whether your application is an Open Application or not. Open Applications provide TestComplete with access to their internal objects, methods and properties. For complete information on this, see About Open Applications.
If your application is an Open Application, you can address windows and controls by using one of the following special methods:
Method | Description |
---|---|
WinFormsObject |
Provides access to windows and controls in Microsoft .NET applications by object name or by control class name, window text (caption) and index. |
VCLNETObject |
Provides access to windows and controls in Borland VCL.NET applications by object name or by control class name, window text (caption) and index. |
VBObject |
Provides access to windows and controls in Visual Basic 6.0 applications by object name. |
VCLObject |
Provides access to windows and controls in Delphi and C++Builder VCL applications by object name. |
CLXObject |
Provides access to windows and controls in Delphi and C++Builder CLX applications by object name. |
SwingObject |
Provides access to windows and controls in Java Swing applications by object name or by class name, caption and index. |
AWTObject |
Provides access to windows and controls in Java AWT applications by object name or by class name, caption and index. |
SWTObject |
Provides access to windows and controls in Java SWT applications by object name or by class name, caption and index. |
WFCObject |
Provides access to windows and controls in Java WFC applications by object name or by class name, caption and index. |
WPFObject |
Provides access to windows and controls in WPF (XAML) applications by object name. |
XFObject |
Provides access to controls in Xamarin.Forms applications by the control name, or by the control class name, text and index. |
Windows and objects of Visual C++ applications as well as windows and objects of Java applications that were built using other libraries than Swing and AWT, are addressed as windows of black-box applications (see below).
The following example demonstrates how you can obtain a form of a .NET application created with Microsoft Windows Forms library. If your Open Application was created with another development tool, then to obtain a form of your application replace calls to the WinFormsObject
method with calls to the appropriate method from the table above.
JavaScript, JScript
p1 = Sys.Process("MyApp");
w1 = p1.WinFormsObject("MainForm");
Python
p1 = Sys.Process("MyApp")
w1 = p1.WinFormsObject("MainForm")
VBScript
Set p1 = Sys.Process("MyApp")
Set w1 = p1.WinFormsObject("MainForm")
DelphiScript
var p1, w1;
begin
p1 := Sys.Process('MyApp');
w1 := p1.WinFormsObject('MainForm');
end;
C++Script, C#Script
var p1, w1;
p1 = Sys["Process"]("MyApp");
w1 = p1["WinFormsObject"]("MainForm")
Note: | Each of the changed methods returns the wrapper object for a window of a tested application. This wrapper object provides access to the methods and properties defined by the application code (for example, methods and properties of .NET, Java or MFC classes) as well as methods, properties and actions provided by TestComplete. |
It is possible that a process contains several windows having the same name (for instance, your Open Application may create several instances of the EditOrder form). To distinguish such windows in your scripts, you can use any of the following alternatives:
-
Use the Name Mapping feature.
-
Find for the window using the
Find
,FindChild
orFindId
method of the process (Find
returns a child object by values of its properties,FindId
returns a child object by its id). -
Enumerate all of the windows belonging to the same process, examine the window properties (or properties of their child windows) and obtain the desired window. To enumerate windows, you can use the
Child
andChildCount
properties of theprocess
object.
If a window has no Name
property (for example, windows of Visual C++ applications have no names), or if your application is not an Open Application, you can use the Window
and WaitWindow
methods of the process
object to get the desired window. These methods return a top-level window of a process using window class name, caption and index as parameters:
JavaScript, JScript
p1 = Sys.Process("MyApp");
w1 = p1.Window("WindowClassName", "WindowCaption", 1);
// or
w1 = p1.WaitWindow("WindowClassName", "WindowCaption", 1, 2000);
Python
p1 = Sys.Process("MyApp")
w1 = p1.Window("WindowClassName", "WindowCaption", 1)
# or
w1 = p1.WaitWindow("WindowClassName", "WindowCaption", 1, 2000)
VBScript
Set p1 = Sys.Process("MyApp")
Set w1 = p1.Window("WindowClassName", "WindowCaption", 1)
' or
Set w1 = p1.WaitWindow("WindowClassName", "WindowCaption", 1, 2000)
DelphiScript
var p1, w1;
begin
p1 := Sys.Process('MyApp');
w1 := p1.Window('WindowClassName', 'WindowCaption', 1);
// or
w1 := p1.WaitWindow('WindowClassName', 'WindowCaption', 2000);
end;
C++Script, C#Script
var p1, w1;
p1 = Sys["Process"]("MyApp");
w1 = p1["Window"]("WindowClassName", "WindowCaption", 1);
// or
w1 = p1["WaitWindow"]("WindowClassName", "WindowCaption", 1);
The differences between the Window
and WaitWindow
methods are similar to the differences between the Sys.Process
and Sys.WaitProcess
methods. Window
checks whether the specified window exists and if it does not, the method posts an error message to the test log. WaitWindow
delays the script execution until the specified window is created or until the specified timeout is over. It does not post an error message to the log if the desired window does not exist.
If the window with the specified attributes does not exist, both Window
and WaitWindow
methods will return an empty stub object containing only one Exists
property. If you attempt them to call any other method or property for the stub object, TestComplete will post an error message to the test log.
To determine which class name, caption or index to use to address a window, explore your application in the Object Browser. You can copy the whole window recognition string from the Object Browser:
Note: | You can use wildcards (? and *) when specifying the window caption and class name. |
The Window
and WaitWindow
methods of the process
object return the window
program object that corresponds to a top-level window of a process. To get a child window or control, call Window
or WaitWindow
methods of that window
object.
If your application is an Open Application, you can obtain child windows by their names or by using the methods described above (WinFormsObject
, VBObject
and others).
JavaScript, JScript
p1 = Sys.Process("MyApp");
w1 = p1.WinFormsObject("MainForm");
w2 = w1.WinFormsObject("Button1"); // or w2 = w1.Button1;
Python
p1 = Sys.Process("MyApp")
w1 = p1.WinFormsObject("MainForm")
w2 = w1.WinFormsObject("Button1") # or w2 = w1.Button1
VBScript
Set p1 = Sys.Process("MyApp")
Set w1 = p1.WinFormsObject("MainForm")
Set w2 = w1.WinFormsObject("Button1") ' or Set w2 = w1.Button1
DelphiScript
var p1, w1, w2;
begin
p1 := Sys.Process('MyApp');
w1 := p1.WinFormsObject('MainForm');
w2 := w1.WinFormsObject('Button1'); // or w2 := w1.Button1;
end;
C++Script, C#Script
var p1, w1, w2;
p1 = Sys["Process"]("MyApp");
w1 = p1["WinFormsObject"]("MainForm");
w1 = w1["WinFormsObject"]("Button1"); // or w2 = w1["Button1"];
If you do not call any special xxxxObject
methods, TestComplete will return the wrapper object for the requested window (or control) that will hold only the application-defined properties. For instance, if you are testing a .NET application, the wrapper object only holds the methods and properties of .NET classes. To obtain an object containing both application-defined and TestComplete methods and properties, use the WinFormsObject
method (or one of other special methods mentioned above).
The hierarchy of windows depends on the Object tree model option of your TestComplete project. To view or change it, open the project editor, switch to the Properties page and select the General category on the left of the page. The option will be on the right of the page. This option specifies which of the object tree models, Flat or Tree, is active. For complete information on them, see Object Tree Models. Note that scripts created for the Flat model are not supported by the Tree model and vice versa. That is, if you run a script routine created for the Flat model when the Tree model is active, TestComplete will not find windows and will post errors to the test log. To check the state of the Object tree model option in scripts, use the |
Note: | The child objects list of some objects can change dynamically (for instance, windows can be created or deleted within the process). TestComplete automatically updates the child list when you obtain a child of some object. You can force TestComplete to update the child list of an object by calling the Refresh method of that object.
|
If the same parent window contains two or more objects having the same name, then to obtain the desired window, you can use approaches similar to those that were described for top-level windows (name mapping, searching with Find
and FindId
method, enumeration of child windows).
Once you obtain the window
object for the desired window or control, you can use the object’s methods and properties to work with this window (or control) as your needs dictate. For instance, you can simulate user actions (mouse clicks or keystrokes), maximize or minimize a window (if it is a top-level or MDI window), change window properties (for example, text) and perform other actions. To determine what properties are available to your TestComplete scripts, we would recommend to look up the window properties in the Object Browser.
If your application in an Open Application (for example, a .NET application), the Object Browser will show methods and properties of .NET classes as well as methods and properties provided by TestComplete.
Note that TestComplete automatically determines the type of a window (button, list box, tree view and so on). It adds specific methods and properties to the window
object, so you can use these methods and properties to perform actions specific to the control. For instance, you can enumerate nodes of a tree view, click items of a list view control, get combo box items and so on.
To determine the control type TestComplete checks the window class name. For instance, if the class name of a window coincides with the default class name given by Windows to button windows, TestComplete considers a window as a button. Similarly TestComplete determines the types of other controls (list boxes, tree views, etc.)
Of course, the class name of a window may differ from the default class name. In this case TestComplete uses Object Mapping settings to determine the control type. To view or change these settings, open the project editor, activate the Properties page and choose the Object Mapping category on the left of the page. TestComplete will display the settings on the right of the page.
For complete information on how to address processes, windows and controls in scripts, see Object Browser Naming Notation.
3. Simulate User Actions
TestComplete includes all the means for simulating user actions. You can:
-
Maximize, minimize, bring to front and change position of application’s top-level windows on the screen.
-
Simulate mouse clicks, double-clicks, drag-and-drop events, keystrokes, etc. in controls on application forms.
-
Simulate touches over mobile applications.
-
Simulate selection of menu and toolbar items.
-
Simulate selection of items in list view, tree view, list box and many other controls.
For instance, to simulate a click of a button, obtain the window
object for that button and then call the ClickButton
method of this object (TestComplete automatically adds this method to all window objects that correspond to buttons):
JavaScript, JScript
p1 = Sys.Process("notepad");
w1 = p1.Window("#32770", "Open", 0);
w2 = w1.Window("Button", "&Open", 1);
w2.ClickButton();
Python
p1 = Sys.Process("notepad")
w1 = p1.Window("#32770", "Open", 0)
w2 = w1.Window("Button", "&Open", 1)
w2.ClickButton()
VBScript
Set p1 = Sys.Process("notepad")
Set w1 = p1.Window("#32770", "Open", 0)
Set w2 = w1.Window("Button", "&Open", 1)
w2.ClickButton
DelphiScript
var p1, w1, w2;
begin
p1 := Sys.Process('notepad');
w1 := p1.Window('#32770', 'Open', 0);
w2 := w1.Window('Button', '&Open', 1);
w2.ClickButton();
end;
C++Script, C#Script
var p1, w1, w2;
p1 = Sys["Process"]("notepad");
w1 = p1["Window"]("#32770", "Open", 0);
w2 = w1["Window"]("Button", "&Open", 1);
w2["ClickButton"]();
TestComplete automatically determines the window type by the window’s class name (see the previous section) and adds type-specific methods and properties to the window
object that corresponds to that window. You can call these methods and properties to perform operations specific to the control, for instance, if a window is a tree view control, you can use specific methods to simulate clicks and double-clicks over tree view nodes. TestComplete provides extended support for almost all types of standard controls (see List of Win32 Controls). Besides, TestComplete supports recent Windows Presentation Foundation, .NET and Java controls, as well as a number of popular third-party components. Furthermore, using object mapping, you can set up TestComplete so it handles a custom control as if it is a standard one. See Supported Controls.
It is possible that an object will contain several methods or properties with the same name. For instance, an object of an Open Application may contain the method Click
and TestComplete may add a method of the same name to this object. If you then call the Click
method of this object in your scripts, the script engine will use the method provided by TestComplete, not the method defined in your application. To call the latter, use the appropriate namespace: NativeClrObject
, NativeVBObject
, NativeCPPObject
or another. For detailed information on namespaces and how to use them, see Using Namespaces.
For complete information on simulating user actions, see Simulating User Actions.
4. Retrieve Data From the Tested Application
TestComplete automatically determines the type of a control (buttons, tree view, list box, etc.) and adds specific methods and properties to the window
object corresponding to this control (see the Addressing Processes, Windows and Controls section above). Using these methods and properties you can obtain data held in the desired controls.
If TestComplete cannot associate the control used with any standard Win32 control, then you can try compiling your application as an Open Application. Open Applications provide access to their internal objects, methods and properties, and using these methods and properties you should be able to obtain data stored in the desired control.
Note: | An object may contain several properties having the same name (for instance, an object of an Open Application may contain the property Left and TestComplete may add a property of the same name to the object). If you address the Left property of this object in your scripts, TestComplete will use its property, not the property defined in your application. To call the latter, use namespaces. |
For complete information on how to obtain data from windows and controls, please see Interacting With Non-Compatible Application Objects. You may also find the Working With Grids section helpful.
5. Post Messages to the Test Log
To post messages to the test log, use methods of the Log
object. Using these methods you can post messages of different types (error, warning, informative and other). The following code snippet posts error, warning and informative messages to the log:
JavaScript, JScript
Log.Error("Message Text 1", "Extended Message Text 1");
Log.Warning("Message Text 2", "Extended Message Text 2");
Log.Message("Message Text 3", "Extended Message Text 3 ");
Python
Log.Error("Message Text 1", "Extended Message Text 1")
Log.Warning("Message Text 2", "Extended Message Text 2")
Log.Message("Message Text 3", "Extended Message Text 3 ")
VBScript
Log.Error "Message Text 1", "Extended Message Text 1"
Log.Warning "Message Text 2", "Extended Message Text 2 "
Log.Message "Message Text 3", "Extended Message Text 3 "
DelphiScript
Log.Error('Message Text 1', 'Extended Message Text 1');
Log.Warning('Message Text 2', 'Extended Message Text 2');
Log.Message('Message Text 3', 'Extended Message Text 3');
C++Script, C#Script
Log["Error"]("Message Text 1", "Extended Message Text 1");
Log["Warning"]("Message Text 2", "Extended Message Text 2");
Log["Message"]("Message Text 3", "Extended Message Text 3");
Each message can have an image that is posted with it. The message parameters let you specify color and font style of a message. Besides messages of various types, you can also post images and file links (see methods of the Log
object). The Log
object also includes special methods that let you organize log messages into folders.
For complete information on posting messages and images to the log, see Posting Messages, Images and Files to the Log.
6. Database Access
To work with databases from your tests directly, use the TestComplete ADO
object. You can also create ADO objects as COM objects.
Notes:
-
This example uses the OrdersDB.mdb file that is part of the additional sample package. To use it, download this package from support.smartbear.com/testcomplete/downloads/samples and install it. After the installation is over, you can find the database in the <TestComplete 15 Samples>\Desktop\Checkpoints\XML\DataGridViewSample folder.
-
Using the Microsoft.Jet.OLEDB.4.0 provider requires that you run your script in the 32-bit version of TestComplete.
TestComplete 32-bit executable is located in the <TestComplete>\Bin folder.
JavaScript
function TestProc()
{
var AConnection = getActiveXObject("ADODB.Connection");
// Specify the connection string
AConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;" +
"Data Source=C:\\Users\\Public\\Documents\\TestComplete 15 Samples\\Desktop\\Checkpoints\\XML\\DataGridViewSample\\OrdersDB.mdb";
// Activate the connection
AConnection.Open();
// ...
}
JScript
function TestProc()
{
var AConnection = new ActiveXObject("ADODB.Connection");
// Specify the connection string
AConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;" +
"Data Source=C:\\Users\\Public\\Documents\\TestComplete 15 Samples\\Desktop\\Checkpoints\\XML\\DataGridViewSample\\OrdersDB.mdb";
// Activate the connection
AConnection.Open();
// ...
}
Python
def TestProc():
AConnection = Sys.OleObject["ADODB.Connection"]
# Specify the connection string
AConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;" + \
"Data Source=C:\\Users\\Public\\Documents\\TestComplete 14 Samples\\Desktop\\Checkpoints\\XML\\DataGridViewSample\\OrdersDB.mdb";
# Activate the connection
AConnection.Open();
# ...
VBScript
Sub TestProc
Set AConnection = CreateObject("ADODB.Connection")
' Specify the connection string
AConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;" + _
"Data Source=C:\\Users\\Public\\Documents\\TestComplete 15 Samples\\Desktop\\Checkpoints\\XML\\DataGridViewSample\\OrdersDB.mdb"
' Activate the connection
AConnection.Open
' ...
End Sub
DelphiScript
function TestProc;
var AConnection;
begin
AConnection := Sys.OleObject('ADODB.Connection');
// Specify the connection string
AConnection.ConnectionString := 'Provider=Microsoft.Jet.OLEDB.4.0;' +
'Data Source=C:\Users\Public\Documents\TestComplete 15 Samples\Desktop\Checkpoints\XML\DataGridViewSample\OrdersDB.mdb';
// Activate the connection
AConnection.Open;
// ...
end;
C++Script, C#Script
function TestProc()
{
var AConnection;
AConnection = Sys["OleObject"]("ADODB.Connection");
// Specify the connection string
AConnection["ConnectionString"] = "Provider=Microsoft.Jet.OLEDB.4.0;" +
"Data Source=C:\\Users\\Public\\Documents\\TestComplete 15 Samples\\Desktop\\Checkpoints\\XML\\DataGridViewSample\\OrdersDB.mdb";
// Activate the connection
AConnection["Open"]();
// ...
}
For more information on database access from scripts and for code examples, see Working With Databases.
7. Call Project Elements From Scripts
For each project item TestComplete provides special program objects that let you work with project items from scripts. For instance, these objects let you execute tests provided by project items, or get project items’ property values.
You can address project elements from scripts using the element name as it is shown in the Project Explorer panel. For more information on calling project items from scripts, see Calling Project Items From Scripts.
See Also
Script Tests
About Script Tests
Object Identification
Handling Exceptions in Scripts
Using Namespaces
Working With Application Objects and Controls