Event handlers

This section describes events handlers, and how to use them to manage unexpected or unpredicted events that can occur during script replay.

Event handler overview

You use event handlers to help your test recover smoothly from behavior of the application that either:

  • Does not occur in every run. For example, during logon, the user sometimes gets a notification: “Server is busy. Please wait for 10 seconds and try again”.

  • Occurs at unpredictable times. For example, the application displays a survey popup at random times.

If you record or add a step to handle such behavior, your script may fail when the behavior does not occur. If there is no step to handle it, the script may fail when the behavior does occur. An event handler calls a function to handle a condition only if the condition occurs.

You can create an event handler for these events:

  • Object Event - Used when an object-related event occurs. For example, a certain object appears on the page, or a certain object property gets a certain value.

  • Dialog Event - Used when a dialog box pops up. For example, an alert or a prompt.

Back to top

Create an event handler

To create an event handler:

  1. Click the Event Handler Editor button in the main toolbar.
  2. Click the button in the editor to add a new event handler.

    An error icon is displayed next to the handler name until enough information is added to define the handler.

  3. Enter the properties of the event handler.

    If a function that handles this event does not exist, close the Event Handler Editor and create the function. See TruClient functions and function libraries. After creating the function, reopen the editor and select the library and the function.

Back to top

Event Handler Editor

The Event Handler Editor dialog box enables you to define events handlers and their properties.

UI Element Description
Event Handlers Pane

Add Event Handler. Add an event to the event handler.

Delete Event Handler. Delete an event from the event handler.

  • Name. Enter a name for your event handler and click Apply.
  • Execute only once. Executes the event handler only once during the current iteration (it resets to zero when the iteration ends).
  • Allow other handlers to interrupt. Select the check box to enable other event handlers to run during the run of this event.
  • Select Event can be triggered during the entire script to allow TruClient to listen for the event throughout the test run and call the event handler whenever the event occurs.

    Clear Event can be triggered during the entire script to allow TruClient to listen for the event during only part of the run. If you clear this box, the Start Step and End Step fields are displayed so you can specify the range of steps where the event can be triggered.

Type. You can select either Object or Dialog.


(Displayed only if you select Type= Object)

Choose an object. Select the object from your application that will trigger the event handler.

After you select an object, the following options are displayed:

  • Roles. The roles determine which operations can be done on the object. For example, an “element” role has operations like “click” and “mouse over". The “textbox” role also has a “type” operation. For details, see TruClient object roles.

  • Name. The name of the object.
  • ID Method. For explanations of the ID Method options, see Object identification.

    Select one:

  • Related objects. Enables you to associate your object with another object in your application to facilitate object identification during replay. See Relate an object to other objects.


Type: For an Object Event, select one of the following:

  • Object Exists. If object exists during replay, the event handler is triggered.
  • Property exists on Object. If the property of an object meets the defined criteria, the event handler is triggered.

For a Dialog Event, the event is Dialog opened. When the specified dialog box is opened, the event handler is triggered.


The handler function must be in a library.

  • Library. Enables you to select the library containing the function.
  • Function. Enables you to select the function.
  • Arguments. If the selected Function has function parameters, this field is displayed. Enter the argument values.

Back to top

See also: