Writing Scripts - Quick Start

Applies to TestComplete 15.45, last modified on December 01, 2022

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

TestedApps["Items"](0)["Run"](1);

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 or FindId 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 and ChildCount properties of the process 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:

Copying window name 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 Options.Project.General.TreeModel property.

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:

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

Highlight search results