HP LoadRunner 11.0X and BPM Citrix Agent

Describe the HP LoadRunner Citrix Agent -- what does it do, and where to find it.

The LoadRunner Citrix Agent is a utility application provided with LoadRunner ; the "agent" executes on all Citrix server machine hosting the Citrix Application Under Test (AUT), and greatly enhances VuGen's capabilities in identifying Citrix client objects.


The agent is not required for LoadRunner Citrix VUser scripts, however, HP strongly recommends it is installed as it's use makes for a much more robust load test and load test development is simplified.


The LoadRunner Citrix Agent, provides enhancements in the following areas:


Object Class Information : During recording, VuGen uses the agent to generate "object level" information about the active object, creating ctrx_obj_xxx functions for all of the mouse actions, such as click, double-click and release.

Expanded Snapshot Interactivity : The agent installation allows you to determine which objects in the client window are detected by VuGen.

Retrieving Text : With the agent installed, VuGen lets you save standard text to a buffer.

In-built Synchronization:  The agent provides in-built synchronization at the "object" level, making the script much more easy to develop and test.

DEP Messaging : Microsoft's Data Execution Prevention status is displayed in the recording and replay log relating to the status of DEP on the Citrix Server, since if DEP is enabled, the agent will have issues trapping text.

ctrxAgent.exe is launched on the Citrix server automatically when a Citrix session is created by LoadRunner during recording or replaying, and it stops automactically when the session is ended.  As well, when used in a LoadRunner scenario load test, the agent only runs when the Citrix VUser script runs.


The HP LoadRunner Citrix Agent is found in the "additional components" folder of the LoadRunner product media.  Starting with LoadRunner 9.51, 64-bit Windows is supported for the agent Citrix host OS.  Install the 32 or 64-bit installer depending on if the Citrix server OS is 32 or 64 bit.


The agent should be installed on all Windows Citrix Servers in a Citrix enterprise (Citrix "Farm") hosting the Citrix application under test.


To expand on the above points, with the use of the LoadRunner Citrix Agent we can:


Record and replay ctrx_obj_mouse_click API calls instead of ctrx_mouse_click API calls. The ctrx_obj_mouse_click() script API not only uses x, y coordinates to make the click but it also uses extended information/properties from a certain window/control - its GUI state and content in order to make the mouse click more accurate.


Record and replay ctrx_obj_get_info API calls which get extended information/properties (window's GUI state or window's content) from a certain window/control. This can help to make Citrix script logic more reliable. 


Record and replay ctrx_sync_on_obj_info calls which synchronize on a certain window/control properties (window's GUI state or window's content). This can help to make Citrix script synchronization more robust.


Record and replay ctrx_get_text API calls which trap text from a certain window. This can help to make Citrix script logic more reliable.


Record and replay ctrx_sync_on_text calls which synchronize on a certain window/control displayed text. This can help to make Citrix script synchronization more robust.


How the LoadRunner Citrix Agent works?


- The HP LR Citrix Agent adds test getting/syncing (reading and syncing with text) and other things – if text getting/syncing isn’t required, or using the object-level VuGen Citrix functions is not required, our agent is not required to be used in the LoadRunner Citrix Protocol.


- The LR Citrix Agent adds not only text syncing/getting functions, but also ctrx_obj_* family of function, which allows access to extended description of objects.  Please review the online function reference in VuGen for more information on the calls we have designed to work with the Citrix Agent.


In the below discussion, we should distinguish the differences between the client side (Vugen side, Load Generator side) and server side (Citrix Server Side where the LR Agent is installed) regarding the Citrix protocol.   


- At the client side in single protocol Citrix ICA VUsers wherein only the ICA protocol is used, we use only public Citrix APIs (ICO/ICA APIs) – however in multi-protocol Web+ICA VUsers (Citrix Web Interface, previously known as “NFuse”) VUsers, our product uses web hooks during recording (only during the web part of the business process) to instrument and monitor IE during recording.  Web hooking usually tricks anti-virus and security software into thinking our recording hooking is a risk, so this should be considered.  This is the same web hooking our Web protocols use.


- Our LR Citrix Agent (client to server communication) uses Citrix RDP “Virtual Channels” as part of it’s implementation communicating with the client-side.   A Citrix virtual channel is a bi-directional error-free connection used for the exchange of generalized packet data between a Citrix host for online delivery (XenApp) and the Citrix client/plug-in. For example: sound, graphics, client drive mapping, and printing are just a few of the virtual channels used by Citrix.


- There is no additional HP information about details and ports for Virtual Channels, as it’s a Citrix feature, and we use only the Citrix Virtual-Channels public API .


-  Our LR Citrix Agent is implemented as a device driver in the Citrix Server where during recording, replay or a loadtest when in order to get extended information about a published Citrix application, we inject DLLs in to processes; therefore, Microsoft DEP should be fully disabled on server.   Because we must use DLL-injection techniques with our LR Citrix Agent implementation, not only DEP but AntiVirus and security software may falsely think our agent activity/interaction is a risk.   Due to this -- on the Citrix server side, our agent’s interaction with the Citrix published application is considered invasive.


- The HP LR Citrix Agent driver/process starts with every Citrix session created on server (process name is ctrxAgent.exe) -- but if it doesn’t see any incoming Virtual Channel connections (indicating it is a session associated with the Lr Citrix protocol) it simply stops itself -- therefore,  by design, our LR Citrix agent is prevented to continue to run unless it is a session requiring it for our ICA protocol (this prevents the agent from running on any Citrix/RDP session).   Connecting remotely to a Citrix server with our agent using RDP/remote desktop, should not result in the ctrxAgent.exe running continuously; however, recording or replaying or load testing using the Citrix protocol will due to the aforementioned.


- Regarding the installation of our LR Citrix agent specific to W2K/R2 -- there could be some issues with driver signing in W2K8/R2, wherein the agent may install without error (with DEP disabled) but the agent may not work properly.  If that is the case please contact HP software support.


- When running, the LR Citrix agent “footprint” is minimal.


- You need to have the LR Citrix Agent(s) patched to the latest patch applicable to the LoadRunner version being used.  For example, as of the date of this KB, with LR 11.04, you need to have the Citrix Agent 11 Patch 2 (Patch 2 is the latest patch for LR 11 Patch 4).




Have more questions? Submit a request


Article is closed for comments.