Record Citrix tests

When you record a test, the test creation wizard records your interactions with the Citrix server, generates a test from the recording, and opens the test for editing. You can record a test session in the Citrix XenApp client.


Citrix performance testing guidelines

Citrix performance tests use synchronization mechanisms to replay the tests on multiple Citrix sessions independently of server performance.

These guidelines will help you record a reliable test and avoid synchronization timeouts during test execution.

Ensure that you have a working Citrix client environment and that you can connect to a Citrix server. IBM Rational Performance Tester supports Citrix Online Plugin 12.3 and Citrix Receiver 3.3 to connect to the Citrix server.

The most efficient recording method is to specify a published application or a server in the recording wizard. It is preferable to specify your login credentials in the wizard instead of recording the login sequence as part of the test.

Ensure that the session that you are recording will be reproducible. To record tests that can be reliably replayed, follow these guidelines:

After recording, and while you edit the test, it is important to perform regular verification runs in order to validate the test with a single user. After each run, open the test log to verify the test synchronizes correctly. If necessary, change the synchronization level from Mandatory to Conditional or Conditional to Optional on window events or image synchronizations that produce unnecessary timeouts. Only deploy the test on vusers or run it in a schedule when the test is robust enough to run flawlessly with a single user.


RPT Agent requirements

When you install Load Generation Agent, by default, the agent starts as a service. To use the Load Generation Agent for Citrix recording, the agent must run as a process. For Windows, open Windows Services. If the MajordomoService is set to Automatic start up, set it to Manual and then stop the MajordomoService. You can now open the Majordomo folder from the RPT Agent installation path and double-click Majordomo.bat.


Optical Character Recognition

You can use optical character recognition when performing image synchronizations. This allows the test to synchronize itself by recognizing the contents of a screen area. In some cases, the software can fail to correctly recognize portions of text or letters.

To improve results of the optical character recognition, follow these guidelines:

When recording image synchronizations with optical character recognition, accuracy of the recognized text is not essential. It is only important that the recognized text is consistent each time the test is executed for the test to synchronize. For example, if a portion of text is displayed as "Hello" on the screen, and recognized as "He110" in the recorded test, you should not attempt to correct the value in the image synchronization test element, because the same result should occur when the test is executed for the test to synchronize.


Long duration test runs

When running long duration test schedules that exceed 24 hours, use the long run mode to reduces resource consumption with the Citrix client. This mode increases the reliability of long duration test runs by running the tests in multiple process. You must enable this option for each user group in the schedule.

In long run mode, a new process is created for each virtual tester.


Record a Citrix test

You can record a Citrix session with the Citrix XenApp version 5.0 or later client. When you record, the recording wizard automatically starts the Citrix XenApp client and configures it for recording. When you have finished recording the session, the wizard generates a Citrix performance test.

By default, IBM Rational Performance Tester Agent starts as a service. If you run a Citrix test on an agent, you must start RPT Agent as a process.

To start an agent as a process:

  1. Open the Windows Services window.
  2. For the Majordomo service, change the Startup Type to Manual and then change the Status to Stop.
  3. From the agent's installation directory, open the Majordomo folder, and double-click the Majordomo.exe file.

To record a Citrix test:

  1. In the Performance Test perspective, click the New Test from Recording toolbar button or click File > New > Test from Recording.
  2. In the New Test from Recording wizard, select Create a test from a new recording, select Citrix Test, and click Next. If you are recording sensitive data, you can select a Recording encryption level.
  3. On the Select Location page, select the project and folder locations to contain the new test, type a name for the test, and click Next. If necessary, click the Create Parent Folder push button to create a new project or folder.
  4. On the Citrix Connection Settings page, specify how to connect to the Citrix server. Complete one of these tasks:

    • If your Citrix administrator has provided you with an ICA file, complete these steps:

    1. Select With ICA file to use its settings to connect to the server.
    2. Click Browse to locate and select the ICA file on your computer.
    3. Click Next to continue.

    • To manually specify the Citrix server to use for the session, complete these steps:

    1. Select On server to connect directly to the server.
    2. Specify the name or IP address of the server or click Browse to locate a server or server farm on your local network.
    3. Optional: If you need to change the Citrix farm parameters, click Farm Settings.
    4. To record a Windows desktop session, leave Initial program blank.

    • If your Citrix administrator has published applications on the network, complete these steps:

    1. Select On published application, and click Browse to choose the application from the list of published applications on the server or server farm.
    2. Optional: If you need to change the Citrix farm parameters, click Farm Settings.
    In this case, the server farm performs the load balancing and selects the server automatically.
  5. To make the logon sequence part of the session parameters, select Logon with user-specified credentials, type your credentials, and specify the domain name. If this option is disabled, your credentials are recorded as part of the logon sequence during the recording.

    If you use the With ICA file option and the ICA file contains the LogonTicket command, even after you type your credentials as part of this step, you must type your credentials again on the Citrix server to start a Citrix test. To avoid entering credentials twice, you can manually remove the LogonTicket command from the ICA file.

  6. Click Next to continue.
  7. On the Citrix Session Preferences page, you can provide a description for the test, change the video settings, encryption mode, and advanced options for the Citrix XenApp client. Click Next to continue.

    Because Citrix performance tests are based on low-level interactions with the server, including mouse and window coordinates, the Citrix desktop must be large enough to support the application under test. You must particularly avoid scrolling windows during the recording.

  8. If this is the first time you record a Citrix performance test, read the Privacy Warning, and then select Accept to proceed.
  9. To start the recording, click Finish. The Citrix Recording window opens, displaying the Citrix XenApp session and a set of recorder controls.
  10. In the Citrix Recording window, complete the tasks to test. You can use the recorder controls in the toolbar to add comments, record synchronizations, or take screen captures during the recording.

    1. To add a user comment to the recorded test, click the Insert user comment icon . Because Citrix tests can be long and difficult to read, meaningful comments can help you locate important elements.
    2. To add an image synchronization to the recorded test, click the Insert image synchronization icon , select an area of the screen to be used for synchronization, and then click the Insert image synchronization icon again. Image synchronizations enable the test to keep track of the contents of a screen area during the replay instead of focusing only on window events. You can use these screen captures to maintain synchronization of a test in applications that do not create or modify many windows, but update the contents of a window regularly. The contents of an image can be evaluated either as a bitmap hashcode or as a text value obtained by optical character recognition.
    3. To insert a response time measurement during the recording, click the Insert response time icon to create a start for the measurement in the recording, and click the icon again to create a stop.
    4. To add a screen or window capture to the recorded test, click the Capture screen icon or Capture window icon . Screen and window captures make your tests easier to read and help you visualize the recorded test. To change the settings for screen and window captures, click the Screen capture preferences icon , and then select one of these options:
      No automatic screen capture
      Select this option if you do not want the test recorder to record screen captures automatically. When this option is selected, you can still record screen captures manually. This option is selected by default.
      Capture screen every
      Automatically record a periodic screen capture and specify the time between captures.
      Capture screen on window creation
      Select this option to record a screen capture each time a window object is created in Citrix.
      Exclude tooltips
      When Capture screen on window creation is selected, enable this option to prevent creating a screen capture each time a tooltip event is displayed during the recording. If this option is disabled, screen captures are recorded when tooltips are displayed.

      To preview all screen captures, window captures, and image synchronizations on the side of the Citrix Recording window, click the Screen capture preview button icon .

  11. When you have completed the sequence of actions to be tested, close the session, and stop the recorder by clicking the Stop recording icon . A progress window opens while the test is generated. On completion, the Recorder Control view displays the Test generation completed message, the Test Navigator lists your test, and the test opens in the test editor.


Record a test with the Citrix Web Interface

You can record a Citrix session from the Citrix Web Interface to use the load balancing feature provided by this connection method. You do this by recording an HTTP test containing session information recorded with the web interface, and then by recording a Citrix test that uses this information. When you have finished recording the session, the wizard generates a Citrix test.

An HTTP test provides the session information to connect to a Citrix farm for a user and an application. The same HTTP test can be reused to record different Citrix tests.

Citrix tests recorded with this method can only be run within a schedule. After recording, you must set up a schedule that runs the HTTP test and then the Citrix test. By default, IBM Rational Performance Tester Agent starts as a service. If you run a Citrix test on an agent, you must start RPT Agent as a process.

To start an agent as a process:

  1. Open the Windows Services window.
  2. For the Majordomo service, change the Startup Type to Manual and then change the Status to Stop.
  3. From the agent's installation directory, open the Majordomo folder, and double-click the Majordomo.exe file.

  1. First, record an HTTP test: Click File > New > Test from Recording, and then select HTTP Recording and click Next.
  2. On the Select Location for Test Suite page, select a project. In Test file name, type a name for the HTTP performance test, and then click Finish. The name that you type is the base name for the recording, test, and other required files. You see these files in the standard Navigator or the Java. Package Explorer with their distinguishing extensions, but you see only the simple (test) name in the Test Navigator.
  3. In the web browser, type the URL of the Citrix Web Interface server.
  4. On the Citrix Web Interface page, type your user name, password, and domain to open a session. The Citrix Web Interface displays the list of applications published on a server and available to the user.
  5. Open the Connection Preferences, and select a Window Size other than Seamless. Seamless mode is incompatible with test schedules.
  6. Select the application to test.
  7. Close the application and the web browser. This stops the recording and generates a new HTTP test that ends with a custom code test element named StoreICA.

    If there are any test elements after StoreICA, remove them.

  8. Now, record the Citrix test: Click File > New > Test from Recording, and then select Citrix Recording, and click Next.
  9. On the Select Location for Test Suite page, select a project.
  10. In Test file name, type a name for the Citrix test, and then click Next.
  11. On the Citrix Connection Settings page, select Through a Web interface, and in Connection scenario, click Browse; then select the HTTP test containing the Citrix Web Interface session.
  12. To start the recording, click Finish. The Citrix Recording window opens, displaying the Citrix XenApp session and a set of recorder controls.
  13. In the Citrix Recording window, perform the tasks to test. You can use the recorder controls in the toolbar to add comments, record synchronizations, or take screen captures during the recording.

    1. To add a user comment to the recorded test, click the Insert user comment () push button. Because Citrix tests can be long and difficult to read, meaningful comments can help you locate important elements.
    2. To add an image synchronization to the recorded test, click the Insert image synchronization () push button, select an area of the screen that will be used for synchronization, and then click the Insert image synchronization button again. Image synchronizations enable the test to keep track of the contents of a screen area during the replay instead of focusing only on window events. You can use them to maintain synchronization of a test in applications that do not create or modify many windows, but update the contents of a window regularly. The contents of an image can be evaluated either as a bitmap hashcode or as a text value obtained by optical character recognition. You can also add verification points to image synchronizations in the test editor.
    3. To add a screen capture to the recorded test, click the Capture screen () push button. Screen captures make your tests easier to read and help you visualize the recorded test.
    4. To change the settings for screen captures, click Screen capture preferences , and then select one of these options:
      No automatic screen capture
      Select this option if you do not want the test recorder to record screen captures automatically. When this option is selected, you can still record screen captures manually. This option is selected by default.
      Capture screen every
      Automatically record a periodic screen capture and specify the time between captures.
      Capture screen on window creation
      Select this option to record a screen capture each time a window object is created in Citrix.
      Exclude tooltips
      When Capture screen on window creation is selected, enable this option to prevent creating a screen capture each time a tooltip event is displayed during the recording. If this option is disabled, screen captures are recorded when tooltips are displayed.
  14. When you have completed the sequence of actions to be tested, close the session and stop the recorder by clicking the Stop recording (). A progress window opens while the test is generated. On completion, the Recorder Control view displays the message Test generation completed, the Test Navigator lists your test, and the test opens in the test editor.

To run the Citrix Web Interface test, you must create a new schedule, add the HTTP test, and then add the Citrix test.


Inserting a new recording into a Citrix test

You can insert a new recording into a Citrix test. Use this feature to add or replace a part of a recorded session.

Inserting a new sequence into a test requires that the Citrix session reaches the same state as is expected at the point where the new sequence is inserted. For example, if your new sequence must interact with a particular window that was created earlier in the test, you must advance to the point where that window is in the expected state before the recording can start. To do this, the Citrix test recorder can either automatically replay the existing scenario up to the insertion point, or you can manually advance the session to the expected state.

When inserting a new sequence into a test, it is important that the context of user actions is preserved to ensure that the test synchronizes properly during the replay. The resulting test will probably require manual editing to make sure that test can replay smoothly.

Because Citrix tests contain low level user input and synchronizations, minor changes can prevent the test from working. When editing these tests, you must ensure that they are functionally identical.

To insert a recording into a test:

  1. In the test editor, select the element before which you want to insert the new recording. It is easier to manage the new test sequence when the insertion point is at the window event level of the test.
  2. Click Insert, and then Record scenario.
  3. In the Update Recording window, specify how you want the session to reach the state expected at the insertion point, and then click OK.

    • Select Automatically replay the scenario to replay the test up to the insertion point. With this option, the test replays and stops when it reaches the insertion point. If the replay fails to synchronize, you will be asked to manually bring the session to the expected insertion point state.
    • Select Manually advance to the expected state to manually put the Citrix session into the state that will be expected at the insertion point.
  4. After the Citrix session is in the expected state and you are ready to start the new recording, engage the Enable/Disable recording button in the toolbar. If you chose the automatic replay option, the recording is enabled automatically.
  5. Perform the sequence of actions to add to the existing test. When you have finished, click the Enable/Disable recording again to stop the recording.

    You can restart the recording several times. However, you must be sure that the Citrix session resumes from the same state that it was in when it was stopped. If actions are missing from the recorded sequence the test is unlikely to synchronize correctly during the replay.

  6. When you have completed the sequence of actions to be inserted into the test, close the session and stop the recorder by clicking Stop recording . A progress window opens while the test is generated. On completion, the Recorder Control view displays the message Test generation completed, the Test Navigator lists your test, and the test opens in the test editor.
  7. After the test has been updated in the Test Navigator, check that the new sequence was properly inserted into the test before saving the new test. Check that the context of the Citrix session is compatible with the user actions at the beginning and at the end of the of the inserted sequence. If the results of the insertion were not what you expected, you can revert to the previously saved version of the test by clicking File > Revert or try to correct any problems manually.


Change Citrix recording preferences

You can change the behavior of the recorder by changing the preference settings.

  1. Click Window > Preferences.
  2. In the Preferences list, expand Test, and then click Citrix Recorder.
  3. Select the setting you want to change.
    Screen capture options
    These settings specify how the test recorder performs screen captures of the Citrix desktop during recording.
    No automatic screen capture
    Select this option if you do not want the test recorder to record screen captures automatically. When this option is selected, you can still record screen captures manually. This option is selected by default.
    Capture screen every
    Automatically record a periodic screen capture and specify the time between captures.
    Capture screen on window creation
    Select this option to record a screen capture each time a window object is created in Citrix.
    Exclude tooltips
    When Capture screen on window creation is selected, enable this option to prevent creating a screen capture each time a tooltip event is displayed during the recording. If this option is disabled, screen captures are recorded when tooltips are displayed.
    Capture screen on image synchronization
    Select this option to ensure that a screen capture is recorded each time an image synchronization is recorded.
  4. After changing a setting, click Apply.


Change Citrix test generation preferences

You can change how Citrix events are converted into performance test elements.

  1. Click Window > Preferences.
  2. In the Preferences list, expand Test, expand Performance Test Generation, and then click Citrix Test Generation.
  3. Select the setting you want to change.
    Record Optimization Options
    These settings specify how mouse and window events are interpreted in the generated test.
    Window activate recording
    Specify whether to record no, last, or all window-activate actions when a sequence of similar actions is detected.

    • none disables recording of window-activate events.
    • last records only the last of an uninterrupted sequence of window events. This eliminates redundant window-activate actions from the recording.
    • all records all events of the sequence.
    Mouse move recording
    This setting specifies which mouse move events are recorded. Relevant is the default setting.

    • All records an uninterrupted sequence of mouse movements in the generated test.
    • Relevant records only the mouse movements that generate a response, such as hover text.
    • First and last records a simplified mouse-move action.
    Automatic Generation
    These settings specify test elements that are automatically generated after recording the test.
    Verification point on every window title change
    When enabled, this option generates a window title verification point whenever the caption changes. If this option is disabled, the window title is verified only when a new window is created. This option is disabled by default.
    Response times for main windows
    When enabled, this option generates response time measurements for all recorded main window-create events. A main window is a window that is created at the top level of the test contents tree and contains user actions. The generated response time measurement starts with the keyboard or mouse action that immediately precedes the window-create event. This option is enabled by default.
    Window event synchronization criteria
    Use this option to disable window recognition on the window position, size, or title. Disable any of these options if the test produces synchronization timeouts because a window changes its position, size, or title between or during test runs.
    Default Test Execution Delays
    This page specifies the default keyboard and mouse delays for the test client. Do not change these settings unless you are experiencing problems with events that do not run correctly.
    Synchronization timeout delay
    This is the delay after which a timeout error is produced when a window event or an image synchronization element is not recognized during test runs. The default value is 15 000 milliseconds. The specified delay is for synchronizations that are set as conditional. Mandatory synchronizations use a delay of three times the specified delay. Optional synchronizations use a fixed delay of 2 seconds.

    In the generated test, the Override synchronization timeout for a particular window creation event will be enabled with the corresponding recorded time only if it is greater than what is specified in this preference.

    If think time is under x ms, then replace with
    If the delay between two events is above the specified limit, then it is handled as a think time. If the delay is below the limit, then the test generator replaces the think time with one of the following delays. The think time is the delay spent by a virtual user before performing an action. The default limit is 20 000 milliseconds.

    In the generated test, the think time for a particular user action will be enabled only when the recorded think time is greater than the value specified for this preference.

    Delay between mouse down and mouse up in a click
    This is the default delay used to generate a mouse click action using a mouse down and a mouse up action. The default value is 20 milliseconds.
    Delay between two mouse clicks in a double click
    This is the default delay used to generate a double-click action using two mouse clicks. The default value is 50 milliseconds.
    Delay between key down and a key up in a stroke
    This is the default delay used to generate a key-stroke action using a key-down and a key-up action. The default value is 20 milliseconds.
    Delay between two keyboard strokes in a text input
    This is the default delay used to generate a text input action using multiple key stroke actions. The default value is 50 milliseconds.
    Default OCR settings
    This page specifies the settings for text extraction by optical character recognition in image synchronizations. You might need to experiment with various settings to obtain good results. These settings define the default behavior for new image synchronizations. You can change the behavior for individual image synchronization elements by changing the OCR settings in the test editor.
    OCR default language
    This is the language of the dictionary that is used to recognize words for the application that you are testing. This setting defines the subset of languages that will be available in image synchronization elements in the test editor.
    OCR default zoom factor
    This is the enlargement factor that is applied to the image. The default setting is medium for standard font sizes. Increase the zoom factor to improve recognition of smaller fonts or decrease for larger fonts.
    OCR default brightness
    This is the brightness level from 0 to 250 that is applied to the image. The default setting is 70 for text with normal contrast. Increase the brightness setting to improve recognition of darker images or decrease for lighter images.
    OCR default recognition rate
    This is the rate of recognition that is required for the extracted string to match the expected text. Decrease the recognition rate to tolerate a proportion of mismatching characters in the recognized text. The default is 100%, which means that an exact match is required.
  4. After changing a setting, click Apply.