Citrix agent

The Citrix agent is an optional utility that you can install on machines that deliver Citrix applications. It enables enhanced functionality when developing Citrix scripts in VuGen.

Citrix agent installation

The Citrix agent is provided in the LoadRunner Professional installation package. To use the Citrix agent, you install it on all machines that deliver the Citrix application, including the Citrix server and remote machines as relevant. For installation instructions, see Install the Citrix agent (optional).

You can install the Citrix agent on any supported Citrix server. For details on supported Citrix server versions, see Supported Protocols.

Note: The Citrix agent is not supported when working with a Citrix cloud environment, using services installed on Microsoft Azure.

Back to top

Object detail recording

If the Citrix agent is installed on the Citrix machine, then when you record a Citrix script, VuGen records specific information about the active object in addition to general information about the action. When the agent is installed, the relevant step name includes "Obj" to indicate the additional object description: for example, VuGen generates Obj Mouse Click and Obj Mouse Double Click steps instead of the Mouse Click and Mouse Double Click that it generates without the agent.

An "Obj" step contains a corresponding function that includes the object description. The names of these functions have the format of ctrx_obj_xxx, and they are parallel to the ctrx_xxx functions recorded without the agent. The following table lists the functions with object descriptions recorded with the agent, and the parallel functions recorded without the agent. For details on these functions, see Citrix ICA Vuser Functions (CTRX) in the Function Reference.

Function recorded with agent Function recorded without agent
ctrx_obj_mouse_click ctrx_mouse_click
ctrx_obj_mouse_double_click ctrx_mouse_double_click
ctrx_obj_mouse_down ctrx_mouse_down
ctrx_obj_mouse_move ctrx_mouse_move
ctrx_obj_mouse_up ctrx_mouse_up

Example

The following example shows the same mouse-click action recorded with and without the agent installation. 

/* Without Agent Installation */
ctrx_mouse_click(573, 61, LEFT_BUTTON, 0, test3.txt - Notepad);
/* With Agent Installation */
ctrx_obj_mouse_click("<text=test3.txt - Notepad class=Notepad>" 573, 
         61, LEFT_BUTTON, 0, test3.txt - Notepad=snapshot21, CTRX_LAST);

In the example above, the first argument of the ctrx_obj_mouse_click function contains the text of the window's title and the class, Notepad. Note that although the agent provides additional information about each object, Vusers only access objects by their window name and the object coordinates.

Back to top

Active object recognition

The Citrix agent lets you see which objects VuGen detects in the client window. This includes all Windows Basic Objects such as edit boxes, buttons, and item lists in the current window.

You can see the detected objects in snapshots generated by VuGen. To view a snapshot, in the Step Navigator, double-click a step that contains a reference to a snapshot. (In the Step Navigator, each step that contains a snapshot displays a Snapshot icon .) To see the detected objects in the snapshot, you move your mouse through the snapshot, and VuGen highlights the borders of the detected objects as the mouse passes over them.

In the following example, the Save button is one of the detected objects.

When the Citrix agent is installed, you can insert functions interactively from within a snapshot, by utilizing VuGen's ability to detect objects. For details, see Insert a function interactively. Also, when you right-click within a snapshot, you can use additional agent-only interactive commands. For details, see Additional interactive commands.

Back to top

Insert a function interactively

When the Citrix agent is installed, you can insert functions interactively from within a snapshot, by utilizing VuGen's ability to detect objects.

To insert a function interactively:

  1. In VuGen, select a step in the Step Navigator. The new step will be inserted after the selected step. Make sure that a snapshot is visible.

  2. Click within the snapshot.

  3. Mark the relevant object or area in the snapshot, as follows:

    Mark a bitmap Other commands

    To mark a bitmap:

    1. Right-click the bitmap and choose Insert Sync on Bitmap from the right-click menu.
    2. Mark the relevant area.
    3. Click OK in the Sync on Bitmap dialog box. VuGen inserts the step into the script after the currently selected step.

    For all other commands:

    1. Move your mouse over snapshot objects to determine which items are active—VuGen highlights the borders of active objects as the mouse passes over them.

    2. When the object is highlighted, right-click and select one of the Insert commands. A dialog box opens with the step's properties.

    3. Set the properties as needed and click OK. VuGen inserts the step into your script.

Back to top

Additional interactive commands

When you click within a snapshot, you can insert several functions into the script using the right-click menu. If the Citrix agent is installed on the Citrix machine, several additional options are available from the right-click menu of the Citrix window in focus.

These commands insert related functions into the script. These functions are available only when the Citrix agent is installed.

Right-click command Details Related agent-only functions
Insert Obj Get Info Retrieves the current state of any object property: ENABLED, FOCUSED, VISIBLE, TEXT, CHECKED, and LINES. ctrx_<obj>_get_info
Insert Sync on Obj Info Instructs VuGen to wait for a certain state before continuing. ctrx_sync_on_obj_info
Get Text For details, see Text retrieval. ctrx_get_text
Insert Sync on Text ctrx_sync_on_text

These commands are interactive—when you insert them into the script, you are prompted to mark the object or text area in the snapshot.

In the following example, the ctrx_sync_on_obj_info function provides synchronization by waiting for the Font dialog box to come into focus. 

ctrx_sync_on_obj_info("Font", 31, 59, FOCUSED, "TRUE", CTRX_LAST);

Back to top

Text retrieval

With the Citrix agent installed, VuGen lets you save standard text to a buffer. Note that VuGen can only save true text—not a graphical representation of text in the form of an image.

You save the text using the Get Text step after recording.

For details, see Citrix manual synchronization.

When the Citrix agent is not installed, you can use functions that utilize OCR for text retrieval. These functions can be inserted during and after recording. Note that OCR might consume a substantial amount of the hardware resources for the load generator machine.

The following table lists the text-related functions available with the agent, and the parallel functions available without the agent. For details on a function, click the name of the function.

Function with agent Function without agent
ctrx_get_text ctrx_get_text_ocr
ctrx_sync_on_text ctrx_sync_on_text_ocr

Back to top

Additional agent-only functions

The following table lists additional functions that are available when the Citrix agent is installed. For details on a function, click the name of the function.

Function Description
ctrx_get_server_name Retrieves the name of the active server to which the client is connected.
ctrx_get_text_location Searches for a text in a selected area and retrieves the text location.
ctrx_list_select_item Selects an item from a list.
ctrx_menu_select_item Highlights a menu item.
ctrx_sync_on_text_ex Waits until specified text is displayed in the specified area.

Back to top

See also: