Handling Events - Overview

About Events and Event Handling

Supported Events

Event Handler Types

Event Control Modules

Creating Event Handlers

Using Event Controls Outside of TestComplete

Sample

Requirements

Notes

An event is a specific action that occurs during the test run. This can be an action that occurs in TestComplete or in some other application. An example of an event that may occur quite often when testing desktop applications is the appearance of an unexpected window during the test execution.

With TestComplete you can create a script routine or keyword test that will be executed when an event occurs. This script or keyword test is called an event handler. It can perform specific operations you would like to do in response to the event. For instance, an event handler can post a desktop image or an image of your tested application’s window to the test log.

TestComplete handles events only during test runs. Event handlers are not called when TestComplete is working in recording or design mode.

To handle events in TestComplete, you use the Events project item and Event controls. A project can contain several Event controls, and the Events project item serves as a collection of these controls:

An Event control stores a collection of events to be handled. We use the term control as it is registered in the operating system as an ActiveX object (control) and can be used for creating event handlers outside of TestComplete (see below). By default, the Events item contains one Event control, GeneralControl. This control contains some of the available TestComplete events.

The Event controls can handle the following events:

• Events that occur in TestComplete projects during the test run. Typical events of this type are events that occur when something unexpected happens during the test, when an error or informative message is posted to the test log, or events that occur on start and stop of a test item. For complete information, see TestComplete Events.

• Events of ActiveX controls and COM objects that implement the IDispatch interface. For example, if the tested application is a COM server, you can create event handlers for its events.

Events of User Form components are handled in the UserForm and ActiveX Object editors. That is, there is no need to use Event controls to handle them. These events can be triggered by user actions on the components or by the components’ properties changes.

• If you run tests in TestComplete or TestExecute, an event handler can be either a script routine, or a keyword test.

  The number of the routine’s (or test’s) parameters must match the number of an event’s parameters. If you want to call a test with some other parameters in a response to the event, call it from the even-handling routine (test). The same concerns calling tests of other types, for instance, low-level procedures: call them from the event-handling script routine or keyword test.

• You can place an event handler in any other application that can handle events of ActiveX objects, for instance, in a C#, Visual C++ or Visual Basic application. This feature lets you, for instance, handle TestComplete events in your Connected Application.

  Connected and self-testing applications are deprecated. We do not recommend using them.

The functionality of each Event control is implemented by two modules:

• tcEventControl.ocx - This module holds the binary code of the control. It is located in the <TestComplete>\Bin\Extensions folder.

• <EventControlName>.tlb - This is the type library that describes events used in the project. The library’s location depends on the “Unregister the type library when the project is closed” setting. When this setting is enabled (default) the type library resides in a temporary folder and it is removed when you close the project. If the setting is disabled, the library is located in the folder holding the Events project item file (by default, <Project Folder>\Events).

You need to deactivate the “Unregister the type library when the project is closed” setting if you want to use the control (create event handlers) when your TestComplete project is closed. If the setting is enabled, then your Event control is available only when your project is opened in TestComplete. See Using Event Controls Outside of TestComplete below.

The way you create event handlers depends on whether the event handler will be located in your TestComplete project, or in an external application. A typical procedure includes the following steps:

1. Add the Events project item to your TestComplete project and add an Event control to the Events project item.

2. Open the Event control editor and specify the event source (TestComplete, external ActiveX object and so on). Then specify the events to be handled with the control.

3. If you are going to use a script routine or a keyword test as an event handler, then in the editor you can also associate the routine or test with the desired events.

4. Create event handler code (or add operations to the keyword test).

For detailed instructions, see the following sections:

Event controls are ActiveX controls. They are registered in the operating system and can be used in any application that supports working with ActiveX controls. For instance, you can add this control to some form in your application and use it to handle a TestComplete event from within the application.

You can have several test projects and each of them can use its own Event control or controls, so there can be lots of Event controls (ActiveX objects) registered in the operating system. TestComplete includes the “Unregister the type library when the project is closed” setting that lets you manage the Event control registration. When this setting is enabled, the controls are registered only when your project is opened in TestComplete. If the setting is disabled, the controls are registered permanently - TestComplete registers them when the project is opened and they remain registered after you close the project.

To decrease the number of ActiveX controls registered in the system, the setting is enabled (by default) and Event controls are available only when their test project is open. You need to disable the setting if you want to use Event controls (create event handlers) when your test project is not open in TestComplete. To view or change the setting, select Tools | Options from the TestComplete main menu and, in the subsequent Options dialog, choose Engines | Events from the tree on the left.

For more information on using Event controls from external applications, see the topics of the Creating Event Handlers in Connected Applications section.

TestComplete includes a sample project that demonstrates using the Events project item:

<TestComplete Samples>\Common\Event Handling\Scripts

The functionality of the Events project item is implemented by the following extensions:

• Events Project Item
• Events Project Item Editor

They are part of the TestComplete distribution. They are installed and active by default. You can check if these extensions are active by selecting File | Install Extensions from the TestComplete main menu. If some extensions are not available, re-install TestComplete. For more information about changing installed TestComplete features, see Installing Extensions.

You cannot run the network suite, jobs and tasks from event handlers.

In addition, do not call the NetworkSuite.Synchronize method from the event handlers. The method will not perform synchronization.