Writing Scripts - Quick Start

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.

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:

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:

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.

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:

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:

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:

p = Sys.WaitProcess("Notepad", 2000)
if not 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:

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.

p1 = Sys.Process("MyApp")
w1 = p1.WinFormsObject("MainForm")

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:

p1 = Sys.Process("MyApp")
w1 = p1.Window("WindowClassName", "WindowCaption", 1)
# or
w1 = p1.WaitWindow("WindowClassName", "WindowCaption", 1, 2000)

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:

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

p1 = Sys.Process("MyApp")
w1 = p1.WinFormsObject("MainForm")
w2 = 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.

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.

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

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.

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.

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.

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:

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.

To work with databases directly from your scripts, use the TestComplete ADO and BDE program objects.

Using the ADO object you can work with databases via Microsoft ADO objects, methods, and properties. The BDE object lets you work with databases via wrappers of VCL data-aware objects for BDE access.

An alternative to using ADO and BDE, is the creation of ADO objects as COM objects from scripts.

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

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();
  # ...

For more information on database access from scripts and for code examples, see Working With Databases.

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.