Creating Event Handlers for TestComplete Events

Applies to TestComplete 15.47, last modified on January 20, 2023

This topic provides step-by-step instructions on creating event handlers for events of TestComplete engine.

1. Add an Event Control to Your Project

In order for TestComplete to be able to handle events, you need to add the Events project item and an Event control to your test project.

The Events project item is included in a new project by default. It contains an Event control named GeneralEvents. You can use this control to handle TestComplete events. So, if your test project contains the Events | GeneralEvents node, you can proceed with the next step.

If by some reason your project does not contain the Events project item or an Event control, you should add them to the project. To do this, right-click your project node in the Project Explorer panel and select Events in the subsequent Create Project Item dialog. TestComplete will add the Events project item and the GeneralEvents control to your project:

2. Add Needed Events to the Event Control

After you added an Event control to your project, you have to specify the events the control will handle. To do this:

  1. Double-click the Event control (GeneralEvents) in the Project Explorer. This will open the Event Control editor in the Workspace panel.

  2. In the editor, specify TestComplete general events in the Source object edit box that is at the top. You can choose this value from the drop-down list of this edit box.

  3. The Available Events list on the left contains the events that can be handled by the control. The events are organized into categories. Expand the category nodes to find the desired event in the list.

    Tip: Frequently used events like OnUnexpectedWindow or OnLogError belong to the General Events category.

    After you found the desired event, select it in this list and drag it to the Events to Handle list on the right:

    An Event control can handle multiple events from several sources. You can add events from different sources to the control by specifying the sources in the “Source object” box and dragging the desired events to the “Events to Handle” list. For complete information on specifying events to be handled, see Adding Events to Event Controls.

3. Create an Event Handler

After you included the desired event to the Events to Handle list, you can create an event handler for it:

  1. In the Events to Handle list, select the desired event and click the New button in the Event Handler cell or simply double-click the event. TestComplete will display the New Event Handler dialog.

  2. In the dialog, specify either the name of the event handling routine and the unit that will hold this routine or the name of the event handling keyword test; then click OK.
    The New Event Handler Dialog

    TestComplete will create an event handler and display it in the Code Editor, if you specified a script routine, or in the Keyword Test editor, if you specified a keyword test as the event handler.

  3. After you created the event handler, select File | Save All from the TestComplete main menu to save the changes.

Depending on the test type you chose, you will see a script editor or a keyword-test editor with the created event handler script or test. Now you can create event handling commands. For information on common operations with error handlers, see Typical Event Handler Tasks.

Note on Using Event Handler Parameters

Script Handlers

To access handler parameters in script routines, simply call them by name:

JavaScript, JScript

function GeneralEvents_OnUnexpectedWindow(Sender, LogParams)
 {
  // This routine changes log message text
  LogParams.MessageText = "The message from the event handler";
 }

Python

def GeneralEvents_OnUnexpectedWindow(Sender, LogParams):
  # This routine changes log message text
  LogParams.MessageText = "The message from the event handler"

VBScript

Sub GeneralEvents_OnUnexpectedWindow(Sender, LogParams)
  ' This routine changes log message text
  LogParams.MessageText = "The message from the event handler"
End Sub

DelphiScript

function GeneralEvents_OnUnexpectedWindow(Sender, LogParams);
begin
  // This routine changes log message text
  LogParams.MessageText := 'The message from the event handler';
end;

C++Script, C#Script

function GeneralEvents_OnUnexpectedWindow(Sender, LogParams)
{
  // This routine changes log message text
  LogParams[MessageText] = "The message from the event handler";
}

Keyword-Test Handlers

You can see the handler parameter on the Parameters tab of the keyword-test editor:

Automated testing with TestComplete: Keyword-test event handler parameters

In scripts, you can access them through the Parameters collection:

KeywordsTests.YourTestName.Parameters.ParameterName

You should use this collection if you access the parameters as a code expression in your keyword test:

Automated testing with TestComplete: Setting operation parameters using a code expression

A possible alternative is to use the Test Parameter mode:

Automated testing with TestComplete: Setting operation parameters using a test parameter

For more information on this, see Keyword Test Parameters and Specifying Operation Parameters.

Note on Handling Events of External ActiveX Objects

TestComplete can handle events that occur in ActiveX objects that reside in any application running in the operating system. In order for TestComplete to be able to handle events of these ActiveX objects, you need to attach your Event control to these objects during the test run. To do this, call the EventControl.AttachTo method. If the object is not attached to the Event control, the latter does not receive event notifications, and event handlers are not run.

At the end of the test run, detach the Event control from the objects by calling the EventControl.DetachFrom method.

Note: It is recommended to always detach from objects before the test gets completed.

For more information on attaching and detaching Event controls, see Creating Event Handlers for External COM Objects.

See Also

Handling Events - Overview
Typical Event Handler Tasks
Creating Event Handlers for External COM Objects
Creating Event Handlers in TestComplete

Highlight search results