Rational Performance Tester and Citrix troubleshooting and best practices

The IBM Rational® Performance Tester Extension for Citrix Presentation Server uses the Citrix ICA Client Simulation API, which is part of the Citrix client software, to record and play back user interactions with Citrix-based applications (virtualized applications running in Citrix Presentation Server or XenApp or XenDesktop software). Multiple Microsoft Windows processes interact in the background to make this happen. This tutorial discusses best practices to adopt for Citrix load testing using Rational Performance Tester and tips to troubleshoot common problems. This tutorial does not include the best practices for Citrix Performance Testing; you'll find those in the Rational Performance Tester Knowledge Center.

This tutorial has two sections: troubleshooting and best practices while recording, and testing and scheduling playback.

Citrix Errors during test recording

AllowSimulationAPI key is not present in Windows Registry

When launched for recording for the first time after the Citrix client (Citrix Receiver or Citrix Online plugin) installation, you might see "Unsupported Function" displayed prominently in the Citrix client window open for recording. This error is caused by incorrect or incomplete Windows Registry entries that pertain to the Citrix client — most importantly, the registry key used by Citrix client AllowSimulationAPI, which activates ICA Client Simulation API.

If you encounter this error, make sure the installer of Citrix runs as a user with administrative privileges. Even though you installed the Citrix client as an administrative user, occasionally the AllowSimulationAPI fails to get written. If this happens, you can manually create the entry.

To verify whether the AllowSimulationAPI key is present and create it if required:

  1. Open Windows Registry Editor (Start > Run > Regedit).
  2. If you have 32-bit Windows, navigate to HKEY_LOCAL_MACHINE > SOFTWARE > Citrix > ICA Client > CCM.
  3. If you have 64-bit Windows, the path is HKEY_LOCAL_MACHINE > SOFTWARE > Wow6432Node > Citrix > ICA Client > CCM.
    ICA client folder in Windows Registry
    Screenshot shows ICA client folder in Windows Registry
    Screenshot shows ICA client folder in Windows Registry
  4. Windows Registry entries for ICA client: In the CCM Folder, verify that the key AllowSimulationAPI is present and that its value is 1. If the value is 1, ignore the remaining steps in this section.
  5. If the CCM Folder or AllowSimulationAPI value is not present, right-click the ICA Client folder and select the New > Key option. A new folder is created as a child of the ICA Client parent folder.
  6. Rename the new folder CCM.
  7. Right-click this folder and select New > DWORD (32-bit) Value.
  8. Name the new attribute AllowSimulationAPI.
    Creation of AllowSimulationAPI
    Screenshot shows creation of AllowSimulationAPI
    Screenshot shows creation of AllowSimulationAPI
  9. Double-click AllowSimulationAPI. The Edit DWORD (32-bit) Value dialog box opens.
    Edit AllowSimulationAPI
    Screenshot shows editing AllowSimulationAPI
    Screenshot shows editing AllowSimulationAPI
  10. In the Edit DWORD (32-bit) Value dialog box, type 1 in the Value data field, then click OK.
  11. If the recording problem continues, restart the system to ensure that the registry settings have taken effect.

Clean up Citrix processes

When the Citrix client starts, it launches a few processes, notably the Citrix connection center (concentr.exe) and the Citrix Connection Manager (wfcrun32.exe). These processes will continue running after the Citrix client window exits after closing the connection with the Citrix server.

Due to this, when you initiate a Citrix test recording with Rational Performance Tester, you might encounter the following errors. These errors will occur after the Citrix client window for recording opens:

  • Unsupported Function
  • Protocol Driver Error

A new Citrix test can't be captured and generated in this state. To recover and get the recording to work successfully, terminate the Citrix Connection Centre (concentr.exe) and Citrix Connection Manager (wfcrun32.exe). This forces the Citrix client to open new instances of these processes in the next attempt to connect. To end the processes, use either Windows Task Manager or the taskkill utility from the Windows command line.

The processes CitrixRuntime.exe started by Rational Performance Tester and wfica32.exe started by the Citrix client might remain in the system due to an abnormal exit of a test or scheduled playback. If errors occur during recording, terminate the processes before you start a new recording. Be sure to end the concentr.exe process first.

Citrix Online Plug-in vs. Citrix Receiver

The Citrix client software was previously named Citrix Online Plug-in. The last Citrix Online Plug-in stand-alone (V12.3) was released in April 2012. It is no longer supported. The Citrix Online Plug-in software is now part of the Citrix Receiver package. The first Citrix Receiver (V3.1) included Online Plug-in V13.1, and the version nomenclature has continued with the same pattern.

The machine used for Rational Performance Tester recording and playback should not have both Citrix Online Plug-in and Citrix Receiver installed separately. To confirm this, look in the Add/Remove Programs utility in the Windows Control Panel and verify that only one is installed.

Record with application window maximized

While recording mouse-click events, the ICA Client Simulation API captures the x and y coordinates of actions. During playback, Rational Performance Tester instructs the ICA Client Simulation API to perform the playbacks on the same coordinates. This makes the actions sensitive to differences in relative positioning of the application window while playing back. If the application window opens in a different relative location on the screen, the required GUI element is no longer in the same place, and the mouse event won't have any effect on the application. Playback failures can result.

The image below shows a Citrix test recorded against a simple application — Windows Notepad. In this test:

  • The user opens Notepad
  • Types foo
  • Exits the application using mouse clicks

This test contains a left mouse-click event on coordinates (577, 402). Those coordinates now correspond to the location where the user dismissed the Save dialog box.

Citrix mouse-click test element
Screenshot shows Citrix mouse-click test element
Screenshot shows Citrix mouse-click test element

If during playback, the Save dialog window or the Notepad window opens in a different location from where it was while recording, then the mouse click on coordinates (577, 408) have no effect. The Citrix test will cause a logout failure, and unexpected windows open the next time that same user attempts to log in.

To avoid this, use hotkeys or shortcuts where you can while recording. If certain actions do not have an associated shortcut or hotkey, record the interaction with the main window maximized. With the application window maximized, the chances of a change in relative positions is less, yielding robust playbacks. Recording a keyboard action to the Windows shortcut that maximizes the application main window immediately after it launches.

Best practices for a multi-user Citrix schedule run

A multi-user Citrix schedule playback is typically not done on the workbench machine but on a different one using IBM Rational Performance Tester Agent software. This section describes a couple of best practices for running multi-user Citrix schedules on Rational Performance Tester Agents.

Setting up agent machines for Citrix playback

Important things to know when using a remote agent machine to run your workload are:

  • Make sure Rational Performance Tester Agent is 32-bit. Citrix test playback does not work with the 64-bit Agent software.
  • The Registry entry for AllowSimulationAPI is required for Citrix playback. As with the Workbench machine, make sure the Citrix client is installed as a user with administrative privileges.
  • Verify that the AllowSimulationAPI registry key is in the correct location with a value of 1.

Limit concurrent logins

It is typical in a load test scenario to have virtual users logging in, performing actions, and logging out in a loop for a long duration. As the number of virtual users in a system increases in a playback, multiple Citrix users might log in to the server at the same instant. When multiple users simultaneously log in to the Citrix server from the same agent machine, reliability issues with the Citrix sessions that lead to playback errors can occur. This occurs very rarely during a multi-user schedule playback depending on environmental factors, such as time required to complete a login, so do not apply this solution for all schedules. Use it only as and when necessary.

Ramp-up time helps to mitigate this by distributing user login. But in tests that run for a long duration with loops, only having ramp-up time might not be sufficient. However, you can set up the schedule to prevent multiple concurrent logins.

The image below shows one approach for preventing concurrent logins. In this example, a login lock file is created in the file system using a custom code element. This occurs before starting the Login element. Another custom code removes this file after the user completes login.

Custom code elements to lock Citrix login
Screenshot shows custom code elements to lock Citrix login
Screenshot shows custom code elements to lock Citrix login

The listing below shows the virtual user running this code. It verifies that the lock file is not present before proceeding with logon. If the lock file is present, it waits until the lock file is no longer available in the system. The code also includes a mechanism to detect stale lock files.

Virtual user code
package customcode;

import java.util.Calendar;
public String exec(ITestExecutionServices tes, String[] args) { 
    File connectionLock = new File("C://path//to//lockFile"); 
            tes.getTestLogManager().reportMessage("Another VU logging in now. Will try later."); 
            try { // Delete stale lock file if any 
                long timeStamp = connectionLock.lastModified(); 
                Calendar rightNow = Calendar.getInstance(); 
                 if ((rightNow.getTimeInMillis() - timeStamp) > (5 * 60 * 1000)){ //> 5 mins
                     tes.getTestLogManager().reportMessage("Stale lock file to be removed");
                } catch (Exception e) { 
            try {
                 tes.getTestLogManager().reportMessage("Creating Lock File");
            }catch (IOException e) {
 return null;

The following listing is custom code that releases the lock (deletes the connection lock file). This should run after a user successfully logs in.

Sample code to release connection lock
public String exec(ITestExecutionServices tes, String[] args) {
    File connectionLock = new File("C://path//to//lockFile"); 
        tes.getTestLogManager().reportMessage("Removing login lock file"); 
     return null;

Note: There are other ways to achieve locking with custom code, such as using the Execution Engine data area.


Citrix performance testing is challenging, even for experienced developers. Setting up the client systems and the interaction of Rational Performance Tester with Citrix ICA Client Simulation API can be complicated. In this tutorial, you learned about a few commonly occurring problems and solutions to those problems. Use this information and the Rational Performance Tester Knowledge Center to resolve some of the obstacles that might occur in a Citrix performance testing project.

Downloadable resources

Related topics

Zone=DevOps, Rational
ArticleTitle=Rational Performance Tester and Citrix troubleshooting and best practices