HPE Software is now Micro Focus
HPE Software is now Micro Focus
LoadRunner and Performance Center

A closer look at TruClient Event Handlers

A closer look at TruClient Event Handlers


What are Event Handlers and why do we need them?

(This post was written by Michal Barak, from the TruClient R&D Team)

Event Handlers are a script entity that empowers the script developer to handle an application behavior that appears in an unexpected or unpredicted phase. The most common example is a survey that could pop up sometimes—for some of the users.  (It is not a constant thing; rather a random occurrence.) A user might react by either filling out the survey or by dismissing it …but how would a Virtual User react?

One approach to answering this question (but not a clean one) is to perform a check before every step in your script to discover if the survey appears, and handle it. This is where, by using TruClientsEvent Handler feature, the scripter can handle such situations more smoothly. All that is needed is to define the “Event” you wish to address and the “Handler” that is to be triggered once the event occurs. In the previous survey example, the “Event” is the survey pop up window, and the “Handler” can be closing the survey window allowing the script to continue running.

The “Event” may be an appearance of a UI element or a dialog.
The “Handler” is a TruClient function that defines the relevant step(s) for handling the event.  
Experience TruClient within Hewlett Packard Enterprise LoadRunner software for yourself here.

A robust automatic script, is one that will handle errors or different paths in the application flow.
Event Handlers enables the scripter to handle deviations from the main path of the business process flow and to return back to it in a smooth way.

Another example, could be during the business process login to the application. Instead of the expected login process, the user gets a notification saying: “Server is busy. Please wait for 10 seconds and try again”.
The scripter has two options:

(a)  Ignore it. Replay the script and get “Object Not Found” on the step that is right after the login and the script will fail.
(b)  Add an event handler that waits for ten seconds by using a “Wait” function and then attempt to login again. Then continue with the original flow.

Clearly the second approach is the preferred one.

Five Steps to Create an Event Handler:

As mentioned earlier, there are two types of TruClient Event Handlers: Object Event Handler and Dialog Event Handler.

  • The Object Event Handler is used when an object-related event occurs (e.g. A certain object appears on the page, A certain object property gets a certain value).
  • The Dialog Event Handler is used when a dialog pops up. (e.g. Alert, Prompt)

 The following steps cover a typical Event Handler use case and demonstrates, step-by-step, and how to define it within TruClient:

In our example, while executing the business process steps, every now and then a message pops up asking you to sign up. The message appears at unexpected intervals while performing the business process steps. This is a typical case to demonstrate TruClient Event Handlers.

 1) Open the Event Handler Editor from the main toolbar:


2) Click on the "+" button to add a new Event Handler.
Although a new handler is created you still need to fill more information. Until this is done, an error mark will appear next to the handler name.
As shown in following screenshot, In the General section, one should fill out the options regarding the handler scope. In our example, as the message could appear more than once and in any point during the business process, we will choose the “Event can be triggered during the entire script” option.

Note: if possible, it is recommended to pin-point the scope for the Event Handler so to reduce the amount of checks TruClient performs during runtime.

Our handler type is an “Object” type as the message appears within a regular DOM object and not within a browser dialog.

3) Click on the “Click to choose an object” and highlight a “meaningful” object that is part from the message. In our example the “SIGN ME UP!” button was selected.
After you choose the object you can see that TruClient has “recorded” the object and has created an identification for it, as shown in the following screenshot:


4) The Event Type is “Object Exists”. This means that if TruClient identifies the object that is defined in the Object section it triggers the Handler.
During script replay, TruClient will search for this object after each step execution.
Alternatively, there is another option for Event Type “Property exists on Object”.
You can define the property value and a condition that should be met.

This concludes the Event definition part.

5) The final element to be defined is the Handler.
The Handler is a function that contains steps which should be executed once the defined object appears. In our example, the goal is to ignore and close the message.

If a new Handler needs to be defined, to create the function, temporarily close the Event Handler Editor. Once the function is defined we will reopen this Editor and associate it as our Handler for this Event.

 Create the function:

  •  Start recording and close the message:


  • TruClient recorded a navigation step and the close step. We are only interested in the close step. Stop the recording.

  • Create a function from the close step. 
    Select the step, right click to open the context menu and select “Group Into” --> “New Function”


  • The “Create new function” dialog appears.
    Type a function name, a library name (new or existing) and uncheck the option “Replace steps with function call” so the script itself will not activate this function, but the Event Handler will do so…


  • Now we have a new function that contains a single step that closes the message.
    You can see this function listed in the “Function Libraries” section.

Now let’s go back to the Event Handler Editor and choose the function as the handler.
You can now see that the error icon next to the handler name has disappeared.

Now the Handler is part of the script.
You can record the business process as usual, ignoring the message and knowing that the handler will close it every time it appears during script replay.
Note that if you encounter the unexpected behavior during recording make sure to delete associated steps since the Event Handler is supposed to handle it.

In a similar way you can define an Event Handler for Dialog.
When Dialog is selected, there is no need to choose a UI object. In a Dialog Event Handler TruClient listens to any browser dialog that pops-up and triggers the function defined in the Handler.
Usually, this function will simply close the dialog as shown in the following examples:

As shown, using Event Handlers is a powerful tool for handling unexpected cases and making a TruClient script more robust. It can address both unexpected browser dialogs or unexpected application windows or UI elements. TruClient evaluates the event condition at the end of each step execution and triggers the handler to “recover” from the unexpected state allowing the script to continue to run.

You can try Event Handlers for yourself by beginning your trial to Hewlett Packard Enterprise LoadRunner.

Thanks to Michal for providing this great article! 

  • Load Testing
About the Author


Yudit is the Functional Architect for HPE LoadRunner, a product that is a core part of HPEs Software Performance Validation Suite.


Please tell me how to work with dialogue event handler. In my application dialogue-authentication window is coming. Thanks in advance

Frequent Contributor.

Hey  yuditb ,  I have a question on trueclient. Recently , for a js page , we recorded and run the test using LR VuGen True Client 11.0 IE. Now the same page when we tried to record with VuGen 12.5 TrueClient with IE  .. it is not able to detect and record .. I can see that the it showing as non-standard mode.. can you let me know what could be the problem in this? Do 12.5 TC required any setiings to detect ? 

Micro Focus Expert
Hi Janardhana, in most cases authentication dialogue appears right after navigation step in a predictable phase. I do not think and Event Handler is required. If you still do not know when it will triggered you can implement like explained for alert or confirm box just instead of having the Dialog Alert step you need to place a Dialog Authentication step.
Micro Focus Expert
Hi loadpractices, your comment is irrelevant to this post. I suggest you raise it in the support forum. Please include screenshot of the real IE browser devtools while in focus on Emulation tab when the application is opened. Thanks, Shlomi
Trusted Contributor.

A very detailed and helpful post. Thanks a lot Barak and Yudtib. Great job !! Keep generating more :)