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.
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|
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.
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.
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:
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.
Click within the snapshot.
Mark the relevant object or area in the snapshot, as follows:
Mark a bitmap Other commands
To mark a bitmap:
- Right-click the bitmap and choose Insert Sync on Bitmap from the right-click menu.
- Mark the relevant area.
- 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:
- 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.
When the object is highlighted, right-click and select one of the Insert commands. A dialog box opens with the step's properties.
- Set the properties as needed and click OK. VuGen inserts the step into your script.
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<![CDATA[ ]]>|
|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||<![CDATA[ ]]>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);
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|
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.
|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.|