TestComplete 7

Introduction

INTRODUCTION.............................................................................................................................................5Introducing TestComplete...............................................................................................................................5

Difference Between Standard and Enterprise Editions...................................................................................5

System Requirements......................................................................................................................................8

Supported Development Tools......................................................................................................................10

Technical Support and Resources.................................................................................................................11

GETTING STARTED....................................................................................................................................13Product Overview..........................................................................................................................................13

TestComplete User Interface.....................................................................................................................13About Projects and Project Items.............................................................................................................14Tests and Test Items..................................................................................................................................16Stores and Checkpoints.............................................................................................................................17TestComplete's Test Log...........................................................................................................................18Working With Applications' Windows and Controls.................................................................................20Testing Through Application Code...........................................................................................................21

Creating Tests With TestComplete...............................................................................................................22Creating a Test Project.............................................................................................................................22Defining Applications to Test....................................................................................................................24Exploring the Application in the Object Browser.....................................................................................28Planning Tests...........................................................................................................................................35Recording a Test.......................................................................................................................................37Analyzing the Recorded Test.....................................................................................................................42Creating Checkpoint.................................................................................................................................49Organizing Tests.......................................................................................................................................57Running Test..............................................................................................................................................59Analyzing Test Results...............................................................................................................................60Searching for the Reason of an Error.......................................................................................................68

NAMING OBJECTS......................................................................................................................................70Naming Processes.........................................................................................................................................71

Naming Windows..........................................................................................................................................72

Naming Controls and Objects.......................................................................................................................76

Naming Web Objects....................................................................................................................................79

KEYWORD TESTING IN TESTCOMPLETE...........................................................................................80Keyword Tests – Overview...........................................................................................................................80

Creating and Editing Keyword Tests............................................................................................................82

About Operations, Their Parameters and Result Values...............................................................................83

Running Tests................................................................................................................................................85

Parameters of Keyword Tests.......................................................................................................................86

Keyword Test Variables................................................................................................................................86

Debugging Keyword Tests............................................................................................................................87

Keyword Tests vs. Scripts.............................................................................................................................87

Creating Custom Keyword Test Operations.................................................................................................87

www.automatedqa.com TestComplete by AutomatedQA Corporation

2

Introduction

SCRIPTING IN TESTCOMPLETE.............................................................................................................88Writing Scripts – Overview..........................................................................................................................88

Selecting the Scripting Language..................................................................................................................90

Writing Scripts – Quick Start........................................................................................................................91

Calling Routines and Variables Declared in Another Unit.........................................................................102

Supported Scripting Languages – Peculiarities of Usage...........................................................................107

Index................................................................................................................................................................115

© 2009 AutomatedQA Corp. www.automatedqa.com/support

3

Introduction

Introduction

Introducing TestCompleteTestComplete is an automated testing environment for Win32, .NET and WPF applications. It provides extended support for testing Web pages, Web servers and projects created in Microsoft Visual C++, Visual Basic, Borland Delphi, C++Builder, Java, .NET and WPF development tools.

TestComplete manages scripts to test applications externally, self-testing by the applications themselves, and many inside-outside forms of tests. It is oriented equally to unit testing and to functional testing, provides superior support for daily regression testing and supports many other kind of testing (data-driven testing, object-driven testing, etc.)

If you are new to TestComplete, see Getting Started to learn how to use the product.

To get to know basic concepts, please read TestComplete - Product Overview (this topic is part of the Getting Started section).

A note about plug-ins: TestComplete’s entire architecture is COM-based. Most of the features you see in the product are supported through plug-ins. When the plug-in is meant to remain for the life of the current version, it is made an internal part of TestComplete.exe. When it is possible that the plug-in could be updated, it is left external (such as the database-access plug-ins). Others will be added to the AutomatedQA Web site (http://www.automatedqa.com), and users can write their own plug-ins using the supplied interface documentation and libraries – several user-contributed plug-ins are in http://www.automatedqa.com/downloads/plugins.asp.

In fact, there are so many “open” features to TestComplete that we have put a checklist into a separate topic, Open Access.

Difference Between Standard and Enterprise EditionsThere are two editions of TestComplete: Standard and Enterprise. The following matrices explain differences between them.

Features Supported by Both Standard and Enterprise Editions

Features Standard Edition Enterprise Edition

Black-box testing(functional testing of any Windows application)

+ +

Extended support for .NET applications + +

Extended support for Microsoft Visual C++ applications + +


4

http://www.automatedqa.com/downloads/plugins.asp

http://www.automatedqa.com/

Supported Scripting Languages – Peculiarities of Usage

Extended support for Microsoft Visual Basic applications + +

Extended support for Java applications + +

Extended support for Borland Delphi applications + +

Extended support for Borland C++Builder applications + +

Support for 64-bit applications + +

Extended support for applications using Microsoft Active Accessibility (Microsoft Visual FoxPro, Microsoft Access, etc.)

+ +

UI Automation technology support + +

Extended support for WPF (XAML) applications + +

Extended AQtime integration and coverage testing + +

Testing applications running under another user account + +

Support for third-party grid controls + +

Support for third-party menus + +

Scripting and script debugging + +

Keyword testing + +

Event handling + +

Unit testing(including support for MSTest, JUnit, NUnit and DUnit unit tests)

+ +

Functional testing (or user interface testing) + +

ActiveX objects support + +

Low-level recording and playback + +

Name mapping + +

Object-driven testing + +

Data-driven testing + +

Source code control integration + +

User forms + +

Calling Win32 API routines + +

Calling functions located in .NET assemblies + +

Calling functions located in DLLs + +

ADO and BDE support + +


5

Introduction

Compression of test results + +

Features Available in the Enterprise Edition Only

Features Standard Edition Enterprise Edition

HTTP load testing - +

Network suite (distributed testing) - +

Testing applications running on PDAs - +

Functional testing of web pages (web testing) - +

Testing of Flash applications - +

Testing of web services - +

Optical character recognition - +

Integration With Microsoft Visual Studio and Team System - +

Issue-tracking support - +

CORBA support - +

TestExecute - +

TestRecorder - +

TestComplete Enterprise Edition includes special plug-ins that allow you to simulate virtual users and perform the load, stress and scalability testing of your Web servers. The basic TestComplete Enterprise license supports 5 virtual users. These users can be simulated on the workstation where TestComplete is installed. There are also versions available that support more virtual users:

TestComplete Enterprise Edition with 50 virtual user license. This license allows you to simultaneously simulate from 1 to 50 virtual users on a computer where TestComplete is installed.

TestComplete Enterprise Edition with 250 virtual user license. This version includes a special software package, TestComplete HTTP Load Testing Remote Agent, that lets you simulate virtual users on several network computers. If you have this license, you can install TestComplete on one workstation and install the HTTP Load Testing Remote Agent on any number of workstations. The HTTP Load Testing Remote Agent includes all functionality needed to simulate virtual users. There is no need to install TestComplete on workstations where the HTTP Load Testing Remote Agent is installed. You can share virtual users among workstations, but the total number of virtual users working simultaneously cannot exceed 250.

TestComplete Enterprise Edition with unlimited virtual users. Like the license with 250 virtual users, this one also includes the TestComplete HTTP Load Testing Remote Agent. If you have this license, you can simulate any number of virtual users working simultaneously on any number of workstations. The number of virtual users per workstation cannot exceed 300 (this restriction is caused by certain operating system limitations). If you need to simulate, for example, 600 users, you would need to use two workstations.


6


For detailed information, please visit AutomatedQA's web site:

Supported Development Tools“Will TestComplete test my application?” - This is probably one of the first questions our clients ask about TestComplete. As a matter of fact, TestComplete does not depend on any development tool. It can simulate user actions (keypresses, mouse movements and clicks) under any application no matter whether this application was created in C#, Visual C++, Delphi or Java. However, in most cases, this kind of testing (testing via GUI) cannot provide reliable and thorough results. Quite often, QA engineers need access to the application internal objects, methods and properties. This is required, for example, for unit testing. You can get this access using TestComplete. It can “open” internal objects, methods and properties up to private object elements in the application under test.

Below is a list of major development tools, software platforms and application types supported by TestComplete::

All existing .NET compilers. For instance:

Microsoft: Visual C#, Visual Basic .NET and Visual C++ .NET (managed code) ver. 7.0, 7.1, 8.0 and 9.0 (Visual Studio ver. 8.0 only with Service Pack 1 installed), JScript .NET

Non-Microsoft: Borland C#Builder, Borland Delphi for .NET (Delphi 8, Delphi 2005 and 2006), CodeGear Delphi (2007 - 2009), Python .NET, Cobol .NET, Perl .NET, and others.

TestComplete supports applications created for .NET Framework ver. 1.0, 1.1, 2.0, 3.0 and 3.5.

Microsoft Visual C++ 6.0, Visual C++ (unmanaged code) ver. 7.0, 7.1, 8.0 and 9.0 (Visual Studio ver. 8.0 only with Service Pack 1 installed).

Intel C++ Compiler 11.0.066

64-bit .NET, Java, Windows and Qt applications (see Testing 64-bit Applications in TestComplete help).

Microsoft Visual Basic 6.0

Borland Delphi 3.0 - 7.0, Delphi 2005 and 2006, CodeGear Delphi 2007 - 2009

Borland C++Builder 3.0 - 6.0, C++Builder 2006, CodeGear C++Builder 2007 - 2009

Any Java development tool that supports one of the following Java virtual machines:

Sun JDK (or JRE) v. 1.1.8 - 1.6. TestComplete also supports 64-bit JRE 1.6 applications.

MSVM, build 3309 or later

BEA JRockit 5.0

For instance, you can use Microsoft Visual J++ 1.1, Borland JBuilder 3.0, Sun Forte 1.0 and other development tools. The AWT, SWT, Swing and WFC library classes are also supported.

Macromedia Flash 1.0 - 8.0, Adobe Flash 9.0 and later

Any Flex development tool. For example, Adobe Flex Builder 2.0 and later


7

Introduction

Microsoft Silverlight 2

Qt ver. 4.5.0 by Qt Software (32-bit and 64-bit Qt applications are supported)

Sybase PowerBuilder 10.0 and later

Microsoft FoxPro 7.0 and later

Microsoft Office Access 2003 and 2007

Microsoft Office InfoPath 2003 and 2007

Since TestComplete can test any Windows application via GUI, it can simulate keypresses and mouse clicks in any Internet browser. This allows you to test Web pages working with any Internet browser. However, currently, you can only access properties and methods of HTML elements on a Web page shown in Internet Explorer, Firefox or in any instance of the Web Browser control. See Web Testing in TestComplete help for complete information on this.

As for the performance, load, stress and scalability testing of Web servers, they do not depend on Internet browsers (Internet Explorer, Netscape Navigator, Mozilla, Opera, and so on), the server type (Microsoft IIS, Apache, and so on) or platform (Windows, Linux, and so on) That is, with TestComplete you can perform these kinds of testing for any Web server working on any platform. Please see Load, Stress and Scalability Testing of Web Servers With TestComplete in TestComplete help.

Getting Started

Product Overview

TestComplete User Interface

TestComplete’s user interface is organized into a number of panels:


8


The Project Explorer panel displays the contents of projects and the project suite: tree of project items, their child elements and test log nodes. The Workspace panel is your working desktop: it displays project items’ editors, where you create and modify tests, and shows test log pages that display test results.

Besides the Project Explorer and Workspace, TestComplete contains other panels. For instance, the Watch List, Locals, Breakpoints and Call Stack panels are used for test debugging. The To Do panel manages a list of tasks to be done and the Code Explorer panel provides a convenient way to explore the contents of and navigate through script units.

The Object Browser panel holds one major TestComplete function that does not belong to a specific project. The Object Browser maps all processes currently running on the machine, whether they are an application for testing, a basic operating system service like the Explorer process, or some other application like Internet Explorer or TestComplete itself. For each process it shows all objects accessible externally through TestComplete facilities, and all of the accessible object properties and methods. In other words, the Object Browser tells you which methods and properties are available for testing, and how to get to them. See Exploring Application Properties in TestComplete help.


9

Introduction

The panel’s layout is not strictly defined. You can change the panels’ width and height as your needs dictate, or undock panels and dock them to another edge of TestComplete’s window. For more information, see Docking in TestComplete help.

To command TestComplete to perform certain actions, you use menus and toolbars. The menu subsystem used in TestComplete is very similar to the menus and toolbars or Microsoft Visual Studio or other popular products. You can change the toolbars location, move items from one menu or toolbar to another, hide items and add hidden items back to the menus and toolbars and perform other tasks. For more information, see Toolbars Customization in TestComplete help.

Many of TestComplete’s panels and dialogs display lists or tables. You can modify the column and view as your needs dictate. For instance, (with some exceptions) you can typically change the columns’ position and width, sort and group panel contents on a column, hide or display columns and so on. For more information on this, see Arranging Columns, Lines and Panels in TestComplete’s help.

About Projects and Project Items

Similar to program development tools, such as Microsoft Visual Studio or Borland Delphi, the primary unit of management in TestComplete is a project. A project contains data and files (project items) that are needed to perform tests as well as a cumulative log of all test runs since the start of the project.

Related projects can be united into a project suite that contains one or more projects. TestComplete automatically generates a project suite when you create a new project. You can also create empty project suites and then use TestComplete’s dialogs to fill the suite with the desired project files.

Project items are elements that perform various testing operations or assist in performing these operations. Each project item is a collection of child items and files. By default, the child items are stored in files located in subfolders of the project’s folder.

The Project Explorer panel provides a graphical interface to view and manage the projects, project suites and project items:


10


For complete information on project items available in TestComplete, see About Project Items in TestComplete help.

For each type of project item and their child elements, TestComplete offers specific editors, where you can view and change the project item’s contents. To modify properties of a project item or its child element, double-click the item or element in the Project Explorer or right-click the desired node and choose Edit from the context menu (if the editor contains several pages, the Edit menu item lists them as subitems):


11

Introduction

TestComplete will show the property editor in the Workspace panel.

In addition to the editor displayed in the Workspace panel, TestComplete offers other helper panels and windows for some project items to make editing more convenient. For instance, TestComplete includes the Code Explorer panel which makes it easier to navigate through script units.

Tests and Test Items

Most project items or their child elements can be used to perform testing actions. For instance, the KeywordTests item contains keyword tests that can be used to simulate user actions; the same applies to script routines and low-level procedures that are child elements of the Script and Win32 Low-Level Procedures items; the UnitTesting item is a collection of items that run unit tests defined in the application’s code; NetworkSuite manages distributed tests, HTTP Load Testing can simulate the user activity over a web server, and so forth.

Tests can be recorded or created from scratch in the appropriate test editor. The only exception is unit tests, they cannot be recorded.

After creating or recording a test, you can run it from the test editor or from the Project Explorer panel. That is, the project items or their child elements can act as a source of the entire test.

You can also specify a sequence of tests to be executed when the test project is executed. In this case, the tests defined in the project act as part of a bigger test (project test). We call these parts test items. The sequence of test items to be run is specified in the Test Items page of the project editor:


12


For each test item you can specify the test to be run, test parameters (if needed), the number of times the test will be repeated, the action that the test engine will execute if an error occurs during the test run, and some other parameters.

You can easily include or exclude a test item from the test run by selecting or clearing the test item’s check box in this page. Test items can have child items or they can be organized into groups and subgroups for easier management. By selecting or clearing the check box of a parent item or a group, you can include child items into or exclude them from the project test run.

A project itself can be used as a test item when you create tests for project suites in the Test Items page of the project suite editor.

Stores and Checkpoints

A typical test performs a lot of comparisons. For instance, if a test simulates some user actions like clicking on menu items and exporting an application’s data to a file, you may need to check whether the file contains valid data. To perform this check, you may compare the resulting file with its baseline copy. This is only one example of a comparison that you may need to perform. Real-life tests includes hundreds and thousands of comparisons. Every form of testing (regression, unit, functional and so on) need a validated reference during automation.

To support the comparison, TestComplete offers the Stores project item. This project item contains various elements that are saved along with the project for comparison purposes. We call the comparison or verifying operations checkpoints. The Stores project item contains elements that are used to create checkpoints.

The elements are organized into a number of collections. Currently, the item includes the following collections:

Regions - Contains elements used to compare images and find one image within another.


13

Introduction

Files - Contains elements used to compare files.

Objects - Contains elements used to compare properties of an object or window.

DBTables - Contains elements used to compare and verify data of a database table, view or query.

Tables - Contains elements used to verify data of controls that display information in tabular form as well as data of list view, list box and combo box controls.

WebTesting - Contains elements used to verify web pages and compare them.

XML - Contains elements used to compare XML documents and check web service responses.

TestComplete includes a lot of special keyword test operations and scripting objects that lets you easily perform the comparison (or verification) operations in your keyword tests and scripts.

You can create checkpoints at design time by selecting items of the Tools toolbar or by adding the appropriate operations to your keyword tests. You can also create checkpoints during test recording through the Add Checkpoints item of the Recording toolbar:

When you command the test engine to create a checkpoint, it displays a dialog or wizard, where you can specify the checkpoint parameters. After closing the dialog (or wizard), TestComplete inserts the checkpoint operation into your keyword test or generates the script statements used for verification, which you can then insert into your script code. Of course, if you have scripting experience, you can write verification code from scratch, without using special dialogs and wizard.

For more information on creating checkpoints and verification code, see About Checkpoints in TestComplete help.

TestComplete's Test Log

Each project holds a log of all project runs. In fact, the best definition of a project is “what TestComplete maintains a log for”. Everything else is secondary. The log is where you get the results of the entire testing exercise.


14


The basic unit of the log is a test. The log itself is an object that can be called in scripts or code. You launch a test by any one of the many options to run a test, for example, right-clicking a project or project item in the Project Explorer panel and selecting Run from the context menu. The log is smart enough to know that the current test starts when the project item’s execution begins, and ends when the execution stops. A project item (for example, a keyword test) can call other project items or run applications that access the test log - the “current test” goes on until the execution of the “parent” item is finished. The only thing you cannot do is run several tests on the same computer in parallel.

For each test, the log records start, stop, duration and completion (non-completion means the test could not continue to the end).

The log has a tree-like structure similar to the structure of the executed test items. Each node in this tree has a specific format of results. This format depends on the project item, in which a test item is based. For instance, the log of a script execution is a tree-like structure of various kinds of messages. TestComplete supports a large variety of ways to differentiate these messages:

It automatically logs the exact message time, so you can get the time spent between any two messages.

Each message is posted according to one of the following message types - Error, Warning, Picture, File, Link, Event and the ordinary Message (called information message in the Help to differentiate it from other messages).

Each message also has a priority level.

Messages contain text and additional comments (or remarks). Each message can also have an image associated with it.


15

Introduction

Related messages can be organized into folders within the log.

Finally, filters can be defined to create reports of any type.

If your test does not post messages to the log, the only messages you will find are possible error messages from TestComplete itself. Therefore, unless you are simply trying out a test, the one thing it must do is post messages. This cannot be recorded, you have to use special keyword test operations or call scripting methods for this.

You can easily find what keyword test operation or script line posted a message to the log. To do this, simply double-click the message in the log. TestComplete will automatically open the keyword test or script editor and position the cursor to the appropriate line in them.

Working With Applications' Windows and Controls

To work with processes, window and controls existing in the system, TestComplete uses special objects that correspond to processes, windows and controls. TestComplete determines the type of the window or control under test and automatically adds specific methods and properties to the objects that correspond to these windows and controls. Using these methods and properties you can simulate user actions on the windows and controls or obtain information about their contents and state.

The Object Browser panel shows a lot of detail about applications running in the operating system and their windows and controls. It also displays the methods, properties and actions that can be used in your tests.

By default, the processes and windows only contain methods and properties provided by TestComplete. You can use them to test your application via the GUI, that is, to simulate keystrokes and mouse actions over windows and controls and to check certain windows’ attributes (like style, text and visibility).

This may be enough to create simple tests, but quite often, testing routines need access to those methods and properties that are provided by the tested application. In other words, they require access to the objects, methods and properties provided by the programming libraries that were used to create the application (WinForms, MFC, VCL, SWT, AWT and others).

If applications test themselves using their own code, then access to the applications’ internal objects is usually not a problem. However, even if applications are tested externally (for instance, with TestComplete scripts), there is no reason to use a simple GUI-test. Where possible, tested applications should be Open Applications, that is, they should provide access to their internal objects, methods and properties.

TestComplete comes with special plug-ins that “open” various types of applications - .NET, Visual C++, Visual Basic, Delphi, C++Builder, WPF, Java and Qt. In addition, TestComplete has an exclusive technology called Debug Info Agent™ that works with tests to access practically all internal elements of the application under test, even private properties. To “open” some applications, you may need to recompile them, some other applications are “open” automatically without recompiling.

Once your application is “open” look at it through the Object Browser. You will see that making the application “Open” has multiplied the access to application objects for your test code. You can test much closer to the design level, and much more conveniently. Depending on the level of “openness”, you can use public, protected and even private methods, fields and properties in your tests.

TestComplete also includes two special plug-ins that provide deeper access to applications’ internals in comparison to the default access. One of these plug-ins, UI Automation Support, retrieves window properties provided by Microsoft UI Automation Framework. Another special plug-in, MSAA Open Applications, exposes methods and properties of windows that implement the IAccessible interface. This lets you work


16


with windows of Sybase PowerBuilder, Microsoft Access, Visual FoxPro and other applications. You can see the objects, methods and properties, exposed by these plug-ins, in the Object Browser panel.

Testing Through Application Code

TestComplete’s services are provided through an OLE server. The entire user interface is simply a client of this server. By linking in just one file, an application can put itself in the place of the TestComplete user interface and run the OLE server directly, for whatever purpose. We call this a Connected Application.

The most common thing a Connected Application will do is run tests in its own source code (see Self-Testing Applications in TestComplete help). This is usually the easiest way to do unit tests (see Testing With TestComplete in TestComplete help).

Connected Applications can also be used to run tests on other applications. This way of testing provides more control over test conditions, since the TestComplete engine is commanded from source code rather than the user interface. For instance, you might want to run a specific series of tests at a given time, and which tests are to be run would depend on the conditions at that time. All of these can be done from a rather simple Connected Application.

Also, using Connected Applications simplifies the test creation because it is convenient to write test code in your normal programming language and use the preferred IDE for debugging.

Of course, application code in a Connected Application still has access to all of the objects a script uses. These are all OLE objects, and the needed interface is in the file that you link to.

The following figure explains the relations between TestComplete and other applications (Open, Connected and General applications):


17

Introduction

Creating Tests With TestCompleteThis section provides a step-by-step tutorial that describes how to create a test project in TestComplete, record and play back a simple test and analyze results.

To demonstrate the testing operations, we will use the Orders application that is shipped along with TestComplete and is located in the following folder:

On Windows Vista, Windows Server 2008:

C:\Users\Public\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo

On Windows XP, Windows Server 2003, Windows 2000, Windows NT:

C:\Documents and Settings\All Users\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo

Note that in Windows Explorer and in other Open and Save dialogs, the All Users\Documents folder may be displayed as All Users\Shared Documents.

The folder stores several Orders projects created with different compilers: C#, Visual C++, Visual Basic, Delphi, C++Builder, Swing and so on. We will use the Orders application created with Visual C#.

Creating a Test Project

Projects contain all of the information about one or more applications that you test as well as data, scripts, a baseline copy of files and images, and other information needed to perform a test. For a complex application you may choose to devote a project to just one part of the application, and other projects to other parts (normally, modules).

Let’s create a new test project:

Close the project suite opened in TestComplete. To do this, choose File | Close from TestComplete’s main menu.

Select File | New | New Project from TestComplete’s main menu. This will call the Create New Project dialog. This dialog may function in two modes: Simple and Classic. In Simple mode, which is enabled by default, the dialog contains only three edit fields in which you can specify the project name, location and scripting language. In Classic mode you can also specify the project suite name and choose the project’s template and project items.

In this tutorial we will use the Simple mode since this is the most commonly used mode:


18


Let’s now specify the project name, location and scripting language. To do this, in the dialog:

Enter Orders as the project name.

TestComplete will automatically generate the project path and display it in the Location field. The project folder is used to store all information generated for or by the project -- keyword tests, scripts, test logs, stores, and so on. You can change the project’s folder in the Location box. In our example we will keep the folder name unchanged.

In the Language box specify the scripting language that will be used by the project. We will select VBScript.

Scripting language is important even if you are not going to use script units in your project. Even if you are going to use keyword tests, you may need to call code snippets or use script statements to specify operation parameters.

The scripting language is also important because it defines the format of object names with which your tests will work. These names will be used both in scripts and keyword tests and the name format depends on the language syntax. For instance, in VBScript and JScript the name of the Notepad process looks like Process("Notepad"). In DelphiScript you should replace quotes with apostrophes: Process('Notepad'); and in C++Script and C#Script the word Process should be enclosed in brackets: ["Process"]("Notepad").

TestComplete is equally oriented to VBScript, JScript, DelphiScript, C++Script and C#Script, therefore it allows you to select the language you know. You will be able to use all of TestComplete’s features regardless of the language you choose. However, due to the fact that languages have different syntax and their script instructions are executed by different scripting engines, there are some exceptions (see Supported Scripting Languages - Peculiarities of Usage). For more information on choosing the language, see Selecting the Scripting Language.

We would like to also note that the scripting language does not depend on your tested application’s programming language. For instance, you can use JScript to test Visual C++ applications, or VBScript to test Delphi programs. There is one recommendation: if you plan


19

Introduction

to create a Connected or Self-Testing Application, you should select the language that matches the development tool that the application was created in. For example, if you use Visual C++ or C++Builder, you should select C++Script; if you use Visual Basic, select VBScript, and so forth. This will make it easier to import recorded scripts to Connected and Self-Testing Applications.

After you specified the project name, scripting language and location, press Create. TestComplete will create a new project, Orders.mds, and a project suite for it. It will then display the project suite’s and project’s contents in the Project Explorer panel.

Defining Applications to Test

Each project may have a list of tested applications. This is a way for you to keep track of which applications the project deals with and how they are configured for testing. It also allows TestComplete to launch all applications in the list or only those applications that are enabled to be launched manually via the context menu, or from a keyword test or script. Of course, since projects are independent from one another, any application may be in more than one project’s list.

To maintain the list of tested applications, TestComplete includes two project items: Tested Applications and WinCE Tested Applications. The first item lets you manage applications that run on PC, the WinCE item is a collection of applications that will run on a PDA device. In this tutorial, we will use a “traditional” PC application, not a mobile one.

You can append Windows applications to the list of tested applications manually, or TestComplete can do this automatically during test recording. The recorder is smart enough to detect a start of an application through a command line, Windows Explorer or any other way. After the recording is over, TestComplete will add the tested application to the list and insert the “launch application” command into the recorded test. You can turn off this functionality by disabling the Automatically add applications to the Tested Applications list setting in the Recording Options dialog.

Though the setting is enabled by default, in this tutorial we will add the tested application to the list manually. We will do this to get you acquainted with the list and to demonstrate the features it provides for managing applications under test.

The test project that we created on the previous step already contains the Tested Applications item. It is shown in the Project Explorer panel as the TestedApps node:


20


Let’s add our sample application to the tested applications list. As you may remember, we were going to use the sample Orders application created in C# and shipped with TestComplete. The path to Orders.exe looks like this: C:\Documents and Settings\All Users\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo\C#\bin\Debug\Orders.exe (if you are working under Windows XP), or C:\Users\Public\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo\C#\bin\Debug\Orders.exe (if you are working under Windows Vista).

To add this application to the project:

Right-click the TestedApps node in the Project Explorer panel.

Choose Add | New Item from the context menu. This will invoke the standard Open File dialog.

Locate Orders.exe using this dialog and then click Open.

Now, the sample application is in the list and we can specify command-line arguments for it:

Double-click the TestedApps | Orders node in the Project Explorer panel. TestComplete will show the available settings in the TestedApps editor.


21

Introduction

Now select the application’s run mode. A tested application can be launched in several modes: Simple, RunAs, Debug or Profile. The Simple mode is similar to launching the application from Windows Explorer or the command line window. Using the RunAs mode you can launch the application under a different user account than TestComplete is currently running under. Debug mode is similar to Simple, but TestComplete will act as a debugger for the application and will report information about events and errors that occur during the application run. Finally, Profile mode is used to debug and profile the application with AQtime. For more information on these modes, see Run Modes in TestComplete help.

For our sample application we will use the Simple run mode. This mode is used by default for tested applications. Look at the Run Mode column and make sure the Simple mode is selected:

Now we will change the application’s command line. To do this, press the ellipsis button within the Parameters column. This will call the Parameters dialog.

Type -NOTOPENAPP or /NOTOPENAPP in the Command-line parameters edit box. We will explain this command-line argument later (see Exploring the Application in the Object Browser).


22


Press OK to close the dialog.

Save your changes by selecting File | Save from TestComplete’s main menu.

As you can see, all application parameters (command line, work folder and so on) can be set in one place.

As stated above, one purpose of the tested applications list is to provide you with a way to launch all applications before you start recording or playing a test. Of course, you can record the launch of an application, but it is easier and more adaptable to have all of the launch specifications that you may need in the list, and to uncheck anything that is not needed for the current run (in the Launch column).

In the next steps we will explore which internal objects, methods and properties of the tested application are available to TestComplete and then will record user actions on the application.


23

Introduction

Exploring the Application in the Object Browser

Before creating tests, you may need to explore the object structure of your application to know what properties, fields, methods and events of your applications’ objects TestComplete has access to. You get this information from the Object Browser panel. It shows you exactly what is available to your tests.

Let’s explore our sample application in this panel:

To launch the application, right-click the application node (Orders) in the Project Explorer panel and select Run from the context menu (the application node is a child node of the TestedApps node). Wait until the application’s main window appears on screen.

Switch to the Object Browser panel and find the application in the tree view on the left:

If the tree contains too many processes, you can filter it to only view the tested applications. To do this, click Show Tested Applications Only on the Object Browser’s toolbar.

The applications that belong to the Tested Applications list are displayed in bold. Some applications may have the icon displayed next to them. This icon indicates that the application is an Open Application or that some internal objects of this application are exposed by the Open Application feature of TestComplete.


24


Note: If you use Windows Vista or Windows Server 2008 and you do not see an existing process in the Object Browser, most likely the process and TestComplete have different permissions. In order for TestComplete to be able to test applications under Windows Vista and Windows Server 2008, it must have the same permissions as the application. See Testing Applications With TestComplete Under Windows Vista and Windows Server 2008 in TestComplete help.

Expand the application node and look at its windows and their properties. The right pane displays properties and methods that can be used in tests:


25

Introduction

Note: The image above displays the properties, methods and objects of the Orders application created in C#. The properties, methods, window class names and the whole object structure that you see in the Object Browser on your computer may differ from what is displayed in the image. The information you see depends on the development tool, which you used to compile the tested application. For instance, the objects’, methods’ and properties’ names as well as the object structure of Visual C++ 6 applications differ from those of .NET applications.

As you can see, all processes are direct children of System (the Sys object), and windows are children of the processes that opened them. In TestComplete terms, processes and windows are objects, and this is how they are represented in keyword tests and scripts.

The process name includes the word Process followed by the name of the executable that started the process, for instance, Process("Orders"). The name may also have the second parameter that specifies the application instance relative to other instances started by the same executable. An example of this name is Process("Orders", 2).

The name of a window includes the word Window followed by three parameters: window class name, caption and index of the window relative to other windows that have the same class name and caption. For instance, the name of the main window of the Orders application is Window("WindowsForms10.Window.8.app.0.378734a", "Orders - Untitled", 1).

Controls that are located on application forms are also windows and they are addressed in the same way. That is, their name includes three parameters: class name, text (caption) and index.

For detailed information on naming concepts, see Naming Objects in TestComplete help.

Now let’s explore available methods and properties. Select any control of the Orders application in the tree list of the Object Browser and look to the right hand portion of the panel. It displays properties and methods of the selected object:


26


TestComplete automatically recognizes the control and window types and associates the appropriate scripting objects with them. For each window type it provides specific methods and properties that let you simulate user actions over these controls, obtain the controls' data and state. Currently, the windows of the Orders application contain only these TestComplete-defined properties, not those defined in the application source. This may be enough to test the user interface of some Windows applications, since TestComplete supports almost all standard Windows controls: list views, combo boxes, tree views, and so on.

If the tested app is an Open Application, you can dig even deeper. In this case, objects, methods and properties defined in the source code become available to the test engine. Open Applications can be created in any supported compiler. Some applications (for instance, .NET and Java applications) are “Open” by default because they do not require re-compilation. Please read Open Applications for more information.

The Orders application is already compiled as an Open Application. It provides maximum openness, that is, it makes all public, published and protected elements (with some restrictions) accessible to TestComplete. Currently, TestComplete does not have access to internal properties and methods of the Orders application because we have specified the -NotOpenApp command-line argument for the application. Let’s change the command line:

Close the Orders application.


27

Introduction

Double-click the application node in the Project Explorer panel. TestComplete will show the list of the tested applications in the Workspace panel.

Press the ellipsis button within the Parameters column.

In the resulting Parameters dialog, remove -NotOpenApp from the Command-line parameters edit box. Press OK to close the dialog.

Save the changes by selecting File | Save from TestComplete’s main menu (this menu item can be disabled, if you accidentally selected a project item other than TestedApps in the Project Explorer).

Now run the Orders application: right-click the application’s node in the Project Explorer panel and choose Run from the context menu. TestComplete will launch the application and you will be able to explore the application’s objects in the Object Browser:


28


As you can see, the Object Browser now displays a special icon ( ) for the Orders process. The icon indicates that TestComplete recognizes the Orders application as an Open Application.

The Object tree shows a list of internal application’s objects. The image above shows the objects of the Orders application compiled with Microsoft Visual C#. These objects are addressed with the syntax WinFormsObject("Object_Name"). WinFormsObject is the method that is used to address objects in .NET applications that were created with Microsoft’s Windows Forms library. If you compile the Orders application with another compiler, TestComplete will address the objects using another method: VBObject, VCLObject, SwingObject, and so on.

The right portion of the Object Browser displays properties and methods of the object selected in the object tree. The method and property lists include methods and properties defined in the application’s source code as well as methods and properties introduced by TestComplete. You can use these methods and properties in your tests, if the functionality provided by TestComplete is not enough to simulate some action or obtain controls’ data.

Note that some methods and properties remain unavailable to TestComplete even if the application is compiled as an Open Application. There are a number of reasons for this. Typically, this occurs with non-OLE-compatible properties, with methods containing non-OLE-compatible parameters or return values. See


29

Introduction

Object Properties, Fields and Methods That Are Unavailable to TestComplete in TestComplete help for more information.

Also, protected and private properties are hidden from the panel by default. For more information on this, see Access to Properties in TestComplete help.

Some Read/Write properties may be displayed as Read-Only (they are not marked with any glyphs) or Write-Only (marked with the glyph). These properties will be Read-Only or Write-Only in your keyword tests and scripts. Usually, this means that the property value is not read or set in the application’s source code, that is, the application does not call the “get” or “set” function, so the compiler does not include the function in the application’s binary code.

Now, let’s change the caption of the application’s main form. To do this:

Locate the form in the Objects tree.

Switch to the right pane and find the WndCaption property.

Specify the new caption in the WndCaption property and confirm the change by pressing ENTER.


30


The form caption will be changed. You have literally changed Orders’ internal data, and the next screen update reflects the new data.

Note: For Visual C++ applications this procedure cannot be executed from the Object Browser, since Visual C++ applications do not have properties (they use fields and methods). In this case, you can change the form’s title by calling the appropriate Visual C++ method from script code or a keyword test.

After we explore the application and its objects, we can proceed with the test creation.

Planning Tests

General Notes on Planning and Creating Tests

Before you create a new test, you should plan it:

Define the test goal (decide which application functionality to be tested).

The clearer the goal and the simpler the test, the better. Do not create tests that will test various aspects of the application’s behavior at one run. It is better to create a simple test that is aimed at one objective only. Such tests are easier to create and maintain. Once you create several simple tests, you can always organize them into a larger test.

Plan testing steps (decide which actions the test will perform).

The testing steps depend on the test purpose and the nature of the application under test. For instance, testing of a Web server may require simulating an extensive load, which requires the recording and playback of HTTP traffic to that server, while testing of an image editor may need the recording and playback of mouse movements and presses and releases of mouse buttons. TestComplete lets you simulate these and other actions over the applications under test.

Testing steps may include actions that prepare the application for the test (that is, they put the application to some initial state).

Also, testing steps may feed corresponding input to the application.

Check test results (decide how to determine that the test passed successfully or failed).

After the testing actions are finished, the test should check the results against the expected output and decide whether the test was successful or not. Typically, after the application performed some actions, something changed in that application: data in an application window can be rearranged, a new window may be created, a file can be created on or deleted from your hard disk, and so on. You should determine what facts will be used as the fail (or success) criteria.

Logging the result (determine how you will log the test result).

The test results can be logged in different ways, for instance, your test scripts can save the full test results to a file or show an on screen image notifying you that the test run is over.

TestComplete tracks all simulated actions during the test run and saves the information on these actions to the test log. Of course, you can post custom messages, image, files or file links to the log. The messages can be organized into folders and each message may use specific font and background settings to display. The results can be exported to a file, compressed and sent via e-mail to your co-workers. You can even create a bug report in an issue-tracking system directly from test results shown in the log. See Test Log for more information.


31

Introduction

After you have planned your test, you can create it. The basic test sequence includes the following steps:

1. Define expected output.

2. Feed corresponding input.

3. Gather output.

4. Compare to expected output.

5. Call for attention if the comparison fails.

These items can be divided into a sequence of smaller substeps, each of which will perform a smaller task. We call these substeps test items.

A TestComplete project holds one or more project items. Some project items (for instance, Script) or their child elements (script routines) may be used as a source of tests. That is, a project item or its child element may be used as a test item - it can be “executed” as a test or a subtest. Projects themselves can also be used as test items: this happens when you create tests for project suites.

What actually happens when you execute a test item is determined by the properties of that test item. For instance, if a test item executes a keyword test, TestComplete will run this test; if you command TestComplete to execute a project, TestComplete will perform the test item defined by the project’s properties.

To create a test in TestComplete:

Define the test purpose.

Create source elements for test items (for instance, record a keyword test, write or record a script routine, create a manual or unit test, record a low-level procedure, and so on). The test items created depend on your application and the test purpose.

Specify the execution order of test items.

Create test commands that will check and log the test result (if necessary). This item is optional, because some test items (for example, low-level procedures) automatically post messages about their execution to the log. TestComplete provides various ways that let you decide whether the test passed successfully. These include special functions for comparing images, files and collections of object properties, special keyword test operations and script methods and properties that let you check whether a window is visible or hidden, capture the window image, and so on.

Creating a Test for the Orders Application

The sample Orders application maintains a list of orders. Suppose we need to test whether the application generates the customer list correctly. In this case --

Test purpose: The test should check whether the Orders application generates the customer list properly.

Testing steps: To generate the customer list, the user should select the “Report | Generate customer list” item from the main menu of the Orders application. One way to create a test that checks the customer list is to record a keyword test, script routine or a low-level procedure that will simulate the desired user actions. You may even create several keyword tests, scripts or low-


32


level procedures: one of them may call a form with a button on it, another - simulate user actions on the form, and so forth.

When the user presses the button to generate the customer list, the application calls the routine that generates the list. A possible alternative to simulating user actions is to call the application’s routine that generates the list. This requires TestComplete to have access to the internal application’s objects, methods and properties, so that you can call this routine directly from your keyword tests or scripts. In order for TestComplete to have access to application internals, the application under test must be compiled as an Open Application.

Though our sample application is compiled as an Open Application, we will follow the first approach: we will create a keyword test that will simulate user actions.

Checking and logging the test result: If the customer list has been generated successfully, the Orders application creates a file that holds the customer names. To check whether the list was generated successfully, our test can check whether the file exists and then compares the generated file with the base-line copy stored earlier. We will add special keyword test operations that will perform the described checking and post an error message (if necessary) to the test log.

Currently, our sample project does not include keyword tests, script routines, low-level procedures or other project elements that can be used as test items. Also, the test item sequence is not specified. In the next steps we will record a keyword test and then use it as a test item.

Recording a Test

Now we may create a test for the Orders application. We will first briefly describe the recording features of TestComplete and then will record a sample keyword test on the Orders application.

About Recording

With TestComplete you can create tests of different kinds: keyword tests, scripts, low-level procedures and so on. You can create and modify tests manually, but it is much easier to record test actions and then modify (if needed) and execute them. You can record keyword tests, scripts, low-level procedures and HTTP load tasks.

You start recording by selecting either Test | Record | Record Keyword Test or Test | Record | Record Script from TestComplete’s main menu or from the Test Engine toolbar. You can also start recording by clicking Record a New Test on the Start Page (this will start keyword test recording).

After commanding TestComplete to start the recording, it will switch to the recording mode and display the Recording toolbar on screen:

The toolbar contains items that let you perform additional actions during the recording, pause or stop recording and change the type of the recorded test (keyword test, script code, Windows or PDA low-level procedure, or HTTP traffic). The menu item that you used to start the recording defines the main recorded test: keyword test or script code. If you activate another test type during the recording, the main test will contain special commands that will run these tests.


33

Introduction

By default, TestComplete always records a new keyword test or script routine. But you can also record keyword test operations or script statements into the current position of the KeywordTest Editor or the Code Editor. To do this, disable the Always start a new test setting in the Recording Options dialog. To invoke the dialog, choose Tools | Options from TestComplete’s main menu and then select Engines | Recording in the ensuing Options dialog. The Recording options will be shown on the right of the Options dialog. When the Always start a new test setting is disabled, keyword test operations and script statements are recorded into the current position in your keyword test or script code.

To avoid making the test too dependent on the precise screen layout, and to keep it readable and reasonably short, TestComplete, by default, only records keyboard and mouse events that affect Windows controls. TestComplete does not, for instance, record the precise path of the mouse between clicks in different places, or the time elapsed between each keystroke. However, full-detail recording can be achieved by using low-level procedures.

Requirement: if you use a computer that has several processors or a multiple-core processor (for example, dual-core CPU) and has Windows XP Service Pack 2, then you must install the Windows update #896256 in order for TestComplete to be able to record user actions correctly. The update is available on Microsoft’s web site:

http://support.microsoft.com/kb/896256

Without this update, TestComplete will record user actions incorrectly. For instance, it may have an invalid order of keypresses or record double-clicks instead of the drag or click events.

For more information on test recording, see the Recording in TestComplete section in TestComplete help.

Recording Test for the Orders Application

Let’s now record a keyword test for the sample Orders application according to the plan that we created in the previous step of this tutorial. The test will launch the application, load data in it and simulate some clicks and keystrokes within the application’s window. Below are detailed instructions.

Before you start recording, please install Windows update #896256, if you have a multi-processor computer or a multi-core CPU and you are using Windows XP Service Pack 2 .

Do not switch to the TestComplete help during the recording. The recording engine traces and records all user actions, so the recorded test will contain commands that simulate “switching”.

To see the instructions, you can print them before starting the record. Or, if you have two monitors, you can move the TestComplete help system window to the other monitor.

Let’s start recording:

Select Test | Record | Record Keyword Test from the main menu of TestComplete.

TestComplete will display the Recording toolbar on screen. If the Interactive Help panel is visible, TestComplete will also show information about the recording process in it.

Press the down arrow of the Run Tested Applications button and select Orders from the drop-down list:


34

http://support.microsoft.com/kb/896256


When you launch tested applications this way, TestComplete automatically inserts the application launch command into the recorded test.

Wait until the application starts and the application’s main window is shown:

If the Interactive Help panel is visible, resize or move it so that it does not overlap the application’s window. Your actions on this panel are not recorded.

Switch to the Orders application and select File | Open from its main menu. This will bring up the standard Open File dialog.

In the dialog, open the MyTable.tbl file. The location of this file depends on the operating system you use. On Windows Vista and Windows Server 2008 it resides in the C:\Users\Public\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo folder. On other operating systems, it is located in the C:\Documents and Settings\All Users\Documents\TestComplete 7 Samples\Open Apps\OrdersDemo folder.

It is recommended to type the fully-qualified file name into the File name box of the Open File dialog. Typing instead of using the mouse will help you avoid problems if the Open File dialog displays a different initial folder when the script is played back later.


35

Introduction

After specifying the file in the File name box, press Open. The Orders application will load data from the file and display this data in the application’s main window.

Click the Samuel Clemens row in the list of orders.

Move the mouse cursor to the Orders toolbar and press Edit order. This will call the Edit Order dialog.


36


In the dialog, select FamilyAlbum from the Product drop-down list.

Click within the Customer Name text box to move the input focus there. Right-click within the Customer Name box and choose Select All from the context menu and then enter Mark Twain as the customer name.

Note: You could also choose the text in a text box by dragging the mouse, but in this case the test would become less universal, because if the text length varies, the test will have to drag for a longer or shorter distance, that is, you will have to calculate the dragging distance in your test. Using the Select All menu item shortcut frees you from this problem and makes the test more stable. A possible alternative to using this menu item is to use the CTRL+A or any other shortcut (or a series of shortcuts) to choose the entire context of the text box.

We used the menu item rather than dragging just to demonstrate the “change-proof” approach. In this tutorial, you may select the text in text boxes by dragging the mouse. The test recorder is smart enough to detect that you are working with a text box and that its contents has changed, so it will record the drag command and then the command that changes the entire text of the box. However, the recorder may be unable to determine this for some third-party controls or in-place editors, so in general we recommend that you select text in the controls with the Select All menu item, the Ctrl+A shortcut, or in any other “change-proof” way.


37

Introduction

Click within the Card No text box, select text in it by dragging the mouse and then enter 123123123123 as a card number.

Click OK to close the dialog.

Now you can export the customer list to a file. To do this:

Select Report | Generate customer list from the main menu of the Orders application. Orders will display the Save File dialog.

Enter C:\CustomerList.txt into the File name edit box of the Save File dialog.


The application will save the customer list into the specified file.

Close the Orders window by clicking the X button on the window’s caption bar. This will display the dialog asking if you want to save changes. Press No. Orders will close.

Press Stop on the Recording toolbar to stop the recording.

In the next step we will analyze the recorded test.

Analyzing the Recorded Test

After the recording is over, TestComplete opens the recorded keyword test for editing and displays the test’s contents in the KeywordTest Editor:


38


The recorded test is similar to the test shown in the image above. Your actual test may differ from this one. For example, it may have other object names or window indexes if you have recorded the test on a Visual C++ or Delphi application.

The test consists of operations that simulate actions during the recording. Let’s explore the recorded operations.

The first operation in the test is Run TestedApp. It is used to launch the tested application (in our case, it is the Orders application) from a keyword test. TestComplete records this operation automatically when it detects that a user launches the application from TestComplete’s UI or somewhere from the operating system’s UI.

To view the operation parameters:

Choose the Value cell of the Run TestedApp operation’s row.

Click within this cell or press F2. This will activate the in-place editor.

Press the ellipsis button within the cell. This will invoke the Operation Parameters dialog:


39

Introduction

As you can see, the operation parameters specify the number of application instances to be launched and the time period for the launch. To specify the command line and the executable’s name and path, set the application properties in the TestedApps editor.

The other operations in the test correspond to the actions that you performed during recording. TestComplete automatically organizes the operations into groups that correspond to the processes and windows with which you worked. Grouping makes the test structure easier to understand and also provides some information on the object hierarchy that exists in the application under test.

We recorded user actions on one process (Orders). So, we have only one “process” group node. It contains all of the actions that you simulated on the process windows and controls. The actions that we performed on windows and controls of the Orders process, are organized into a number of “window” grouping nodes:

You may notice that the names of the tested process and its windows and controls differ from the names that we saw in the Object Browser panel in one of the previous steps. For instance, in the Object Browser the tested process was named Process("Orders") while in the test it is called Orders; the main window was called WinFormsObject("MainForm") while in the test it is called MainForm, and so on.

This happened because the Map object names automatically setting was enabled during the test recording. You can view or change this option in the Name Mapping Options dialog. To invoke it, choose Tools | Options from TestComplete’s main menu and then select Engines | Name Mapping from the tree on the left of the ensuing Options dialog.

When this setting is enabled, TestComplete automatically generates and uses custom names for the objects that you worked with during test recording. Generating and assigning custom names is called name mapping. TestComplete maps the names because the default names may be difficult to understand. It may be hard to determine to which window or control corresponds to which name. So, TestComplete replaces the object names with more human-friendly and easy-to-use variants that reflect the object type and contents. Look at the recorded test: MainForm looks better than WinFormsObject("MainForm") and dlgOpen (the Open File dialog) is more understandable than Window("#32770", "Open", 1).


40


After the object’s name has been mapped, TestComplete uses the mapped name to refer to this object in its tests and dialogs. To view the tree of mapped objects and explore and change the mapping settings, double-click the NameMapping item in the Project Explorer panel. This will open the NameMapping Editor, where you can view and modify the settings. For more information on mapping object names, see Name Mapping in TestComplete help.

Let’s return back to the recorded test. As we said above, the window grouping nodes contain operations which you performed on the window, to which the node corresponds. The first grouping node contains the Menu Action operation that simulates selection of the “File | Open” item from the tested application’s main menu:

The name of the desired item is passed as a parameter to the Click method (File|Open). Note that you can address menu items by either their captions (as it is in our case), or by indexes. The item captions can be used if the menu item has no picture and the application displays the item in the standard way. Indexes let you work with menu items that cannot be addressed by their captions. Of course, item captions make the test more readable, but indexes are more universal and work for almost all item types. If you are not sure how to address menu items, we recommend that you use indexes. See also Simulating Menu Actions in TestComplete help.

Selection of the “File | Open” menu item invokes the standard Open File dialog. The next grouping node contains operations that simulate your actions in the Open File dialog:

Despite the fact that these operations have different icons, each of them is the On-Screen Action operation. These operations are used more often than others to simulate user actions on windows and controls.

The On-Screen Action operation simulates user actions by calling a method of the tested object. The first operation in the group simulates keystrokes on the “File name” text box of the Open File dialog. The operation does this by calling the Keys method of the object that corresponds to this text box. It is the standard way to simulate keystrokes from tests. TestComplete provides this method for any object that can accept user input. The text to be “typed” is passed to this method as a parameter.


41

Introduction

To determine that a window supports keyboard input, TestComplete compares the window’s class name with the class name given to windows of this type by default. If the check is successful, TestComplete treats the control as a text box, combo box, button or any other object of the appropriate type. If the window’s class name differs from the default name, TestComplete uses Object Mapping project settings to determine the window type. Once TestComplete determines the window type, it adds methods and properties specific to windows of that type to the window object. By using the Object Mapping settings you can “tell” the test engine which object type of the control corresponds to the object in your tested application. See Object Mapping in TestComplete help.

The second operation in the group simulates a mouse click on the “Open” button of the Open File dialog. It does this by calling the ClickButton method of the object that corresponds to the button. The test engine automatically adds this method to all controls that are recognized as command buttons.

For more information on simulating keyboard input, mouse events and other actions, see Simulating User Actions in TestComplete help.

The click on the Open button of the Open File dialog closes the dialog and returns us back to the main window of the Orders application. The next two operations simulate actions in the main window:

These two operations are On-Screen Action operations. The first of them simulates the selection of the Samuel Clemens row in the orders list. To do this, the operation calls the ClickItem method which the test engine adds to those objects that it recognizes as list view controls.

The other operation simulates a click on the toolbar item that opens the Edit Order dialog. To do this, the operation calls the ClickItem method of the object that corresponds to the toolbar. Toolbar items can be specified by their caption, id or position on the toolbar (see the description of the ClickItem method in help). In our test, the operation uses the item’s id (5) as this makes the test more resistant to changes that may be made to the application (for instance, if a developer changes the button’s position on the toolbar, the test will still be operational).

Note that we do not use any special command to activate the window to which the test will “send” the click. TestComplete does this automatically.

After we click the Edit Order toolbar item, the Orders application invokes the Orders dialog. The next grouping node contains operations that simulate user actions on controls of this dialog:


42


The first operation of this group simulates selection of the FamilyAlbum item from the “Product” combo box. This is the On-Screen Action operation that uses the ClickItem method of the combo box object.

The several next operations simulate mouse clicks on the “Customer Name” text box of the dialog, choosing the “Select All” item from its context menu and the replace the test box contents with Mark Twain. Note that before choosing “Select All” from the context menu, the test first simulates a click of the right mouse button on the control. This is very important, because without this click the context menu will be hidden and the Menu Action operation that simulates the selection of the “Select All” item will fail:

To simulate the change of the text in the “Customer Name” box, TestComplete uses the On-Screen Action operation that assigns a value to the wText property. TestComplete appends this property to all the objects that correspond to text box controls. The property can both obtain and set the text of a control. In our example, it is used to assign the text.

The next two operations select the text in the “Card No” box and replaces it with a new value. As you remember, we selected text in this box by dragging the mouse, so TestComplete recorded the On-Screen Action operation that calls the Drag method. Then it recorded another On-Screen Action operation that uses the wText property to change the text in the box:


43

Introduction

Note that with the wText property you can change text of the control regardless of whether this text is selected or not. You can obtain or set the text even if the control does not have the input focus. So, in most cases, if you created the test manually, then to change the text in a control you would not have to select the text in it. As for TestComplete, it records the selection actions because in general these actions may affect the application under test. For instance, there can be event handlers that process user actions performed on the control and change the contents or state of other controls. These changes may be critical, so TestComplete recorded them in order for the recorded test to be able to execute successfully.

The next operations in the test simulate the selection of the “Report | Generate customer list” item from the main menu of the Orders application and specifying the file name in the Save File dialog:

To perform these actions TestComplete uses the keyword test operations that were described above.

The next operation sends the “Close” command to the main window of the Orders application and thus, closes the application:

As you remember, the application displayed a message box asking whether you want to save the changes made to the orders list. The last operation of the test simulates the “No” button press in this message box.

In the next step we will describe the manual creation of a keyword test.

Creating Checkpoint

The goal of our test is to check whether the Orders application generates the customer list correctly. To perform this verification, we need to compare the exported file with its baseline copy. In this topic, we will describe how you can do this.


44


On the previous step of the tutorial we recorded a test simulating user actions that export a list to a file. We will use this file as a baseline copy for comparison.

TestComplete projects have the Stores project item that serves as a storage for the files, images, XML documents and other elements that are kept with the project for comparison purposes. Let’s add the file to the Stores of our TestComplete project:

Switch to TestComplete’s Project Explorer panel.

Expand the Advanced node (by default, the Stores item is located in this folder in the Project Explorer).

Right-click the Advanced | Stores | Files node in the Project Explorer and select Add | New Item from the context menu:

TestComplete will show the standard Open File dialog, where you can select the file to be added to the project.

In the dialog, select the file C:\CustomerList.txt and click Open. TestComplete will display the message box asking you whether it should copy the file to the Stores folder of your project. Answer Yes. TestComplete will copy the file to the Stores folder and then add the copy to the Files collection of the Stores project item. The added file will be displayed under the Stores | Files node in the Project Explorer:


45

Introduction

Select File | Save from TestComplete’s main menu to save the changes.

Now we can create test that will compare the files. In TestComplete you can do this in several ways: by using the Files.Compare method, regular expressions or special keyword test operations (see File Checkpoints topic in TestComplete help). In this tutorial, we will create a simple keyword test that will use the File Checkpoint operation to compare two files:

Right-click the KeywordTests node in the Project Explorer panel and select Add | New Item from the context menu. This will invoke the Create Project Item dialog.


46


Here, you can specify the test name and location of the test’s file. Leave all values as they are and click OK. TestComplete will create a new keyword test named Test2 and will open it for editing.

Now we can add operations to the test. To compare files from your keyword test, use the File Checkpoint operation. To add this operation to your test:

Expand the Checkpoints operation category in the Operations panel of the KeywordTest Editor.

Click the File Checkpoint operation in the Operations list and then click somewhere within the Test Steps page to add the operation to the test. Alternatively, you can drag the operation from the Operations panel to the test.

TestComplete will display the dialog in which you can specify the operation’s parameters.

In the dialog:

Type C:\CustomerList.txt into the File 1 edit box, or click the ellipsis button and choose the file in the ensuing Open File dialog. This is one of the files to be compared.

Switch to the File 2 box and select CustomerList.txt from its drop-down list. This is the other file to be compared.

Make sure the Report difference check box is selected. If it is selected, then the operation will post an error message to the log if the compared files differ.


47

Introduction

Click OK. TestComplete will close the dialog and add the operation with the specified parameters to the keyword test.

According to the settings we made, the File Checkpoint operation will post a message to the test log if the compared files differ. Let’s now add operations that will report that the comparison passed successfully:

Choose the Statement category in the Operations panel.

Click the If... Then operation in this panel and then click below the File Checkpoint row within the Test Steps page to add the If... Then operation to the test.

TestComplete will display the Operation Parameters dialog:


48


Each row in this dialog corresponds to an individual comparison expression that will be checked by the operation. The entire comparison criterion may include several expressions.

Click the ellipsis button of the Value 1 cell. This will invoke the Edit Value dialog in which you can specify the value that will be used for comparison.

In the dialog:

Choose Last Operation Result in the Mode box. This indicates that one of the values to be compared by the If.. Then operation should be the result of the previous operation (in our case, the results of the File Checkpoint operation).

Click OK to close the dialog and apply the changes.

Now we are back to the dialog that displays parameters of the If... Then operation.

Click the ellipsis button of the Value 2 cell. This will invoke the Edit Value dialog in which you can specify the other value for comparison.

In the dialog:

Choose Constant from the drop-down list of the Mode box.

Select Boolean in the Type drop-down list.

Specify True in the Value box.


49

Introduction

Click OK to save the changes.

Now you are back to the dialog of the If...Then operation parameters. Make sure the Condition column contains the equal to value. Click OK to close the dialog and append the operation to the test.

Now let’s append the Log Message operation to our test. This operation will post a message about successful comparison to the test log. To add the operation:

Expand the Logging category in the Operations panel.

Click the Log Message operation in the Operations panel and add this operation to the test as a child of the If... Then operation. To do this, move the mouse to the right along the If... Then row. While moving the mouse cursor will indicate the position to which the operation will be inserted. Click the left mouse button when the mouse pointer will be as it is shown on the following figure:

Alternatively, you can add the Log Message operation to the end of the test and then change its position using the arrow items on the editor’s toolbar.


50


After you added the Log Message operation, TestComplete will display the dialog, in which you can specify the operation’s parameters. Type The files are identical. into the Message box:

Click Finish to close the dialog.

Now our test is ready and looks as follows:

Select File | Save from TestComplete’s main menu to save the changes.

One last thing we should do is to remove the C:\CustomerList.txt file from the system. To do this, open Windows Explorer or any other file manager and delete the file. If you leave the file, then during the test run you will get a message box asking you whether to replace the existing file or not. This message box is an unexpected window for TestComplete since it did not exist during the script recording. TestComplete is able to handle unexpected windows appropriately (see Handling Unexpected Windows topic in TestComplete help).


51

Introduction

TestComplete will handle the message box by clicking its default button. However, it will post an error message about the window in the test log. So, the log will report that an error occurred during testing (despite the fact that this error is not significant and TestComplete is able to handle it). Deleting the file solves the problem with the error message.

In the next step we will include the Test2 test into the testing tasks of the project.

Organizing Tests

A test may consists of several subtests, each of which performs a smaller testing task. We say that the test consists of test items. Each test item is associated with a keyword test, script routine, low-level procedure, manual test, unit test or another project element that can be executed as a test.

You create the desired test items on the Test Items page of the project editor. Here you can also specify their execution flow and modify their properties. To open this page, right-click the project in the Project Explorer panel and choose Edit | Test Items from the context menu, or select your project in the Project Explorer and click on the Project Explorer’s toolbar. TestComplete will open the project editor in the Workspace panel and activate the editor’s Test Items page. The page shows a tree-like structure of existing test items and lets you modify this structure as needed. The following image displays a sample Test Items page:

Note that the project suite editor also contains the Test Items page. It lets you specify the execution order of projects, which belong to this suite. The difference between these pages is obvious: when you command TestComplete to execute a project, TestComplete will run tests defined with the Test Items page of the project editor. When you command TestComplete to execute a project suite, it will execute projects in the order specified on the Test Items page of the project suite editor.

By default, new projects do not have any test items. Let’s create them:

Select the Orders project node in the Project Explorer panel.


52


Click on the Project Explorer’s toolbar. TestComplete will show the project editor in the Workspace panel and switch to the Test Items page.

Select New Test Item from the page’s toolbar. A new test item will be added to the project.

Click the ellipsis button of the Test cell. This will invoke the Select Test dialog that lists the tests that exist in the project.

In the dialog, choose KeywordTests in the Test Categories list and then select Test1 in the Available Tests box:


TestComplete will display Test1 in the Test column.

Now you can create a test item for the second test. We will do this differently than using the dialog, which is a lot faster. The Test Items page supports dragging, so you can create test item by dragging tests from the Project Explorer panel to the page (script routines can be dragged from the Code Explorer).

To add a test item for the second test:

Switch to the Project Explorer panel.

Drag the KeywordTests | Test2 node from the Project Explorer to the Test Items page of the project editor.


53

Introduction

Now our project contains two test items:

After creating a test item, you can modify its properties in columns of the Test Items page. For instance, you can change the Count property to specify the number of times the test item will be executed, or modify the Timeout property to set the maximum time period for an item’s execution. If the test item’s execution time exceeds the specified timeout, TestComplete terminates the test item run and considers that the item failed to execute successfully. If a test has parameters, you can specify them in the Parameters column. You can also change the position of a test item by dragging it within the Test Items page or using the Move Up, Move Down, Indent and Outdent toolbar items. You can organize test items in groups and perform other actions. For more information about these features, see description of the Test Items page in TestComplete help.

In our example, we will not modify the item’s properties.

Note: Make sure that the test item is enabled, that is, the check box on the left of the test item is selected. TestComplete executes a test item only if it is enabled.

We only created two test items. They will perform all the actions that we planned: launch the tested application, simulate user actions on the application’s windows and controls, save the list of customers to a file and compare this file with a baseline copy. This is enough for our sample project. In real-life projects, you will typically perform more tasks and create more than two test items. You can create as many test items as needed.

In the next step we will run our tests.

Running Test

Now we may run our simple test to see how TestComplete simulates user actions. Some notes before we do this:

The created tests are not compiled into an executable for test runs. You run the tests directly from TestComplete. To run tests on computers that do not have TestComplete installed, you can use a resource-friendly utility called TestExecute. You can also export script code (if you use it) to an external application and run it there. For more information on this, see Connected and Self-Testing Applications in TestComplete help.

TestComplete can use different kinds of tests (keyword tests, script routines, low-level procedures and so forth) and some of these tests can be recorded. Before running the recorded tests, make sure they start with the same initial conditions as the recording did. For instance, the tests almost always require the tested application to be running. So, before


54


simulating the user actions, you should launch the application. To guarantee that the application is loaded, in our case we use the Run TestedApp operation at the beginning of the test. Alternatively, you can run the tested application manually. To do this, right-click the application’s node in the Project Explorer panel and choose Run from the context menu.

If you launch an application under Windows Vista or Windows Server 2008 with administrator privileges, the operating system will display a dialog box asking for your permission for the run. Due to certain limitations, the closing of this dialog box cannot be automated (when this dialog box is visible, the script run is paused). You should either close the dialog manually, or modify the User Account Control settings so that Windows does not display the dialog. See Testing Applications With TestComplete Under Windows Vista and Windows Server 2008 in TestComplete help.

Make sure the desired test items are selected on the Test Items page of the project editor. When you run a project, TestComplete runs only those test items that are selected on this page.

To run your test, select Test | Run Project from TestComplete’s main menu, or choose Run Project from the toolbar, or select the project in the Project Explorer panel and then click Run Project on the Project Explorer’s toolbar. One more variant is to press the Run shortcut (it is defined in the Global Shortcuts dialog)

After commanding TestComplete to run the project, it will start running the project’s test items. You can stop the execution at any time by pressing Stop on the Test Engine toolbar or select Test | Stop from TestComplete’s main menu.

You can pause the test execution by clicking Pause on the Debug toolbar (if the toolbar is hidden, right-click somewhere within the toolbar area and choose Debug from the ensuing context menu). You can also pause the test execution by pressing the Pause shortcut (it is defined in the Global Shortcuts dialog).

When paused you can perform any actions needed. For instance, you can close certain applications or explore the script variables and objects using TestComplete’s Watch List or Locals panel or the Evaluate dialog (see Debugging Tests in TestComplete help). Also, if the Show Log on pause option is enabled, TestComplete displays the Pause Log window when you pause the test run. In this window you can review test results saved to the log when paused. The window is closed after you resume the test execution. To view or change the Show Log on pause option, choose Tools | Options from TestComplete’s main menu and select the Engines | Log setting group on the left part of the ensuing Options dialog. TestComplete will display the log settings on the right of the Options dialog.

For complete information on running tests in TestComplete, on project settings that affect the runs and on the test execution peculiarities, see Running Tests in TestComplete help.

After the test execution is over, you can view test results using TestComplete’s test log. The next topic provides a brief overview of the log capabilities.

Analyzing Test Results

TestComplete keeps a complete log of all operations performed during testing. You can add your own notes, references or images to the log as well.

By default, TestComplete stores the log files in subfolders of the <Project>\Log folder (each subfolder includes all log files of a test run). You can specify another folder for the log files using the Log location project property (this option resides in the General group on the Properties page of the project editor).


55

Introduction

The titles of test results are shown in the Project Explorer panel under the Project_Suite_Name Log | Project_Name Log node, for example, in our case it is the node ProjectSuite1 Log | Orders Log. It is the primary workspace for looking up the test history of the project and project suite. Each node corresponds to a test run. An image to the left of the node specifies whether the corresponding test run passed successfully:

Note that TestComplete automatically adds nodes for the last results after the test execution is over. That is, the results are not displayed when the test is running. You have to wait until the test run is over. However, you can view intermediate results if you pause the test execution. TestComplete includes a special Show Log on pause option. You can find it in the same Log Options dialog (to invoke it, choose Tools | Options from TestComplete’s main menu and then select Engines | Log group from the tree on the left of the ensuing Options dialog). If the Show Log on pause option is enabled, then during the pause TestComplete displays the Pause Log window in the Workspace panel. The window is closed once you resume the test execution. The pause log is not added to the test log tree displayed in the Project Explorer.

Since we have run only one test so far, we have only one log node in the Project Explorer. By default, TestComplete automatically opens its contents in the Workspace panel. You can also view the log at any time later. To do this, right-click the desired result in the Project Explorer panel and choose Open from the context menu.

In our example, the log is as follows --


56


The log window shows results of one test run. On the left of the window there is a tree-like structure of the tests that was executed during the run. The topmost item corresponds to the test that you run. In our case, it is the log of the Orders project, since we run the project. The project log contains logs of the project’ test item. These logs also contain logs of the test that is specified in the test item’s “Test” property.

The project logs contain two pages: Summary and Project Log. The Summary page provides a brief overview of the test results. It reports how many test items were executed, how many of them completed successfully and how many failed:


57

Introduction

The Project Log page contains links to the test items’ logs as well as messages that were posted to the log during the project run. In our case, the page only contains links to the test items’ logs:


58


These log nodes are also displayed as child nodes in the Log Items tree of the test log window (see the image above).

To view a child log, simply select it from the tree, or click the Details link in the Project Log page of the project’s test log. Let’s open the log of the Test1 item. This log looks as follows:


59

Introduction

Note that every test type has its own results presentation, so what the log window displays is determined by what test was executed. The image above shows the log that contains informative, error, warning and picture messages. This log is used by most tests created in TestComplete. For instance, it is used by the keyword tests, scripts and manual tests. Some other tests may form a log having another structure, that is, their logs differ from this generic log. For instance, the HTTP load tests form a log that contain tables with information about simulated virtual users, connections, simulated requests and their responses and so on. For detailed information about these logs, see the description of the appropriate project item, or simply click within the log page and press F1.

The generic log, as we said, contains error, warning, informative and other types of messages. You can hide the messages you do not need and view only specific types of messages. To do this, select or clear the check boxes that are shown above the list of records. For instance, clear the Message check box. TestComplete will hide informative messages from the log and display the “Filtered” mark on the left of the list to indicate that the log contents are filtered. In our case, clearing the check box will hide the first message from the log (this is the informative message):


60


You can also filter results and view only those messages that contains specific text. To do this, type the desired text into the Search text box that is shown on the top right of the message list. For instance, type drag. TestComplete will hide all messages that do not contain this word in them. Now our log has only one row. It provides information about the drag action that we performed on the Card No box of our tested application:

Select this row. The Remarks panel will display additional information about the action (it shows additional information for the selected message):


61

Introduction

If the selected message has an image associated with it (you can post images along with text messages to the log), then this image will be shown in the Picture panel.

You can rearrange the log panels as your needs dictate. For instance, you can resize the Remarks or Picture panes, sort the contents on the Time column, filter results by their type, and do a lot more. For more information, see Arranging Columns, Lines and Panels in TestComplete help.

To view a keyword test operation that posted a message to the log, double-click the desired message in the log. TestComplete will open the keyword test for editing and highlight the appropriate operation. For instance, if you double-click the “The drag operation was performed...” row in the log, TestComplete will highlight the operation that calls the Keys method:


62


For detailed information on the test log panels, on posting messages to the log and on working with the results, see topics of the Test Log section in TestComplete.

Searching for the Reason of an Error

It is possible that the first versions of your tests will fail to execute successfully. There can be a lot of reasons for this. For instance, some objects may be unavailable during the test run, the application behavior can differ from what you expected, an unexpected window may appear, script code (if you use script routines) may contain an invalid instruction and so on. You can search for the cause of an error by performing the following steps:

Look at the first error in the test log (to view the keyword test operation or script function that posted this error to the log, double-click the message in the log window).

Explore the sequence of the test execution that led to the error. To do this, select the error in the log and then switch to the test log’s Call Stack panel. This may help you better understand what happened during the run.

Run your test once again to analyze the application state when an error occurs. To perform this analysis you can --

Set breakpoints or pause the test execution and use the Watch List or Locals panel and the Evaluate dialog to explore tested objects, test parameters, variables and other values (see Debugging Tests in TestComplete help).

Add keyword test operations or script statements that will post different diagnostic messages to the log, for example:

o The list of child objects (windows).

o Images of one or several application windows.


63

Introduction

o The state of objects (windows): existence, visibility, and so on. For instance, to see if an object or window exists, use the Exists property; to see if a window or an onscreen object is visible, you can use the Visible and VisibleOnScreen properties; to see if an object (window) is enabled or focused, use the Enabled and Focused properties.

The goal of the analysis is to answer the following questions:

What is the difference between the current application state and the state you expect?

What is the cause of the error: an error or typo in script code, an application bug or something else?

If you cannot determine the cause of an error, send a message to AutomatedQA’s support team (see Technical Support and Resources). In order for the support team to answer the message in a timely manner, please attach your test project and archived results folder of your TestComplete project to the message (the project results folder is normally <Your_Project_Folder>\Log directory). Please modify the test so that it gives detailed information on your application state at the moment of an error: images of application windows, the list of child objects of the tested process, and so on. A small sample application that illustrates the problem will be greatly appreciated.

You can also ask about the problem in our newsgroup or search for a solution in the list of frequently asked questions. For more information on this, see Technical Support and Resources.


64


Naming Objects

TestComplete gives names to each process, window and control existing in the system. This name is used to address the object in tests, logs and TestComplete’s UI. The object name depends on the object type, values of object properties, and on application type. You can also create and use custom names for objects.

By default, to form an object’s name, TestComplete uses values of object’s properties. Each object has a number of properties such as “class name”, “text”, “enabled” and so on. You can view available properties, for example, in the Object Browser panel.

Some object properties are often changed during the application’s execution (for instance, text in an edit box), while others (for instance, window handle) remain constant but may change between two application runs. Other properties (for instance, window class name in some applications) do not change between application runs.

In order for a property to be used in addressing an object, it must uniquely distinguish the desired object from other similar objects and remain unchanged during the application’s execution and between application runs. Also, it is desirable for the property to be readable. In general, no property meets all of these requirements, so TestComplete uses a combination of properties to identify objects. For instance, to address processes it uses the name of the executable file that started the process and the process index; to address windows it uses the window’s class name, window’s caption and index. In other words, the object names typically include several components:

For complete information on the default naming rules for processes, windows and other objects, see the following topics below:

Naming Processes

Naming Windows

Naming Controls and Objects

Naming Web Objects

Note that some components of an object’s name (for instance, window caption or process index) can change during the application run, so it is possible that you will have to use different names to address the same process or window during the test run. Another problem with default names is that they are hard to understand (it maybe difficult to find the object that corresponds to the name on screen).

An object’s name depends on whether an application, to which the object belongs, is an Open Application or not. The names of Open Applications’ objects contain the name defined for the form or control has in the application’s source code. Typically, this value does not change during the run and between test sessions, so using it is more desirable for addressing the object. However, these names still can be difficult to understand.


65

Introduction

In TestComplete you can assign custom names to any object existing in the system. You do this by using the Name Mapping project item. It stores the custom names defined for the objects. Using these names make tests easier to understand, so it is a lot easier to create and analyze them. When mapping the object name, you define the combination of properties TestComplete uses to address objects, that is, you can make the names more stable to changes in the application relative to default names. The Name Mapping engine lets you also create several aliases for the objects, that is, you can create several custom “names” for it. For more information on creating custom names, see Name Mapping in TestComplete help.

The default name, which TestComplete uses to address an object, are returned by the object’s Name property. You can see this property in the Object Browser panel (in the Properties page and in the Objects Tree). The mapped names are specified by the MappedName property.

There is a certain hierarchy used when addressing them. For instance, to obtain a program object corresponding to a window, you should first obtain a process object; to get program access to a control, you should first obtain a window object that corresponds to the window containing the desired control, and so on. The Name property specifies the object name that is unique relative to other sibling objects that belong to the same parent. The FullName property specifies the object’s full name, which includes the names of parent objects. In fact, FullName returns a string that identifies the object in the system. The MappedName value already includes the parent objects’ names.

The name which TestComplete uses during recording depends on whether the object is mapped or not. If the object is mapped, TestComplete uses an alias defined for the object. If the alias is not defined, the test recorder uses the mapped name. If the object is not mapped, the test recorder uses the name that is specified by the Name property.

If the Map object names automatically setting is enabled in the Name Mapping Options dialog, TestComplete automatically maps the object names during test recording. By default this setting is enabled, so the recorded test contains aliases even if the tested objects were not mapped before the recording starts. For more information on automatic name mapping and recording object names, see Name Mapping - Overview and Recording in TestComplete – Overview in TestComplete help.

Naming ProcessesTo provide access to processes, TestComplete uses the Process objects. The processes are identified by two parameters:

The name of an executable file that starts the process. The file name is used without an extension.

The index of a process instance. There can be several running applications with the same name in the system. In this case, the process index is used to distinguish one process instance from another. The first started process has index 1, the second - 2, and so on.

Note: The index is an optional parameter for process recognition. If you omit the index when referring to the process, the default value 1 will be used, for example, the names


66


Process("Notepad") and Process("Notepad", 1) are equivalent.

The name of the process object depends on the scripting language that is used in your project. For instance, if you use VBScript or JScript, you enclose the executable name in quotes: Process("MyApp"). In DelphiScript, you should use apostrophes instead of quotes, for instance, Process('MyApp'). In C++Script and C#Script the word Process should look like ["Process"]. The following sample demonstrates how you can obtain a process in your script code:

[VBScript, Visual Basic]

' Obtains the object that provides scripting interface' to the second instance of NotepadSet p = Sys.Process("Notepad", 2)

[JScript]

// Obtains the object that provides scripting interface// to the second instance of Notepadvar p = Sys.Process("Notepad", 2);

[DelphiScript, Delphi]

var p : OleVariant;begin // Obtains the object that provides scripting interface // to the second instance of Notepad p := Sys.Process('Notepad', 2);end;

[C++Script, C#Script, C++, C#]

var p;// Obtains the object that provides scripting interface// to the second instance of Notepadp = Sys["Process"]("Notepad", 2);

Note that the process index can change during the test run: if a process with a lower index is terminated, the higher indexes will be decreased, so the names of other processes are changed.

You can map the process name and address the process via the NameMapping or Aliases objects. See Name Mapping in help for more information about this.

Naming WindowsThe way in which TestComplete addresses windows in keyword tests and script code depends on whether the window is mapped or not. If the window is mapped, then TestComplete uses its mapped name or alias. Else, it uses the default window names.

If the Map object names automatically setting is enabled in the Name Mapping Options dialog, TestComplete automatically map window names during test recording or at design time, when you add operations to keyword tests or when you create checkpoints. After the object name is mapped, TestComplete uses the mapped name to address this object. The default name can also be used, though.


67

Introduction

For more information on mapping object names, see Name Mapping in TestComplete help. The rest of this topic will describe the principles which TestComplete uses to recognize windows and to form “default” names.

The window name depends on whether the application under test is an Open Application (white-box) or non-Open Application (ordinary, black-box).

Open Applications

If the tested application is an Open Application, you can address its windows and objects using special methods provided by TestComplete: WinFormsObject, VBObject, VCLObject, SwingObject, and so on. These methods let you address the desired window by using the value specified by the application’s Name property, or by using the class name, caption and index. The method used depends on the programming language and the development tools used to create your application. For complete information on using these methods, see the following topic in TestComplete help:

Addressing Windows, Controls and Objects of Open Applications

Black-Box Applications

To address windows in black-box applications, TestComplete by default uses the following window attributes:

Window class name

Window caption

Window index

The Windows API offers several attributes meant to distinguish one window from the other, among those currently open in the system. The one it uses internally, the handle, is changed from one application to the next and, therefore, is useless. The attributes used by TestComplete - class name, caption and index - are more stable. Though each of them may change during the application run or between the sessions, their combination serves as a rather stable identifier that is suitable for any window existing in the system. The use of other properties, for example, control id (if your application supports them), is also possible. See below for more information.

Now we will describe the attributes used by default.

Window class name. This attribute specifies the name of the window’s class as it is registered in the operating system, for instance, msctrl_statusbar32, #32770, TForm1 or Afx:400000:b:10008:6:1027b.

Window class name is the most stable component of a window name. It does not change during the script run. However, it is not unique for a window (it is quite possible that two or more windows have the same name) and it can change from one application run to another (these changes are typical for MFC applications). To negate the change of the class name, you can replace the varying parts of the class name with wildcard symbols (“*” and “?”). For instance, you can use “Afx:400000:b:*” instead of “Afx:400000:b:10008:6:1027b”. Without the wildcards, you would have to modify window class names in script code before each run. To specify an asterisk as part of the window class name, use two consequent asterisks.

Window caption. The window caption identifies the window for users. It is not unique and there can be two windows with the same caption in the system. Generally, the caption can also be changed during the execution of the application. The developer may use it to display any helpful


68


information, for instance, the caption of a text editor usually displays the name of the edited document: “MyEditor - Document1.rtf”.

You can use wildcard symbols (“*” and “?”) to specify caption patterns. This technique makes application testing more flexible. For example, you can specify only the constant part of the caption (“MyEditor - ”), and replace the name of the edited document with “*”. In this case, the window caption does not depend on the name of the edited document. If an asterisk is part of the caption, then to specify it, use duplicated asterisks (for example, the string “MyEditor - DocName.txt**” corresponds to the caption “MyEditor - DocName.txt*”).

The titles of main windows often contain the application’s name followed by a hyphen and the name of the active window (or document, project, file and so on). TestComplete’s recorder will automatically record the string “*” for any caption that includes a hyphen. Thus, “GraphEditor - MyPicture1.bmp” is recorded as “*”.

Note that many windows, especially smaller ones, have no caption, that is, they all have the same caption, empty. Menus for instance, are captionless windows, and they are rather typical. Entire window classes are used without captions, making the caption useless to distinguish among siblings. In this case, to obtain a window, you should use other attributes: class name and index.

Index. The window’s index is more unstable than the window’s caption, but it is needed when a process or parent window has several child windows with the same caption and the same class name. The index is the current front-to-back onscreen position (similar to Z-order) of the window among windows of the same class with the same parent. Index 1 corresponds to the currently topmost window relative to other windows that have the same class name. The window index is determined by certain Windows API functions, so even if two or more windows visually have the same Z-order, they have different window indexes. To determine the index of the desired window, explore the application windows and controls in TestComplete’s Object Browser.

The index of an application window changes when other windows from the class are called onscreen or when the front-back position of this window changes.

TestComplete may not record a window’s index when you are recording a script, if the class name and caption provide enough information for the recognition of this window.

The window name contains the word Window followed by recognition attributes enclosed in parentheses:

The window name depends on the scripting language that is used in your project. For instance, if you use VBScript or JScript, you enclose the executable window class name and caption in quotes: Window("WndClass", "WndCaption", 1). In DelphiScript, you should use apostrophes instead of quotes, for instance, Window('WndClass', 'WndCaption', 1). In C++Script and C#Script the word Window should look like ["Window"].

The following code shows how to get access to one of the windows of the Microsoft Word process:

[VBScript]


69

Introduction

Set processObj = Sys.Process("winword")Set windowObj = processObj.Window("OpusApp", "Microsoft Word - *", 1)

[JScript]

processObj = Sys.Process("winword");windowObj = processObj.Window("OpusApp", "Microsoft Word - *", 1)


var processObj, windowObj : OleVariant;begin processObj := Sys.Process('winword'); windowObj := processObj.Window('OpusApp', 'Microsoft Word - *', 1)end;


var processObj, windowObj;processObj = Sys["Process"]("winword");windowObj = processObj["Window"]("OpusApp", "Microsoft Word - *, 1")

The hierarchy of windows depends on the Object tree model option of your TestComplete project. This option specifies the active object model: Flat or Tree. For complete information, see Object Tree Models in TestComplete help. We recommend to read this topic since knowing the tree model is essential for running the scripts. Scripts created for the Flat model will run incorrectly if the Tree model is active and vice versa.

To check the state of the Object tree model option in scripts, use the Options.Project.General.TreeModel property.

Using Custom Attributes to Obtain Window Objects

In order to identify windows you can use not only the mentioned attributes (class name, caption and index), but also other window attributes. For example, you can use the control identifier of a window. This identifier is an application-defined integer value associated with a window. The identifier value is returned by Windows API functions: GetWindowLong(hwndCtrl, GWL_ID) or GetDlgCtrlID(hwndCtrl). We use the term “control identifier” since this identifier is typically used to address child windows, for instance, controls on a form (controls are also windows). However, top-level windows also have identifiers.

The control identifier can be specified by a developer (for example, when they designed the dialog template in Visual Studio) or by the development tool itself (for instance, if the development tool does not support manual setting of the identifier). Though the identifier seems to be a persistent window attribute, it may be unspecified (0), its value may change from one application run to another or the program may return the same identifier for two different windows. If you do not find the identifier helpful, you can use the window caption, class name and index to find the desired window.

To obtain a child window by any combination of its property values, you can use the FindChild method of the desired parent object. TestComplete adds this method to all testing objects. For instance, to find a top-level window, you should call the FindChild method of the process to which this window belongs. A possible search condition may include a combination of the ChildCount, Visible, WndClass and WndStyle properties (or any other set of properties that let you uniquely distinguish the window). For instance, two forms may have different window styles (WndStyle property) and a different number of child windows (ChildCount property). Using the FindChild method you can obtain the desired object using


70


any combination of its properties. For more information on using the method, see the method description in TestComplete help.

The following code uses the FindChild method that returns a Window object by the window’s control identifier:

[VBScript]

Set processObj = Sys.Process("Notepad")Set windowObj = processObj.FindChild("ControlId", 133099, 1)

[JScript]

var p, w; p = Sys.Process("Notepad");w = p.FindChild("ControlId", 133099, 1);

[DelphiScript]

var processObj, windowObj;begin processObj := Sys.Process('Notepad'); windowObj := processObj.FindChild('ControlId', 133099, 1);end;

[C++Script, C#Script]

var processObj, windowObj; processObj = Sys["Process"]("Notepad");windowObj = processObj["FindChild"]("ControlId", 133099, 1);

To call the FindChild method in keyword test, you can use the Call Object Method or Run Code Snippet operation. A possible alternative is to use the Find Object operation.

To obtain a window by custom property values, you can also use the Name Mapping feature (we mentioned it at the beginning of the topic). Name mapping lets you visually specify the combination and values of the properties that will be used for recognition and to assign custom names to objects that will match the specified recognition criteria. Once you map an object, you can address this object in tests using the mapped name, rather than the object’s default name. For more information, see Name Mapping in TestComplete help.

Naming Controls and ObjectsIn terms of the operating system, controls that are displayed on applications’s forms are also windows. So, the way in which TestComplete names controls is very similar to the way, in which it names windows. These names depend on whether the control is mapped or not. If it is mapped, then TestComplete uses the mapped name or alias to address this control. Else, it uses the control’s ordinary (unmapped) name.

If the Map object names automatically setting is enabled in the Name Mapping Options dialog, TestComplete automatically maps window names during test recording or at design time, when you add operations to keyword tests or when you create checkpoints. After the object name is mapped, TestComplete uses the mapped name to address this object in keyword tests and scripts. The ordinary (unmapped) name can also be used, though.


71

Introduction

For more information on mapping object names, see Name Mapping. The rest of this topic will describe the principles that TestComplete uses to recognize controls and to form ordinary names.

Like window names, the names of controls depends on whether the application under test is an Open Application (white-box) or non-Open Application (ordinary, black-box).

Open Applications

If the tested application is an Open Application, you can address controls and objects using special methods provided by TestComplete. The method names depend on the development tool and libraries that was used to create the application: WinFormsObject for .NET applications, VBObject for Visual Basic applications, VCLObject for Delphi and C++Builder controls, SwingObject for Java applications created with the Swing library, and so on. These methods let you address the desired window by using the value specified by the application’s Name property, or by using the class name, caption and index. For complete information on using these methods, see the following topic:

Addressing Windows, Controls and Objects of Open Applications

Black-Box Applications

Since controls are windows, all the principles that are used to name windows are also applied to controls. To recognize them TestComplete uses attributes of window objects: class name, caption and index. Like window names, the control names consist of the word Window followed by recognition attributes in parentheses:

To specify the class names and captions you can use wildcards (* and ?). This feature lets you specify the names that are resistant to changes that occur during the application run or between the runs. This functionality is the same as the one used to address windows. For more information, see Naming Windows in TestComplete help.

The image above displays the general format of the control’s name. The format that will be used in keyword tests and scripts depends on the scripting language used in the project. The following sample demonstrates how to address controls in scripts:

[VBScript, Visual Basic]

Set processObj = Sys.Process("MyApp")

' Obtains a top-level window

Set windowObj = processObj.Window("WndClass", "WndCaption", 1)

' Obtains a control on the top-level window

Set windowObj2 = windowObj.Window("ControlWndClass", "ControlText", 1)

[JScript]

var processObj, windowObj, windowObj2;processObj = Sys.Process("MyApp");// Obtains a top-level windowwindowObj = processObj.Window("WndClass", "WndCaption", 1);// Obtains a control on the top-level windowwindowObj2 = windowObj.Window("ControlWndClass", "ControlText", 1);


72



var processObj, windowObj, windowObj2 : OleVariant;beginprocessObj := Sys.Process('MyApp');// Obtains a top-level windowwindowObj := processObj.Window('WndClass', 'WndCaption', 1); // Obtains a control on the top-level windowwindowObj2 := windowObj.Window('ControlWndClass'. 'ControlText', 1); end;


var processObj, windowObj, windowObj2;processObj = Sys["Process"]("MyApp");// Obtains a top-level windowwindowObj = processObj["Window"]("WndClass", "WndCaption", 1);// Obtains a control on the top-level windowwindowObj2 = windowObj["Window"]("ControlWndClass", "ControlText", 1);

The methods we use in the above example address the controls using the standard recognition attributes: class name, caption and index. But you can also use other properties or a combination of properties to obtain a reference to a control, for instance, you can use the control’s identifiers. The control identifier is an application-defined integer value associated with a control (window). It can be retrieved with the GetWindowLong(hwndCtrl, GWL_ID) or GetDlgCtrlID(hwndCtrl) Windows API functions.

The control identifier can be specified by a developer (for example, this is typically done for dialogs designed in Visual Studio) or by the development tool itself (for instance, if the development tool does not support manual setting of the identifier). If the application under test uses the control’s identifiers, you can use them to obtain the desired control.

In TestComplete, the control identifier is returned by the ControlID property of the window object that corresponds to the desired control. To obtain a control by its control identifier, call the FindChild method of the window object, to which the control belongs. This method obtains a child object by one or a combination of property values. For example, the following sample demonstrates how you can obtain a control by using the ControlId property. For a code sample that searches using a combination of properties, see the method description in TestComplete help:

[VBScript]

Set p = Sys.Process("Notepad")Set w1 = p.Window("Notepad", "Untitled - Notepad", 1)Set w2 = w1.FindChild("ControlId", 15, 1) ' Obtains a child window by ControlId

[JScript]

var p, w1, w2;

p = Sys.Process("Notepad");w1 = p.Window("Notepad", "Untitled - Notepad", 1); w2 = w1.FindChild("ControlId", 15, 1); // Obtains a child window by ControlId

[DelphiScript]

var p, w1, w2;begin p := Sys.Process('Notepad'); w1 := p.Window('Notepad', 'Untitled - Notepad', 1);


73

Introduction

w2 := w1.FindChild('ControlId', 15, 1); // Obtains a child window by ControlIdend;


var p, w1, w2; p = Sys["Process"]("Notepad");w1 = p["Window"]("Notepad", "Untitled - Notepad", 1);w2 = w1["FindChild"]("ControlId", 15, 1); // Obtains a child window by ControlId

To call the FindChild method in a keyword test, you can use the Call Object Method or Run Code Snippet operation.

A possible alternative to obtain an object by its property values in keyword tests is to use the Find Object operation.

Though the identifier seems to be a persistent window attribute, it may be unspecified (0), its value may change from one application run to another or the program may return the same identifier for two different control. If you do not find the identifier helpful, you can use the window caption, class name and index to find the desired window.

The hierarchy of windows depends on the Object tree model option of your TestComplete project. For complete information about the supported tree models, see Object Tree Models in TestComplete help. We recommend to read this topic since knowing the tree model is essential for running the scripts. Scripts created for Flat model will run incorrectly if the Tree model is active and vice versa.

To obtain a control by custom property values, you can also use the Name Mapping feature (we mentioned it at the beginning of the topic). Name mapping lets you visually specify the combination and values of the properties that will be used for recognition and to assign custom names to objects that will match the specified recognition condition. Once you map an object, you can address this object in tests using the mapped name, rather than the object’s default name. For more information, see Name Mapping in TestComplete help.

Naming Web ObjectsWhen testing Web pages, TestComplete works with the elements of web pages as it would with application objects. The way in which TestComplete addresses elements of web pages depends on whether the window is mapped or not. If the element is mapped, then TestComplete uses its mapped name or alias. Else, it uses default names.

If the Map object names automatically setting is enabled in the Name Mapping Options dialog, TestComplete automatically maps objects during test recording or at design time, when you add operations to keyword tests or when you create checkpoints. After the object was mapped, TestComplete uses the mapped name to address this object in keyword tests and scripts. However, the default name can also be used.

The default names used for the web pages’ objects depend on the Web Testing | Tree model project setting. It specifies the object model (DOM, Tag, Tree or Hybrid) on the page. The objects’ names in these models are different. For detailed information on how they are formed, see Web Tree Models in TestComplete help. You can see the names, which TestComplete uses to address web page elements, in the Object Browser panel.


74


Keyword Testing in TestComplete

This topic explains the basic concepts of keyword-driven tests in TestComplete and briefly describes how to create, record, modify, run and debug these tests. The topic contains the following sections:

Keyword Tests – Overview

Creating and Editing Keyword Tests

About Operations, Their Parameters and Result Values

Running Tests

Parameters of Keyword Tests

Keyword Test Variables

Debugging Keyword Tests

Keyword Tests vs. Scripts

Creating Custom Keyword Test Operations

Keyword Tests – OverviewKeyword-driven tests consist of keywords that define the action to be performed by the test. Each keyword corresponds to an individual action like mouse click, selection of a menu item, keystrokes, opening or closing a window and so on. So, a series of keywords correspond to the actions a user performs during the test. The testing approach that uses these tests is called keyword-driven testing. We skip the word “-driven”, so in TestComplete UI and documentation this testing approach is called keyword testing and keyword-driven tests are called simply keyword tests.

In TestComplete, the keywords (actions) that make up a keyword test are called operations. Each operation has a number of parameters that define the details of the action to be performed.

To create keyword tests with TestComplete, you should add the Keyword Testing item to your project. This item serves as a storage for keyword tests. The tests are shown as child elements of the Project Explorer panel. The collection’s node is called KeywordTests:


75

Introduction

Note that the KeywordTests project item and its child elements (keyword tests) are available only if the Keyword Testing and Keyword Test Editor plug-ins are installed in TestComplete. To check whether the plug-ins are installed, select File | Install Extensions from TestComplete’s main menu and look at the plug-ins list in the ensuing Extensions dialog. The plug-ins must be there and must be enabled:


76


Creating and Editing Keyword TestsYou can create keyword tests in several ways:

The easiest way is to record a keyword test. You can start recording a new keyword test or record this test during script recording.

You can create the keyword test by using the context menu of the Project Explorer panel. The created tests are empty, so you will have to append operations to them in the KeywordTest Editor.

You can also create tests in the Project Wizard at the time of the project creation.

Finally, you can add existing keyword tests to your project by using the context menu of the Project Explorer panel.

For detailed information on recording and adding keyword tests to your project, see Creating and Recording Keyword Tests in TestComplete help.

After recording or creating an empty keyword test, you can modify it in the KeywordTest Editor:


77

Introduction

For information on working in the editor, see Editing Keyword Tests in TestComplete help.

About Operations, Their Parameters and Result ValuesTestComplete provides a number of operations that you can use in your keyword tests. The operations that you can add to your test are shown in the Operations list on the left of the KeywordTest Editor:


78


Operations are organized into a number of categories. For example, operations of the Logging category let you post messages and images to the test log. By using operations of the Checkpoints category you can execute various verification actions from your tests. Operations of the Test Actions category let you simulate different test actions over your tested application, call script routines or just short code snippets and run other tests (for instance, low-level procedures and load tests) from your keyword test. You can even run other keyword tests from your test.

For more information about available operations, see Operations Reference inTestComplete help.

Keyword test operations have parameters that let you specify input values for the action to be performed. An operation may not have parameters, if the action does not need additional parameters.

You specify operation parameters in special dialogs which are displayed when you add the operation to your keyword test. You can also modify the parameters any time later by using the dialogs and in-place editors provided by the KeywordTest Editor. For detailed information on parameters of an operation, see the operation’s description.

To specify parameters, you can use values of different kinds: string or integer constants, code expressions, keyword test parameters, properties of onscreen objects and so on. This is described in the Specifying Operation Parameters topic in TestComplete help. We recommend that you read it when modifying the parameter values.

Some keyword test operations can return result values. TestComplete offers special means that let you check the operation’s result from your keyword tests. For more information on this, see Checking Operation Result in TestComplete help.

Note: TestComplete uses special grouping nodes to organize operations that were executed


79

Introduction

subsequently and dealt with the same window or processes. These operations are displayed as child nodes of the window or process node and these window or process nodes are called grouping nodes:

Grouping nodes do not perform any actions, they do not have parameters and do not return values. They are used to make the structure of keyword tests clearer and easy to understand. TestComplete creates these nodes automatically during test recording, if you perform several actions on the same window or process, or at design time, if you append several operations that work with the same window or process in a series.

To group the operations in your test, you can also use the Group operation.

Running TestsYou can execute keyword tests in any of the following ways:

You can run the test as a test item of your project.

You can run the test from the Project Explorer panel.

You can run the test from the KeywordTest Editor. Here you can either run the entire test, an individual operation or a part of the test starting from one particular operation to the end of the test.

You can run a keyword test from another keyword test.

And of course you can run keyword tests from scripts.

Before running the test, you may need to specify its parameters (see section below).


80


For detailed information, see Running Keyword Tests in TestComplete help.

For information on how to output data from the test and obtain its result, see Getting Keyword Test Result in TestComplete help.

Parameters of Keyword TestsA keyword test can have one or more parameters that let you pass additional values to the test before running it. This feature helps you easily re-use existing tests and perform various testing actions with minimum efforts.

The way in which you specify test’s parameters depends on the way, in which you run the test:

If you run a keyword test as a project’s test item, then you can specify the parameters’ values in the Test Parameters dialog (it is called from the Test Items editor and is used to specify parameters of keyword tests and script routines that are run as test items).

If you run a keyword test from another keyword test, you specify the parameters in the Operation Parameters dialog which is shown when you add the test running operation to your keyword test.

If you run a test from script code, then you can specify the test’s parameters from script code.

Parameters may have default values. In this case, you can omit them when calling the test.

You create test parameters and specify their default values on the Parameters page of the KeywordTest Editor or using the Add Parameter wizard.

For detailed information on test parameters, see Keyword Test Parameters in TestComplete help.

Keyword Test VariablesA keyword test can have one or more variables. We call these variables keyword test variables. Using these variables you can assign values to operation parameters, store various values and references to objects and pass data from one operation to another during the test execution. You can also use these variables to output data from your keyword test.

You create keyword test variables, specify their type and default values in the Variables page of the KeywordTest Editor or using the Add Variable wizard.

TestComplete provides the Set Variable Value operation that lets you change the variable’s value from your keyword tests. The keyword test variables are also accessible from scripts.

Keyword test variables do not save their values between test runs. Before running a keyword test, TestComplete initializes the variables with their initial values that you specified on the Variables page.

For detailed information on working with variables of this kind, see Keyword Test Variables in TestComplete help.


81

Introduction

Debugging Keyword TestsTestComplete includes the keyword test debugger that supports powerful debugging features. You can set ordinary or conditional breakpoints on individual operations of your test, run the test to the cursor, trace into or step over tests that are called from your test, explore the values of the test variables in the Evaluate dialog and perform other actions.

All of the panels that are involved in debugging - Locals, Watch List, Call Stack, Breakpoints - support the keyword test debugger. Furthermore, the script and keyword test debuggers are tightly integrated, so, for instance, if you debug a keyword test, you can trace into the script routine that is called from this test and continue debugging script code. Similarly, if you debug a script that runs a keyword test, you can trace into this test and debug it.

For detailed information on debugging services provided by TestComplete, see Debugging Tests in TestComplete help.

Keyword Tests vs. ScriptsA keyword test is similar to a script routine. Like the routine, it can have variables and parameters. It contains operations that, like function calls in script code, let you perform various actions during the test.

The benefit of keyword tests is that in many cases it is easier and faster to create them than to write the script equivalent. To create keyword tests you do not have to know the peculiarities of certain scripting languages. So, you can use keyword tests if you are an inexperienced TestComplete user or when you need to create a simple test quickly.

However, the number of keyword test operations is limited and sometimes it may be more convenient to run script code to perform tasks. Also, the scripting engine provides a lot of objects and offers more powerful functionality than keyword test operations. So, you can use scripts to run some complex portions of your tests or perform those actions that do not have keyword test analogues.

Creating Custom Keyword Test OperationsYou can extend the set of available operations by creating your own operations. You can create operations using the script extensions technology. For more information, see Creating Keyword Test Operations in TestComplete help.

TestComplete includes the Log Attributes operation that is implemented with the help of script extensions. You can find the operation’s source code in the AQAScriptExtensions.tcx file that is located in the <TestComplete>\Bin\Extensions\ScriptExtensions folder. This file is a ZIP archive that has the .tcx extension. So, you can use any zip archiver to unpack files from it. For information on the extension’s files, see Pre-Installed Script Extensions in TestComplete help.


82


Scripting in TestComplete

Writing Scripts – OverviewAbout Scripts

There are two basic ways to create a script:

Record a script using TestComplete’s script recorder (see Recording In TestComplete in help).

-- or --

Write a script in TestComplete’s Code Editor.

The easiest way to begin scripting is to use the recorder. The script can be edited further through the Code Editor.

A script is a procedure or function in one of the supported scripting languages (see the Scripting Languages section below). Scripts are grouped into unit files, and each project may use as many units as needed. In the hierarchy of project elements, all the units belong to the Script project item. When you create a new project, TestComplete automatically creates the Script project item with one unit in it.

A typical script that simulates user actions contains the following statements:

Sys.Process(…) - This method returns an object that provides a scripting interface to the process of the tested application.

processObj.Window(…), windowObj.Window(…) - These methods return windows of objects or child windows of a parent window (controls on an application form).

windowObj.Click, windowObj.DblClick, etc., - These statements simulate user actions over a window.

For more information on these instructions, see How TestComplete Recognizes Processes, Windows and Controls and Simulating User Actions in TestComplete help.

Scripts may be called from other scripts, by name if in the same unit, else using the <unit name>.<script> format. You can also import units of other projects. See Calling Routines and Variables Declared in Another Project in TestComplete help.

Note: Since the unit name can be used in script code, the unit name should be a valid script identifier and it should not coincide with the name of an existing programming object. If the unit name is invalid, you have to rename the unit. You can do this in the same way you rename any other project items. See Renaming Projects, Project Suites and Project Items in TestComplete help.


83

Introduction

Whenever you run a command execution of any script, TestComplete checks all script units for syntax errors. The script will not be run if syntax errors are found. You can check syntax by right-clicking the desired unit in the Project Explorer and selecting Check Syntax from the context menu.

Scripting Languages

The scripting language for the project is specified during the project’s creation. You can choose from one of the five scripting languages: VBScript, JScript, DelphiScript (a subset of Object Pascal), C++Script or C#Script (both based on the JScript engine). All languages are restricted to variables of the OleVariant compatible type, and cannot use pointers. Types specified in variable or function declarations are ignored.

DelphiScript support is built into TestComplete. VBScript and JScript are supported by DLLs (of the same name) shipped with Windows and Internet Explorer. Since C++Script and C#Script are based on JScript, they also depend on these DLLs. To run VBScript, JScript, C++Script or C#Script in TestComplete, Internet Explorer 5.0 or higher must be installed on the machine. If you do not have the required version of Internet Explorer, you can install the Microsoft scripting components directly. The latest version of these DLLs (as a part of Windows Script Components) is available at http://www.microsoft.com/downloads.

For debugging VBScript, JScript, C++Script and C#Script routines, you must have either Microsoft Visual InterDev or Microsoft Script Debugger installed. Microsoft Script Debugger is free and can be downloaded from http://www.microsoft.com/downloads. Debugging of DelphiScript routines does not require any additional software.

TestComplete is equally oriented on each of the supported scripting languages. However, each of the languages has its pros and cons that may or may not match your specific requirements. Read the Selecting a Scripting Language topic to decide what language you should choose.

For complete information on the supported scripting languages, use the links below:

VBScript http://msdn.microsoft.com/en-us/library/ms950396.aspx

JScript http://msdn.microsoft.com/en-us/library/ms950396.aspx

DelphiScript DelphiScript Description in TestComplete help

C++Script Writing C++ Scripts in TestComplete help

C#Script Writing C# Scripts in TestComplete help

Scripts and Connected and Self-Testing Applications

Everything that can be done in a script can also be done in application code, using TestComplete’s Connected Application facility. Such connected code is free from the limitations of scripting languages, and has the same access to application internals as ordinary application code. It can also be debugged by the development tool’s debugger, just like the rest of the application’s source.

Connected code can be written directly in the application’s source editor. However, it can also be read from TestComplete’s project source and copied to the application source. VBScript can be read by the Visual Basic compiler or interpreter; DelphiScript code - by Delphi; C++ code can be read by any C++ compiler, but the necessary library to make a Connected Application is compiler-specific, and only Microsoft Visual C++ and Borland C++Builder are supported. C#Script code can be read by any C# compiler, but to make a C# Connected or a Self-Testing Application, you will have to add certain assemblies to the application.

Script File Format and Source Control Systems


84

http://msdn.microsoft.com/en-us/library/ms950396.aspx


http://www.microsoft.com/downloads

http://www.microsoft.com/downloads


TestComplete’s script files can have either ANSI, UTF-8 or Unicode (UTF-16) format. Some source control systems treat Unicode files as binary and thus do not let you perform some operations over such files, for example, compare or merge. Please refer to the documentation on your source control system to learn how you can work with Unicode files.

To solve the problem, you can also change the character encoding format used in your project for script files. For more information on this, see Character Encoding in TestComplete help.

Selecting the Scripting LanguageThe scripting language for the project is specified at the project creation time and cannot be changed later. TestComplete supports the five languages: VBScript, JScript, Delphi, C++Script and C#Script. The languages are quite different, so you may ask “Which one should I choose for my project?”

First of all, we would like to note that the scripting language does not depend on your tested application’s programming language. For instance, you can use JScript to test Visual C++ applications, or VBScript to test Delphi programs. There is only one recommendation: if you plan to create a Connected or a Self-Testing Application, you should select the scripting language that matches the development tool where you will create that application. That is, if you use Visual C++ or C++Builder, you should select C++Script; if you use Visual Basic, select VBScript; if you use C#, use C#Script, and if your using Delphi, select DelphiScript. This will make it easier to import recorded scripts to Connected and Self-Testing Applications.

The vast majority of TestComplete features is equally oriented on each of the five supported languages. So, you can select the language that is closer to your development skills. This will decrease the test creation time, since you will not have to learn a new language.

You will not be limited in functionality if you prefer one language to another - you will be able to use all of TestComplete’s features regardless of which language you choose. However, due to the fact that languages have different syntax and work via different engines, there are few exceptions:

The size of a DelphiScript unit in a TestComplete cannot exceed 1 MB. There is no such a limitation for projects created in other scripting languages (VBScript, JScript, C++Script and C#Script).

JScript does not support functions that obtain parameters by reference. The same applies to C++Script and C#Script since these languages work via the JScript engine.

Any of the supported scripting languages let you call routines and variables defined in another unit. However, circular references between units are supported in VBScript and DelphiScript only and are not supported in JScript, C++Script and C#Script.

JScript, C++Script and C#Script may handle exceptions incorrectly when the try{} block holds calls to routines defined in other units. That is, the try... catch... finally block works correctly only when it does not hold calls to routines from other units.

Some users consider that exception handling in JScript, C++Script, C#Script or DelphiScript may be more convenient than exception handling in VBScript.

The format of arrays in JScript, C++Script and C#Script differs from the DelphiScript and VBScript (see Supported Scripting Languages - Peculiarities of Usage). This affects the usage of some routines (for example, the Find and FindAll methods) in JScript, C++Script and C#Script code. For more information, see documentation for the specific method.


85

Introduction

For information on usage peculiarities of supported scripting languages, see Supported Scripting Languages - Peculiarities of Usage.

One more criterion that may affect the selections of the scripting language is the set of predefined language functions. Each scripting language provides a number of built-in functions that help you perform some routine actions, such as converting numerical values to strings and vice versa (C++Script and C#Script have the same functions as JScript, since these languages are based on JScript). Normally, the sets of predefined functions of different scripting languages are similar to each other, with few exceptions (for instance, DelphiScript does not have an analogue of VBScript’s split function). However, the difference in predefined functions is negligible, since most of predefined functions are simple and you can easily create their analogues in another language.

Writing Scripts – Quick Start 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.

Note: We recommend that you read Writing Scripts – Overview before you proceed.

General Notes

To write scripts, you must add the Script project item to your project. You can do this at the time of the project creation or any time later using TestComplete’s dialogs. For more information, see Adding and Removing Project Items and Their Child Elements in TestComplete help.

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.

The unit name can be used in script code, so the unit name should be a valid script identifier and it should not coincide with the name of an existing programming object. If the unit name does not match these rules, you have to rename the unit. You can do this the same way you rename any other project items. See Renaming Projects, Project Suites and Project Items.

You can call script routines defined in one unit from another unit. You can also import units created in other projects into your project.

To modify the code of a unit, right-click this unit in the Project Explorer and choose Edit from the context menu. TestComplete will open the Code Editor with the unit’s code in the Workspace panel.

The Code Editor offers an abundance 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 in TestComplete help.

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


86


[VBScript]

TestedApps.RunAll

[JScript]

TestedApps.RunAll();

[DelphiScript]

TestedApps.RunAll();


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:

[VBScript]

TestedApps.Items(0).Run(1)

[JScript]

TestedApps.Items(0).Run(1);

[DelphiScript]

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


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 in TestComplete help.

For more information on tested applications, see Tested Applications and Working With Tested Applications From Scripts in TestComplete help.

Addressing Processes, Windows and Controls

Before you simulate a user action over a window or control, you should obtain a program object that provides scripting interface to that window (control). To do this, you should first obtain a process, to which the desired window belongs (in TestComplete object model, processes are children of the System (Sys object), windows are children of processes).

If you started a tested application by calling the Run method of the TestedApp object in your script code, then the method will return the process object corresponding to the launched application:

[VBScript]

Set p = TestedApps.Items(0).Run(1)


87

Introduction

[JScript]

var p;p = TestedApps.Items(0).Run(1);

[DelphiScript]

var p : OleVariant;begin p := TestedApps.Items[0].Run(1);end;


var p;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. 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:

[VBScript]

Set p = Sys.Process("Notepad")

[JScript]

p = Sys.Process("Notepad")

[DelphiScript]

var p : OleVariant;begin p := Sys.Process('Notepad');…end;


var p;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 either post an error message to the test log or display an error message on screen. The action to be performed is specified by the When referring to a non-existent object that can be changed in the Engines – General Options dialog. To invoke this dialog, choose Tools | Options from TestComplete’s main menu and then select Engines | General on the left of the ensuing Options dialog.


88


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:

[VBScript]

Set p = Sys.WaitProcess("Notepad", 2000)If Not p.Exists Then ' Process does not existEnd If

[JScript]

p = Sys.WaitProcess("Notepad", 2000)if (! p.Exists) // Process does not exist...

[DelphiScript]

var p : OleVariant;begin p := Sys.WaitProcess('Notepad', 2000); if not p.Exists then // Process does not exist ...end;


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 have the process, you can obtain windows belonging to this process. The way you do this depends on whether your application is compiled as an Open Application or not. Open Applications provide TestComplete with access to their internal objects, methods and properties. TestComplete “opens” most types of applications using special plug-ins. For complete information on this, see Open Applications -Overview in TestComplete help.

If your application is an Open Application, you can address windows using one of the following special methods:

Method Description

WinFormsObject Provides access to windows in Microsoft .NET applications by object name or by control class name, window text (caption) and index.

VCLNETObject Provides access to windows in Borland VCL.NET applications by object name or by control class name, window text (caption) and index.


89

Introduction

VBObject Provides access to windows in Visual Basic 6.0 applications by object name.

VCLObject Provides access to windows in Delphi and C++Builder VCL Open Applications by object name.

CLXObject Provides access to windows in Delphi and C++Builder CLX Open Applications by object name.

SwingObject Provides access to windows in Java Swing applications by object name or by class name, caption and index.

AWTObject Provides access to windows in Java AWT applications by object name or by class name, caption and index.

SWTObject Provides access to windows in Java SWT applications by object name or by class name, caption and index.

WFCObject Provides access to windows in Java WFC applications by object name or by class name, caption and index.

WPFObject Provides access to windows in WPF (XAML) applications by object name.

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.

[VBScript]

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

[JScript]

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

[DelphiScript]

var p1, w1 : OleVariant;begin p1 := Sys.Process('MyApp'); w1 := p1.WinFormsObject('MainForm');end;


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.


90


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 (see Name Mapping in TestComplete help).

Find for the window using the Find 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:

[VBScript]

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

[JScript]

p1 = Sys.Process("MyApp");w1 = p1.Window("WindowClassName", "WindowCaption", 1);// orw1 = p1.WaitWindow("WindowClassName", "WindowCaption", 1, 2000);

[DelphiScript]

var p1, w1 : OleVariant;begin p1 := Sys.Process('MyApp'); w1 := p1.Window('WindowClassName', 'WindowCaption', 1); // or w1 := p1.WaitWindow('WindowClassName', 'WindowCaption', 2000);end;


var p1, w1; p1 = Sys["Process"]("MyApp");w1 = p1["Window"]("WindowClassName", "WindowCaption", 1);// orw1 = 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


91

Introduction

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 either post an error message to the test log or show an error message on screen. Which actions are performed is specified by the When referring to a non-existent object option, described above.

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

[VBScript]

Set p1 = Sys.Process("MyApp")Set w1 = p1.WinFormsObject("MainForm") Set w2 = w1.WinFormsObject("Button1") ' or Set w2 = w1.Button1

[JScript]

p1 = Sys.Process("MyApp");w1 = p1.WinFormsObject("MainForm");w2 = w1.WinFormsObject("Button1"); // w2 = w2.Button1;

[DelphiScript]

var p1, w1, w2 : OleVariant;begin p1 := Sys.Process('MyApp'); w1 := p1.WinFormsObject('MainForm'); w2 := w1.WinFormsObject('Button1'); // w2 := w1.Button1;end;



92


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 cateogry 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 in TestComplete help. 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


93

Introduction

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 Naming Objects in TestComplete help.

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

[VBScript]

Set p1 = Sys.Process("notepad")Set w1 = p1.Window("#32770", "Open", 0)Set w2 = w1.Window("Button", "&Open", 1)w2.ClickButton

[JScript]

p1 = Sys.Process("notepad");w1 = p1.Window("#32770", "Open", 0);w2 = w1.Window("Button", "&Open", 1);w2.ClickButton();

[DelphiScript]

var p1, w1, w2 : OleVariant;begin p1 := Sys.Process('notepad'); w1 := p1.Window("#32770", "Open", 0); w2 := w1.Window("Button", "&Open", 1); w2.ClickButton();end;


var p1, w1, w2;p1 = Sys["Process"]("notepad");w1 = p1["Window"]("#32770", "Open", 0);w2 = w1["Window"]("Button", "&Open", 1);w2["ClickButton"]();


94


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 Working With Win32 Controls – Basic Concepts in TestComplete help). 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 Working With Custom Controls in TestComplete help.

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 in TestComplete help.

For complete information on simulating user actions, see Simulating User Actions in TestComplete help.

Retrieving Data From Application Objects, Windows and Controls

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 Retrieving Data From Application Objects, Windows and Controls in TestComplete help You may also find the Working With Grids topic helpful.

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

[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 "


95

Introduction

[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 ");

[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');


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 in TestComplete help.

Database Access

To work with databases directly from your scripts, use TestComplete’s 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:

[VBScript]

Set AConnection = CreateObject("ADODB.Connection")' Specify the connection stringAConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.3.51;" + _"Data Source=C:\Microsoft Visual Studio\VB98\biblio.mdb"' Activate the connectionAConnection.Open…

[JScript]

AConnection = new ActiveXObject("ADODB.Connection");// Specify the connection stringAConnection.ConnectionString = "Provider=Microsoft.Jet.OLEDB.3.51;" +"Data Source=C:\\Microsoft Visual Studio\\VB98\\Biblio.mdb";// Activate the connectionAConnection.Open();

…

[DelphiScript]


96


var

AConnection : OleVariant;begin AConnection := Sys.OleObject('ADODB.Connection'); // Specify the connection string AConnection.ConnectionString := 'Provider=Microsoft.Jet.OLEDB.3.51;' + 'Data Source=C:\Microsoft Visual Studio\VB98\biblio.mdb'; // Activate the connection AConnection.Open; …end;


var AConnection;AConnection = Sys["OleObject"]("ADODB.Connection");// Specify the connection string

AConnection["ConnectionString"] = "Provider=Microsoft.Jet.OLEDB.3.51;" +"Data Source=C:\\Microsoft Visual Studio\\VB98\\Biblio.mdb";// Activate the connectionAConnection["Open"]();…

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

Calling 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 instance, to execute a low-level procedure from a script, you can use the following code:

LLPCollection1.LLP1.Execute()

Here LLPCollection1 is the name of the Low-Level Procedures Collection project item as it is shown in the Project Explorer. LLP1 is the name of the desired low-level procedure.

Similarly, you can initiate execution of tests provided by other project items (HTTP Load Testing, Manual Testing, Unit Testing, etc.) For more information on how to do this, see the description of the appropriate project item in TestComplete help.

Calling Routines and Variables Declared in Another UnitBy default, script code can call only those routines (procedures or functions), variables and constants that reside within the same unit. To call routines, variables or constants declared in another unit, the current unit must be “linked” to it.

To link another unit, you should add a special directive to the current unit. The directive syntax depends on the scripting language. The exact rules for each of the supported languages are provided below:


97

Introduction

Instructions for VBScript projects

Place the cursor at the beginning of the unit and add the following string:

[VBScript]

'USEUNIT Unit_Name

Be sure to specify the apostrophe ( ' ) before USEUNIT.

To link several units, use the following syntax:

[VBScript]

'USEUNIT Unit1_Name'USEUNIT Unit2_Name

If you have a VBScript class defined in one unit and you want to create a class instance from another unit, then using the USEUNIT statement is not enough. You also have to create a special routine that will return the desired class instance. For more information, see Supported Scripting Languages - Peculiarities of Usage.

Instructions for DelphiScript projects


[DelphiScript]

uses Unit_Name;

If you need to link several units, separate their names with commas:

[DelphiScript]

uses Unit1_Name, Unit2_Name;

Instructions for JScript, C++Script and C#Script projects


[JScript, C++Script, C#Script]

//USEUNIT Unit_Name

Be sure to specify the double slash ( // ) before USEUNIT.

You can link to several units in the following manner:


//USEUNIT Unit1_Name//USEUNIT Unit2_Name

The USEUNIT statement does not allow tab or space characters at the beginning of the line and between the USEUNIT and the comment operator (' in VBScript and // in JScript). So,


98


the following use of USEUNIT will cause an error:

[VBScript]

' USEUNIT Unit_Name 'USEUNIT Unit_Name...


// USEUNIT Unit_Name //USEUNIT Unit_Name...

Besides, TestComplete allows a unified method to create unit references:

Right-click the desired scripting unit in the Project Explorer, and select the Add Unit References menu item (this command is disabled unless the Script node contains two or more units).

In the ensuing Add Unit References dialog:

Choose the “Add the following unit references to the <Unit_Name> unit” action type

Mark the check boxes against those units that hold the desired routines and variables

Press OK to close the dialog and add the references to the chosen units.

The latter approach is more convenient, since TestComplete recognizes the scripting language of the selected units and inserts valid directives.

Once an external unit is linked to the current one, all routines as well as global variables and constants of the external unit can be called in the current unit. However, this is possible only if the current unit does not contain a routine, a global variable or a global constant of the same name. You can work around this problem by prefixing external calls by their unit names. That is, you can use the following syntax:

MyUnit.MyRoutine(Param1, Param2) MyUnit.MyVariableMyUnit.MyConstant

Note: If you want to make a variable (constant) visible in other units, you need to declare this variable (constant) outside of any routine, that is, you need to declare a global variable or constant. Otherwise, the variable (constant) will be visible only within the routine where it is declared.

To call script routines located in another script unit, you can also use the Runner.CallMethod method. It calls any routine specified by its full name (that is, unit_name.routine_name). If you call a script routine using this function, there is no need to include the unit specified by unit_name in the uses (USEUNIT) clause of the current unit.

TestComplete can also call routines, variables or constants declared in a third unit. That is, if the current unit is linked to another unit that is linked to a third unit, the script declared in the third unit can be called in the current unit. For instance, if you need to call function declared in UnitA from UnitC, that is linked to UnitB, you must add references to UnitA in UnitB:

[VBScript]


99

Introduction

UnitA Function TestProcedure() Log.Message "The procedure is run."End Function ... UnitB'USEUNIT UnitA... UnitC'USEUNIT UnitBSub Main UnitA.testProcedureEnd Sub ...

[JScript]

UnitAfunction testProcedure(){ Log.Message("The procedure is run.");}... UnitB//USEUNIT UnitA ... UnitC//USEUNIT UnitB function Main(){ UnitA.testProcedure();} ...

[DelphiScript]

UnitAfunction testProcedure();begin Log.Message('The procedure is run.');end; ... UnitBuses UnitA;... UnitCuses UnitB;Procedure Main;begin UnitA.testProcedure;


100


end; ...


UnitA function testProcedure(){ Log["Message"]("The procedure is run.");}... UnitB//USEUNIT UnitA ... UnitC//USEUNIT UnitB function Main(){ UnitA["testProcedure"]();} ...

Note, the scripts declared in a fourth unit and greater cannot be called in the current unit.

Note that DelphiScript and VBScript units in TestComplete can refer to each other. In other words, circular references are allowed. For instance, if you need to call scripts declared in UnitA from UnitB, and to call scripts declared in UnitB from UnitA, you must add references to both units --

[VBScript]

UnitA

'USEUNIT UnitB

...

UnitB

'USEUNIT UnitA

...

[DelphiScript]

UnitA

uses UnitB;

...

UnitB

uses UnitA;

...

Note: The circular reference is not allowed in JScript, C++Script and C#Script. Circular links in these languages may cause errors in the jscript.dll (C++Script and C#Script are based on


101

Introduction

JScript and also use this DLL) and these errors can cause other errors in TestComplete.

Supported Scripting Languages – Peculiarities of UsageTestComplete supports the following scripting languages:

VBScript

JScript

DelphiScript

C++Script

C#Script

These languages have different syntax and work via different scripting engines. Their usage has some peculiarities described below. These are features concerning the language support in TestComplete as well as some peculiarities, which are not well-known and can be overlooked by beginners.

Peculiarities Common for All Languages

There is one peculiarity that is common for all supported scripting languages. It concerns the methods’ and functions’ names.

You can skip the object name when calling methods of some program objects in scripts. This feature is supported by the aqConvert, aqEnvironment, aqObject, aqUtils, BuiltIn, Utilities and Win32API objects. For example, you can call the Delay method of the aqUtils object as aqUtils.Delay(…) or as simply Delay(…). Custom objects can support this functionality as well.

However, if the method name coincides with the name of an intrinsic function of the scripting language, TestComplete will call that function rather than the object’s method.

To solve the problem, put the object name before the method name. For example:

[DelphiScript]

// Calls the IntToStr method of the aqConvert objectstr := aqConvert.IntToStr(1235);Log.Message(str);

// Calls the DelphiScript's IntToStr functionstr := IntToStr(1235);Log.Message(str);

VBScript

The usage of VBScript has the following peculiarities:

If you assign an object to a variable or property, use the Set statement, for example:

[VBScript]

Set p = Sys.Process("MyProcess") ' Correctp = Sys.Process("MyProcess") ' Incorrect !!!


102


In TestComplete, script units can refer to each other, so you can call routines and variables defined in one unit from another unit. VBScript supports circular references between units.

To debug VBScript code, you may need to modify Internet Explorer's options. Also, if you work under a user account (not an administrator account), you may need permissions for the Machine Debug Manager's system component. For more information, see Debugging Scripts in TestComplete in TestComplete help.

Variables that are declared with the Dim statement within a routine are only visible within that routine. Variables that are used without declaring them with Dim, become global variables. This behavior may cause hidden influence of routines onto other routines. For instance, the execution of the following code never ends:

[VBScript]

Sub ChildSub For i = 0 To 5 ... NextEnd Sub

Sub ParentSub For i = 0 To 10 ChildSub NextEnd Sub

This happens because after a call to ChildSub, the i variable is always 5 and never 10, so the loop within the ParentSub procedure becomes an infinite loop.

VBScript does not support short-circuit logical operations. This means that all parts of a complex condition are evaluated, even if the result is determined by the first condition only. This peculiarity complicates evaluating complex conditions where subsequent conditions rely on the success of the previous ones.

To illustrate this, suppose you have the following code:

[VBScript]

Sub Test Dim w Set w = Sys.Process("notepad").WaitWindow("Notepad", "Untitled - Notepad", 1, 1000)

If w.Exists And w.VisibleOnScreen Then Sys.HighlightObject(w) Else Log.Error("Cannot highlight the Notepad window.") End IfEnd Sub

In case the Notepad window cannot be found (for example, its caption is different from "Untitled - Notepad"), the w variable will be assigned with a stub object that only has the Exists property equal to False. However, the w.VisibleOnScreen property will still be tested, so you will get the following error in the test log:


103

Introduction

The object does not exist.You are trying to call the "VisibleOnScreen" method or property of the "Window("Notepad", "Untitled - Notepad", 1)" object that does not exist.

To workaround this limitation, you can evaluate conditions separately:

[VBScript]

If w.Exists Then If w.VisibleOnScreen Then Sys.HighlightObject(w) Else Log.Error("The Notepad window is not visible on screen.") End IfElse Log.Error("The Notepad window is not found.")End If

-- or --

[VBScript]

ok = w.ExistsIf ok Then ok = w.VisibleOnScreen

If ok Then Sys.HighlightObject(w)Else Log.Error("Cannot highlight the Notepad window.")End If

If you have VBScript engine ver. 5 or later, you can create and use classes in your scripts. For more information on VBScript classes, see Microsoft Development Network (http://msdn.microsoft.com/en-us/library/ms950396.aspx).

Note that you can create class instances only in the unit, in which the class is defined. Creating a class from another unit will cause an error. The following code demonstrates this:

[VBScript]

[UnitA]Class MyClass ...End Class

Sub TestRotuine ... ' Creating class in the same unit Set cls = New MyClass ' OK! ...End Sub

[UnitB]


104



'USEUNIT UnitA

Sub AnotherRoutine ... ' Creating class in another unit Set cls = New MyClass ' Error! ...End Sub

To solve the problem, you can create a helper routine in the unit, in which the class is defined. This routine will create a class instance and return it. You can then call this routine from another unit and work with the created class instance in a usual manner:

[VBScript]

[UnitA]

Class MyClass ...End Class ' This routine creates and returns a new class instanceFunction GetClassInstance Set GetClassInstance = New MyClassEnd Function

[UnitB]

'USEUNIT UnitA

Sub AnotherRoutine ... ' Calling a routine defined in UnitA. ' Do not forget to include this unit with the USEUNIT statement Set cls = GetClassInstance ' OK ! ...End Sub

DelphiScript

DelphiScript support is built into TestComplete. The usage of DelphiScript has the following peculiarities:

The size of a DelphiScript unit in TestComplete cannot exceed 1 MB. This limitation does not exist for projects created in other scripting languages (VBScript, JScript, C++Script and C#Script).

In TestComplete script units can refer to each other, so you can call routines and variables defined in one unit from another unit. DelphiScript supports circular references between units.

In Object Pascal, the body of a function or a procedure can contain declarations of other functions and procedures, for example:

[Delphi]

procedure FuncA;


105

Introduction

procedure FuncB; begin … end; begin …end;

Nested routine declarations are not allowed in DelphiScript scripts that are run from TestComplete. This restriction does not exist in Delphi Connected Applications.

DelphiScript does not support enumeration through collections similar to using the VBScript For Each ... In statement or JScript Enumerator object. So, collection enumeration in DelphiScript is more complicated than in other languages, and sometimes even impossible.

DelphiScript’s ExceptionMessage function cannot be evaluated in TestComplete’s Watch List panel and Evaluate dialog.

The DelphiScript engine does not allow you to call script routines located in the web pages if you use the DOM model. This restriction does not apply to the Tag, Tree or Hybrild models. See Calling Scripts Located on a Web Page From TestComplete Scripts.

DelphiScript does not support the Set Next Statement command of the script debugger (see Setting Next Statement for Execution in TestComplete help).

JScript, C++Script and C#Script

C++Script and C#Script are based on JScript, so all of these languages have the same peculiarities of usage:

JScript, C++Script and C#Script do not support functions that obtain parameters by reference.

In TestComplete script units can refer to each other, so you can call routines and variables defined in one unit from another unit. JScript, C++Script and C#Script do not support circular references between units.

JScript, C++Script and C#Script may handle exceptions incorrectly when the try{} block contains calls to routines defined in other units. That is, the try... catch... finally block works correctly only when it does not contain calls to routines from other units.

In TestComplete, when a routine is called from another script unit, the caller property of the Function object that corresponds to the current routine returns null. Normally, when a function is called by another routine declared in the same script unit, the caller property returns a reference to the function that invoked the current function. If the caller property is used in a string context, it contains the text of the function that called the current routine. For more information on the Function object and its caller property, see the MSDN Library (the on-line version is available at http://msdn.microsoft.com).

To debug JScript, C++Script and C#Script code, you may need to modify Internet Explorer's options. Also, if you work under a user account (not an administrator account), you may need permissions for the Machine Debug Manager's system component. For more information, see Debugging Tests in TestComplete help.

The format of arrays created by the JScript engine differs from arrays created in VBScript or DelphiScript. The arrays in JScript, C++Script and C#Script are objects, while arrays created in


106

http://msdn.microsoft.com/


VBScript and DelphiScript are Variant values. This difference limits the use of some routines (for instance, the Find and FindAll methods) in JScript, C++Script and C#Script code. In order to use a JScript array with these routines, you need to convert the array to the format adopted in VBScript and DelphiScript. Below is a typical conversion routine:

[JScript]

function ConvertJScriptArray(JScriptArray){ // Uses the Dictionary object to convert JScript array var objDict = Sys.OleObject("Scripting.Dictionary"); objDict.RemoveAll(); for (var i in JScriptArray) objDict.Add(i, JScriptArray[i]); return objDict.Items();}


function ConvertJScriptArray(JScriptArray){ // Uses the Dictionary object to convert JScript array var objDict = Sys["OleObject"]("Scripting.Dictionary"); objDict["RemoveAll"](); for (var i in JScriptArray) objDict["Add"](i, JScriptArray[i]); return objDict["Items"]();}

Variables that are declared with the var statement within a function are only visible within this function. Variables that are used without declaring them with var, become global variables. This behavior may cause hidden influence of functions onto other functions. For instance, the execution of the following code never ends:


function ChildFunc(){ for(i = 0; i < 5; i++) …} function ParentFunc(){ for(i = 0; i < 10; i++) ChildFunc();}

This happens because after a call to ChildFunc, the i variable is always 5 and never 10, so the loop within the ParentFunc function becomes an infinite loop.

When a variable goes out of scope, it is released. However, if the variable held a reference to an object, the JScript engine does not release this object until the entire script run is over. This happens because the JScript engine cleans up memory and references at a certain point and not when a variable is destroyed or you set it to null.


107

Introduction

This restriction may cause problems when working with certain program objects and COM servers. Suppose you have the following code:


function Foo(){ Obj = new ActiveXObject("MyCOMObject.MyCOMObject"); … Obj = null;}

function MainFoo(){ … Foo(); // MyCOMObject still exists …}

In this example, MyCOMObject exists after a call to Foo. Assigning null to the Obj variable marks it as a candidate for releasing, but the object still exists in memory. To force the releasing of all such objects and variables, call JScript’s CollectGarbage method:


function Foo(){ Obj = new ActiveXObject("MyCOMObject.Application"); … Obj = null; CollectGarbage(); }

The described JScript peculiarity may cause a problem with creating virtual users when performing load tests. For more information on this, see Creating Load Tests in Scripts in TestComplete help.

Due to certain peculiarities of the JScript engine, the instanceof operator returns an incorrect value if the checked objects are passed between script units. Suppose you have the following code:


function fooA(){ try { throw new Error(10,"This is an error."); // Simulates exception } catch(err) { var res = err instanceof Error; Log.Message("fooA: err instanceof Error = " + r); fooB(err); }} function fooB(err)


108


{ var res = err instanceof Error; Log.Message("fooB: err instanceof Error = " + res); }

If both fooA and fooB reside in the same script unit, in both functions the res variable will be true. If you place fooB to another unit, then the res variable in fooA will be true, and the res variable in fooB will be false.

The OnStopTest event is not generated if the script written in JScript, C++Script or C#Script stops upon an unhandled exception.


109

Introduction

Index

A

Additional information about TestComplete......11Analyzing......................................................42, 60

Recorded test...................................................42Test results.......................................................60

Application controls and objects.........................76Addressing in tests...........................................76

AQCommunity....................................................11Arrays................................................................107

in JScript, C++Script and C#Script...............107

C

C#Script......................................................90, 107Peculiarities of usage.....................................107Selecting the scripting language......................90

C++Script....................................................90, 107Peculiarities of usage.....................................107Selecting the scripting language......................90

Calling...............................................................102Project items in scripts.....................................91Routines declared in another unit..................102Variables and constants declared in another unit

....................................................................102Checkpoints........................................................17

About...............................................................17Community site...................................................11Controls

Addressing in tests...........................................76Recognizing windows and controls.................76

Creating a test project.........................................22Custom keyword test operations.........................87

D

DebuggingKeyword tests..................................................87

DelphiScript................................................90, 107Peculiarities of usage.....................................107Selecting the scripting language......................90

Difference between various TestComplete editions...............................................................5

E

Enterprise edition of TestComplete......................5Errors..................................................................68

Searching for the reason of errors....................68

F

FAQ....................................................................11Frequently asked questions.................................11

G

Getting started with TestComplete.....................13Getting Support...................................................11

H

How to...............................................................102Calling routines declared in another unit.......102Calling variables and constants declared in

another unit.................................................102

J

JScript.........................................................90, 107Peculiarities of usage.....................................107Selecting the scripting language......................90

K

Keyword Tests....................................................80Creating...........................................................82Debugging.......................................................87Editing.............................................................82Operation parameters.......................................83Operation results..............................................83Operations........................................................83Overview.........................................................80Parameters.......................................................86Running...........................................................85Variables..........................................................86

L

Languages...................................................90, 107Comparing features of scripting languages.....90


110

Index

Peculiarities of usage.....................................107Selecting the scripting language......................90

Log......................................................................18

N

Naming controls..................................................76Naming objects...................................................76Naming processes...............................................71Naming web objects............................................79Naming windows................................................72Newsgroups about TestComplete.......................11

O

Overview...............................................................5

P

ProcessesRecognition of.................................................71

Project items.......................................................14Projects

Creating...........................................................22

R

RecognizingProcesses, windows and controls.....................70

Recording Tests..................................................37Resources............................................................11Results.................................................................60

Analyzing.........................................................60Running the test..................................................59

S

Scripting..............................................................88Comparing features of scripting languages.....90Overview.........................................................88Quick start........................................................91Scripting languages..........................................90Supported languages – Peculiarities of usage107

Scripting languages.....................................90, 107Comparing features of scripting languages.....90Peculiarities of usage.....................................107Selecting the scripting language......................90

ScriptsAbout writing scripts.......................................88

Quick start........................................................91Writing scripts – Quick start............................91

Standard edition of TestComplete........................5Support................................................................11Supported development tools..............................10System requirements.............................................8

T

Technical support................................................11Test Items............................................................16Test Log..............................................................18Test results..........................................................60

Analyzing.........................................................60TestComplete

Community site................................................11Difference between Standard and Enterprise

editions...........................................................5FAQ.................................................................11Getting started..................................................13Newsgroups.....................................................11Overview.....................................................5, 13Projects and project items................................14Supported development tools..........................10System requirements..........................................8Technical support............................................11

Tested applications.............................................24Defining applications to test............................24

Tests....................................................................35Analyzing recorded test...................................42Planning...........................................................35Recognition of processes and windows...........70Recording.........................................................37Running.....................................................59, 85

U

uses statement – About.....................................102

V

VBScript.....................................................90, 107Peculiarities of usage.....................................107Selecting the scripting language......................90

W

WindowsRecognition of.................................................72


111