How to Set Up and Run Load or Performance Tests in a Microsoft Terminal Server or Citrix Environment

Note: This is an expanded explanation of the Mercury document called Load Testing with LoadRunner in a Citrix/Microsoft Terminal Server environment., dated March 11, 2002.

Questions, corrections: Whitney Wetherill, 908-626-6022

Introduction

This document describes the setup process for MTS (Microsoft Terminal Server) LoadRunner virtual users and, since they are essentially identical, it should also be useful for setting up Citrix virtual users. However, it was written as part of an MTS solution and has not, at this writing, been tested for a Citrix solution. This document was originally written for internal use and has been modified to become more generic.

References

Mercury Interactive provides two files that are intended to assist in the setup of Citrix/MTS virtual users. They are routinely updated at Mercury and an effort should be made to find the latest version on their Customer Service web site (http://merc-int.com (there is no www)). These documents are:

1. citrix_setup_video.avi.exe2. Load Testing with LoadRunner in a Citrix/Microsoft Terminal Server environment, March 11, 2002.

Note that the first document is an avi.exe file, which will actually "play" as a video (double click the file) if you are using WINNT. If you are using WindowsXP you will probably not be able to play this file unless Mercury updates it. The second document is a Word document.

Both of the above files are useful but elaboration should also help and that is the purpose of this document: to add to the information provide by Mercury.

Understanding MTS/Citrix

Taking LoadRunner and WinRunner out of the picture for a moment, it is useful to discuss MTS/Citrix solutions to gain a basic understanding of this technology. MTS/Citrix technology is used to deploy an application on a server, which must be especially configured for the purpose. The server is then accessed by client users whose local c:\ drives do not contain any of the application or database files but do contain MTS or Citrix software allowing them to connect to the MTS or Citrix server. This setup allows the developers to deploy changes to the application software on the server with no need to change any files on the client. (Note that there can be multiple servers but we will limit this discussion to one server.) The MTS/Citrix solution also, if properly implemented, allows the client user to work faster because the only "work" being performed on the local client machine is the rendering of an image of the application on the screen. All of the typical client-side work is done on the server.

Performance and Load Tests of MTS/Citrix

There are two basic types of information that Mercury's tools can provide for MTS/Citrix technology: 1) performance as it would be perceived to an actual user and 2) database (or connectivity) load . The first is essentially a WinRunner solution, because it includes the rendering of the GUI and that piece is critical to the actual user's experience. WinRunner, used by itself, runs only one "user" on the script. It's primary purpose is to functionally test the application, so one user is enough. But for performance testing, we need multiple users. LoadRunner runs multiple users but it does so without rendering the GUI.

The trick for performance testing of an MTS/Citrix setup is to use WinRunner for it's ability to test the GUI combined with LoadRunner for it's ability to run multiple virtual users. Even in an MTS/Citrix situation, if the only requirement of the test is to stress the database's ability to handle load, the solution can be implemented without the WinRunner piece by using LoadRunner to simulate sessions without the GUI rendering. This document discusses each of these basic tests separately.

Performance Test, WinRunner Used With LoadRunner

Setting up the Test Machines

Figure 1 below provides a very basic description of an MTS setup. The drawing can be found at \\at_lbtciadi01\int_testdocs\Citrix_MTS_Docs\DiagramMTS_Citrix_Solution.vsd for closer inspection. Detailed explanations for each step are provided following the diagram.

Figure 1, Diagram of MTS/Citrix setup.

Step 1. Setting up the MTS/Citrix Server

The MTS/Citrix server is also the load injector machine. This means that the virtual users are actually running on this server (just as the actual users are actually running on the MTS or Citrix box). WinRunner and LoadRunner are both required for performance testing. The Mercury instructions quoted here come from their March 11, 2002 version of "Load Testing with LoadRunner in a Citrix/Microsoft Terminal Server Environment." (see Item 2 in the References section of this document) and are in courier font.

1) Install Citrix/MTS on the server machine where you will run the AUT and LoadRunner DB or GUI Vusers. Set up the Citrix Services to work in Application Server mode. The "AUT" is the application being tested. The "LoadRunner DB" refers to load test vusers and will be discussed in the second part of this document. The "GUI Vusers" refer to the vusers running the WinRunner script, launched from LoadRunner on the Controller (which we will talk about in Step 3). Often, you will be using a test MTS or Citrix server that the developers have already configured with MTS or Citrix.

2) Install LoadRunner and WinRunner on the Citrix Server. (By default, LoadRunner will put a shortcut to Remote Command Launcher/Launcher Agent into your Startup folder. Please do not remove it.) This instruction is referring to the same server that was discussed in 1) above. If the functional testers have already used the same MTS/Citrix server, WinRunner may already be installed. You should be able to do a partial LoadRunner installation (you need Vugen) but we did not test with a partial install. Check with Mercury for license information.

3) For the Citrix Server, copy the "wrun.ini" file from the WinRunner\dat directory to c:\WTSVR\Profiles\yourusername\windows directory.

For Microsoft Terminal Server, the "wrun.ini" file resides in the c:\WINNT\ or the c:\Windows\ folder.

Make sure that values are specified for the variables M_ROOT, M_HOME, and TMP in the [WrEnv] in the beginning of the file as in the following example.

[WrEnv]M_ROOT=d:\mercury interactive\WinRunnerM_HOME=d:\mercury interactive\WinRunnerTMP=d:\mercury interactive\WinRunner\tmp

Actually, this instruction can be misleading if you are on a large network. The purpose of this instruction is to provide the LoadRunner tool, running on the Controller machine, with an INI file for WinRunner on the MTS server (or Citrix server, as the case may be). LoadRunner 'reads' the INI file to find the WinRunner executable and tmp file storage and it looks for this INI file in several places that the above instruction does not mention. In our case, the first place it looks is actually on network user's shared directory, which we map to H:\. WinRunner was already installed on the MTS server we were using. We were logging in with a test userid "masstest." We finally located the correct INI file at H:\windows\wrun.ini where H was "masstest on sharename…" Note that the error message we were getting from the Controller when it tried to find WinRunner referred to the C:\ drive "-55997 : There doesn't seem to be a WinRunner installation on this machine. WinRunner's wrun.ini file does not exist C:\WTSRV\wrun.ini"

Our first attempt to correct this problem led us to create a wrun.ini file in the C:\WTSRV directory. This led to the following error:"-55998 : WinRunner's M_ROOT variable is undefined in C:\WTSRV\wrun.ini"

It was only when we found the H:\windows\wrun.ini file and made the changes indicated in Mercury's instructions (above) that the test would run.

4) For LR7.x, install the launcher agent on the load generator machine as a process, not a service.

The LoadRunner Agent needs to be running as a process rather than service.To stop the LoadRunner Agent Service on the load generator machine go to 'Start | Settings | Control Panel | Services' and stop the service. Then browse to the 'launch_service\bin' folder in the LoadRunner installation directory on the load generator machine and click 'magentproc.exe' to launch the agent as a process.

For LR6.5, ensure that the remote command launcher is running on the Citrix server.

This instruction is very confusing if you don't realize that the "load generator machine" is the same as the MTS/Citrix box. Note that in the little video (see References, item 1), the instruction is to make a shortcut for the magentproc.exe file and put it into the startup menu for the MTS/Citrix server. This is a good suggestion because it means that every time you connect to the MTS/Citrix server you will be launching the LoadRunner agent as a process automatically. Verify that this happened properly by searching for the little icon in the lower right corner of the Start bar on the MTS/Citrix server after you open the session. (Opening sessions will be explained in Step 2, below.) Figure 2 shows the icon for the process agent for LR7.5:

Figure 2: Icon showing LoadRunner agent running as a process.

5) For LR7.x, modify the configuration file on the load generator machine located at: launcher_service\dat\br_lnch_server.cfg and set the value of CitrixisActive in the [Citrix] section to 1 and save it. Launch the agent after having saved the file.Clearly, this instruction, which the Mercury document has as number 5) (and that's why it is number 5 in this document) should have been provided before number 4) because you want to do this before launching the agent. Yes, that's the same agent they are discussing in number 4). Also, again, the load generator machine is the MTS/Citrix server. So, on the MTS/Citrix server, do a file find on the file called "br_lnch_server.cfg" and select the file that is in the path shown above. Open it in Notepad. The file will look like the figure below:

Figure 3: br_lnch_server.cfg

As you can see, in the Figure 3, the setting is "CitrixIsActive" and it's default value is "0". Change that to 1 and save.

Step 2. Setting up the MTS/Citrix Client Machine

This discussion refers to Step 2 in the diagram above. We are still also following the step by step instructions provided by Mercury in the document listed in our References section (Item 2). We have moved from the load injector machine (which is the same as the MTS/Citrix server where the application resides) to the Client machine. The Client machine (and there may be several) corresponds to the actual users' machines. When an MTS (or a Citrix) user starts to work on an MTS (or Citrix) application, he/she will begin by clicking an icon and thereby launching a session on the server. The resulting window looks like the figure below (this one is an MTS (Microsoft Terminal Server) client window):

Figure 4: Example of a session window with login.

Figure 4 shows a session from a client machine to the server ("ServerName" as shown in the window's title bar).

After the user logs in to the server and launches the application, the his/her desktop will look like Figure 5 (notice the server window with the application (we used MS Word for illustration purposes) in it):

Figure 5, Application (MS Word) launched within MTS session window.

Thus, the user is actually working on the server, not on his/her own box. The only "thing" on the user's box is the rendered image of the server window and the application. When we do a full performance test of the application, we need to replicate the client's session connection on the server and also the GUI rendering on the client's desktop, for each of the virtual users. To do that, we set up "MTS/Citrix Clients."

Continuing with the instructions as they are provided in the Mercury document, we are now at Step 6:

6) Install the Citrix Client on the Citrix client machine (WinNT/WIN95/98/2000). You can use the Citrix Client Creator to create client installation files on diskette. This is used to start Citrix ICA sessions so that the Controller can connect to them.This instruction doesn't help much if you are using MTS (Microsoft Terminal Server). However, since the developers can normally provide the connection methodology to the performance tester, you will be able to get some help with this step. In other words, the developers (or possibly local site support) will help set up the MTS or Citrix client box(es) using the exact same methodology that would be used to set up a new business user. Request the setup software for the application you will be testing from either the developers or from local site support. The only difference is that for performance testing, you will be launching more than one session from each MTS/Citrix Client machine so that you can launch multiple users. For Citrix, the sessions are called "ICA" and for MTS they are just called "remote sessions", "MTS sessions" or just "sessions."

Regarding the statement "This is used to start Citrix ICA sessions so that the Controller can connect to them" - The sessions you start will appear on the desktop of the MTS or Citrix client box, just as is pictured in the discussion above, except that you will be opening more than one such session window. But the sessions you open actually exist on the MTS/Citrix server. The controller will be using these sesions on the server, it will not make any contact with the client machines. The only function of the MTS/Citrix Client machine(s) is to create these sessions on the MTS/Citrix Server. You will be opening these sessions manually (or you can create a little macro or WinRunner script, but this automation has nothing to do with your performance test and must before you launch the test).

The sessions have to be open before the test starts and you will close them manually when the test is over.) You will usually need 1 more session from each client machine than the controller will actually use.

NOTE: As a test that everything so far is working correctly, open more than one session on the MTS/Citrix Client box. Examine each resulting window (scroll to the lower right corner) for the icon that indicates that the Remote Command Launcher is open and that it is in Process mode. See the diagram above in the discussion about the MTS/Citrix Server, which shows what the icon looks like. You need to be able to open multiple sessions on the MTS/Citrix Client and they all need to display this icon.

Step 3. Setting up the Controller Machine for the MTS/Citrix Test

The rest of these instructions refer to the setup of the Controller for the performance test.

7) Perform a Typical, Standalone installation of LoadRunner on the Controller machine (NT/2000 machine).This instruction is self-explanatory, except that you need to be aware that the Controller cannot be run from the MTS/Citrix Server or the MTS/Citrix Client. You probably already have a Controller machine and won't need to install LoadRunner especially for this test. Hopefully you are using LR7.5 or greater. Note that the Controller cannot, as of this writing, be in Test Center.

At this point, if you are using LoadRunner 7.5, the machines are completely set up for a performance test. If you are using LR6.5 you will also need to edit the host file as in 8) below. In addition, in order to test the setup of the host file, you will need to follow 11), so it is included here even though it is out of order from Mercury's original document.

8) (This step needs to be performed with LR6.x only. In LR7.x, LoadRunner handles the ":" delimiter automatically so no further modification is needed in the 'hosts' file.

On the Controller machine, modify the "c:\winnt\system32\drivers\etc\hosts" file (open it in Notepad) to include Citrix Server connection information.

Format: <IP of Citrix Server><server name><client session aliases. 1 per client> Example: 199.99.99.99 remote remote:1 remote:2 remote:3 remote:4NOTE: This is to help resolve the host name remote:1, remote:2 … to your Citrix Server's IP address from the Controller machine.)

Item 8) is in parentheses because readers of this document are probably using LR7.5 or greater, so the information in 8) is not relevant.

(11. From the Controller machine, bring up a command prompt and ping each of the aliases to verify that the aliases are working properly. (E.g. "c:\>ping remote:1"))

This instruction needs to be followed only if you are using LR6.5 and should really have been part of in step 8) since it is a test that the entries you made in the hosts file are actually working.

NOTE: If you are using LR6.5, you might still need some clarification. The example shown here is a hosts file entry for a server named "servername" whose IP address is 199.99.99.99:

199.99.99.99 servername remote:1

After the above hosts file entry was made on the Controller box, a session on the 199.99.99.99 box, using Microsoft Terminal Server on the MTS Client box was manually opened. Then, a ping command was initiated from the Controller box (Start menu, choose Run, type cmd in the Open box and click OK. The DOS box will open with the default network share "H:\>" showing. Type "c:" and press enter to get a command line that reads "C:\>" (i.e., change the directory to C:\). Type "ping", press the space bar, type "remote:1" and press Enter. The bold text below shows the successful ping:

Microsoft(R) Windows NT(TM)(C) Copyright 1985-1996 Microsoft Corp.

H:\>c:

C:\>ping remote:1

Pinging servername [199.99.99.99] with 32 bytes of data:

Reply from 199.99.99.99: bytes=32 time=30ms TTL=125Reply from 199.99.99.99: bytes=32 time=20ms TTL=125Reply from 199.99.99.99: bytes=32 time=30ms TTL=125Reply from 199.99.99.99: bytes=32 time=30ms TTL=125

C:\>

Once again, this instruction should NOT be followed unless you are using LR6.5.

Your boxes are now configured. From this point on, we leave the Mercury document (by all means, consult it for further reference).

Completing a WinRunner/LoadRunner Performance Test

WinRunner Script(s)

To test the performance of the application, each of your virtual users will be running a WinRunner script. If you have a working WinRunner script on the MTS/Citrix server, you can now continue to set up a performance test. If not, the next step is to create a working WinRunner script (or scripts) that exercises the application sufficiently to simulate "real" users. Create and debug the WinRunner script(s) on the MTS/Citrix server. Remember that it will need sufficient time at the window load for the remote rendering of the GUI. For example, if you record a script that loads a window called "Quote Request" the recording may read

set_window ("Quote Request", 2)

where 2 is the number of seconds WinRunner recorded for the window load. Since the test will be remote, this value will need to be increased to 10 or 15 seconds, e.g.: set_window ("Quote Request", 15) . In addition, you can add a wait statement immediately following the set_window statement:

win_wait_info("Quote Request", "enabled", 1, 10);

where 1 = true and 10 = the number of seconds.

You can add transactions to the WinRunner script and these will work with the LR Analysis tool (see instructions for the product). Iterations must be coded into the WinRunner script as there is no Run Time Setting in the Controller for GUI Scripts. It may also be a good idea to include rendezvous points. Once you have a working WR script on the MTS/Citrix server, you can proceed to setting up the sessions.

Client Sessions

Follow your test plan document, if you have one, regarding the number of virtual users the developer or project manager wants to load the application with. The WinRunner/LoadRunner performance test of an MTS or Citrix application can usually support up to 50 (give or take) sessions from each MTS/Citrix Client box. So, if the project manager wants 100 virtual users, you will need at least 2 Client boxes. Open 1 session for each virtual user, distributed across the Client boxes (50 on each box). Open 1 additional session on each box (1 more than the number of virtual users you will need from each box, or in this example, a total of 51 on each box.) Remember to check for the correct Remote Command Launcher icon in the lower right corner of the session window. (If you have problems try adding a client box and reducing the number of sessions on each.)

The Scenario

When you are ready to actually launch the WinRunner script using the LoadRunner Controller, you will need to set up a scenario on the Controller machine. These instructions are written for LR7.5. Open the Controller and initiate a new scenario. There are two default settings that need to be checked:

On the Design tab, click the Generators button. Click the Details button and select Vuser Limits in the resulting Load Generator Information dialog box. Make sure the GUI/WinRunner check box has a check mark in it.

Choose Scenario from the main menu bar. Make sure Enable IP Spoofer is NOT checked. (If it is, select it, close the menu, reopen the menu. Enable IP Spoofer should now NOT be checked.)

1) Attach the Script If you have not already done so, map the MTS/Citrix Server to the Controller machine (use WindowsNT Explorer, Map Network Drive under Tools). Back to the Controller, on the Design tab, click inside the Script Path column, top field. A down arrow should appear. Click it. Browse to the MTS/Citrix server and connect to the WinRunner script. NOTE: You must use the Open Test dialog box in the following sequence. ). First, in the Files of Type box, choose GUI Scripts (this is critical). Once this box reads "GUI Scripts" you can navigate to the directory on the MTS/Citrix Server where the WinRunner script resides. It should appear in the window with the WinRunner icon (if the icon in the main window is a yellow folder, check the Files of Type box and make sure it says GUI Scripts.) Select the script so that it appears in the File name: box and click Open. Once the script is displayed in the Controller, it should appear in blue type. If it appears in red type delete it and try again.

At this point, if you followed these instructions, your Controller will show one Group Name which will be the same name as the script. The Script Path column will display the script we just connected, including it's path. Under the Quantity column there will be a "1" (1 virtual user in the group) and under the Load Generators column it will read "localhost". All of this information should be blue. If it is red, delete the whole line and try again.

2) Edit the Group Name. You can edit the group name by selecting it and typing a new name. Don't choose an old group from the drop down list -- it will bring it's old script with it.

3) Correct the number of virtual users. Select and change by typing.

4) Set up the Load Generators. By way of explanation for the setup of the load generator field, remember these 3 key points:

The load injector box for an MTS/Citrix situation is the MTS/Citrix Server. WinRunner can only run 1 user at a time. You already set up multiple MTS remote sessions (or Citrix ICA's) from the MTS/Citrix

Client box(es).

Open the Load Generators wizard by clicking the Generators button on the Design tab. Delete the localhost entry (select the row, press the Delete key). In the first field in the Name column, type the IP address of the MTS/Citrix Server, type a colon, type 1:

199.99.99.99:1

Repeat this entry, changing the value of the 1 to 2, etc. until you reach the number of virtual users you need for the test. Figure 6 shows 4 Load Generators. (In this example, if the test will be run with one MTS/Citrix Client box, it should have 5 open sessions. If it is to be run with 2 MTS/Citrix Client boxes, each of them should have 3 open sessions.)

Figure 6: Putting the MTS/Citrix server sessions in the Load Generator wizard in the LR Controller.

Close this window when you have enough Load Generators. You will be returned to the Design tab, which will still show the value "localhost" under the Load Generator column. Don't worry about this, we are about to change it.

5) Setting up the Virtual Users. Click the Vusers button on the Design tab. This will open the Vusers window, which will show all 4 virtual users with the localhost load generator. Select the first field under the Load Generator column. The down arrow will appear. Choose the first Load Generator. Repeat this until all of your virtual users have one distinct load generator session:

Figure 7: Setting up the Vusers with the Load Generator MTS/Citrix sessions.

6) Testing the Session Connections. If everything is working properly the Controller will be able to initialize each virtual user. This process is displayed in the Status field of the Vuser dialog box as a transferring of the LoadRunner "script" to the MTS/Citrix Server, initializing and then putting the virtual user into the "Ready" state. Right click the vuser (or vusers) and select "Initialize Vuser/s" from the menu.

Run the Test

At this point you are ready to run the test. Select the vusers again and launch them, or create a schedule in the Controller. The results and analysis will work just as they would for any other test from the LoadRunner controller.

Database Test of MTS/Citrix Application using LoadRunner

Testing the database that is associated with a client/server application can be handled within the MTS/Citrix environment or it can be handled by working outside the MTS/Citrix environment. Either way, the solution is a LoadRunner test because there is no GUI. The reason for testing within the environment is to simulate the behavior of the MTS/Citrix server for a specific number of sessions. In other words, the MTS/Citrix server will have limitations with respect to the number of sessions it can handle and the number of selects and inserts that it can pass to the database server. If you need to test the database without these limitations, the test can be set up outside the MTS/Citrix environment.

Database Test within MTS/Citrix Environment

To execute a database test within the MTS/Citrix environment, open a session to the MTS/Citrix server, and launch LoadRunner's Vugen on the MTS/Citrix server. Record a LoadRunner database script against the application, and do the usual debugging, error handling, etc. Save the LoadRunner script on the MTS/Citrix server.

When you are ready to run the database test, follow all of the instructions in the "Setting Up the Test Machines" section of this document except those that specifically refer to WinRunner. You will need client machines with MTS/Citrix sessions open against the server and you will run the Controller software from a separate machine. The basic difference will be that the script you will attach to the scenario will be a LoadRunner database script rather than a WinRunner GUI script.

Database Test outside MTS/Citrix Environment

In order to conduct a load test outside the MTS/Citrix environment, it will be necessary to install the application as a normal fat client on a local machine. This will include the database connectivity software (Sequel Server, Oracle, etc.). Once the application "works" from the local machine, which will also need to have LoadRunner installed, you can record and execute the test as you would any other database load test.