FTR Advanced/CitraTest Best Practices
Contents
Introduction..................................................................................................................................... 3
1. Verify configuration and integration into the FMS ..................................................................... 3
2. Create and run scripts on the same machine.............................................................................. 3
3. Captured images should be as small as possible......................................................................... 4
4. Manually create the CitraTest scripts.......................................................................................... 4
5. Use the AppStart function to start applications .......................................................................... 5
6. Maximize Applications after AppStart......................................................................................... 5
7. Close the application ................................................................................................................... 5
8. Use “synchronization” steps ....................................................................................................... 6
9. Create and test a FTR script containing the CitraTest script ....................................................... 7
10. Use the restore desktop features of CitraTest and FTR ............................................................ 8
11. Disable the screensaver, enable autologon and schedule automatic reboots ......................... 9
12. Trouble shooting and common playback problems ................................................................ 10
November 14, 2011
v1.1
Page 2 of 10
Introduction
CitraTest is an effective and robust method of scripting applications. The learning curve is relatively
short so CitraTest can be mastered in a few hours if the best practices are followed.
1. Verify configuration and integration into the FMS
Before deploying your scripts, it is advisable to ensure that the environment is correct by deploying
and running a test script. To do this, create a quick FTR script, publish it, create an agent on the
Foglight Management Server (FMS) and configure it to run the script: As User. The script can be as
simple as navigating to a website or even About:Blank. The goal is to ensure that the script will run
and return results thereby verifying the configuration and integration.
2. Create and run scripts on the same machine
To eliminate as many variables as possible, the creation and playback environments should be
identical.

Agent Machine - The development machine should be configured as a Foglight agent machine
and the agent should be started and stopped as necessary for testing. The creation and
deployment of test should all be done on the agent machine which is separate from the Foglight
server.

Run as User - When configuring the agent properties, scripts should be set to run As User and the
user specified should be the same as the user that was logged on during script development.

Remote Access - Another important step keeping the creation and playback environments
identical is to NOT use remote access or terminal services. While these may seem to provide
identical environments, there can be subtle differences that affect playback and cause problems
that can be difficult to diagnose.
If it is not possible to work directly on the development machine, a remote control program that
controls the default desktop (as opposed to creating a second desktop environment) should be
used. DameWare Mini Remote Control is easy and inexpensive. A free trial is available at
http://www.dameware.com/products/dmrc/. If another remote control product is used, it is up
to the user to ensure that the product does not alter the display properties of the system when
connected/disconnected. If it does alter the display properties, a script that plays back properly
when remotely controlled may not play back correctly when the remote connection is
terminated.
Note:
In Citrix applications are published with a “Maximum color quality” like:
 Better Appearance (32 bit)
 Better Speed (16 bit)
 256-color (8-bit)
Due to network and/or system load conditions, it has been found that applications published
with “Better Appearance (32 bit)” may change to the “Better Speed (16 bit)” setting.
This has of course impact on the FTR-A/CitraTest scripts. A workaround is to check for either the
16- or 32-bit image, or by creating an extra 16-bit published application for FTR-A/CitraTest
playbacks.
November 14, 2011
v1.1
Page 3 of 10
When using DameWare Mini Remote Control, configure the settings to ensure that the display will be
consistent.
3. Captured images should be as small as possible
Make captured images as small as possible while ensuring that they will be a unique image for the
script to identify when running. This will reduce the impact of display changes to script.
For Example, this image of the Quest Software logo is accurate, but much larger than needed.
This image provides a much smaller unique image to use to identify the logo.
4. Manually create the CitraTest scripts
While CitraTest has a record feature, manual scripting using the “Capture image/Insert script
function” method will result in scripts that are more reliable and easier to debug. After a short
learning curve, manual scripts can be created almost as quickly as recorded scripts. When creating a
new CitraTest script, these steps should always be taken:
1.
2.
3.
4.
Know precisely what each step in the script will be before starting
Create a new folder for the script
Create a new script In CitraTest
Write comments and code that will launch and then shut down the application and test by
running the script (see topics below)
5. Write comments for each action needed in the script.
6. Code and test the actions commented in step 5.
November 14, 2011
v1.1
Page 4 of 10
5. Use the AppStart function to start applications
The first thing to accomplish in many CitraTest scripts is starting the application. While it is tempting
to double click desktop icons or use the Start menu to launch an application, the AppStart function is
easier and more reliable. (Note: AppStart will not work when the application is launched inside a
Citrix/Terminal Services Client).
1. Launch and maximize the application to be monitored. If the application uses a web browser, set
the browser homepage to About:Blank.
2. Use CitraTest’s Image Capture to grab a portion of the title bar, and save the image. For
example, if scripting a Foglight login page, capture and save an image from the login screen.
3. Select AppStart from the CitraTest Scripting menu. Choose the executable that will launch the
application and the image of the title bar that will be used to verify the application is running.
Note: The path to the executable must be the same on all agent machines. At the end of the
AppStart wizard a code snippet will be inserted into the script. If the application takes a few
seconds to load, it is advisable to add a Delay() after the function call.
4.
Compile and run this script. Don’t worry about any other scripting until this script runs.
6. Maximize Applications after AppStart
Maximize the application to ensure that the window will match the script development environment
(certain buttons, etc. may not be visible when required).
1. When the application is not maximized, capture and save an image of the window buttons – be
sure to set the image click point on the maximize button.
2. Add a click on image command to the script
7. Close the application
Now that the script launches the application, add code to close the application.
1. Use the File menu->Exit or Close. If the app has a File menu the best way to close it from the
script logic is to use keystrokes for the menu hotkeys. For example:
KeystrokeStringVK ("VK_MENU", KEY_PRESS)
KeystrokeString ("f")
KeystrokeString ("x")
or
KeystrokeVK ("VK_MENU", KEY_DOWN)
KeystrokeVK ("VK_F4", KEY_PRESS)
KeystrokeVK ("VK_MENU", KEY_UP)
2. Click the window “x” close button. Capture an image of the window close button and use
ClickOnImage. Be sure to set the image click point on the close button.
November 14, 2011
v1.1
Page 5 of 10
8. Use “synchronization” steps
A synchronization step tells the script that it is Ok to proceed to the next step. This prevents the
script from getting “ahead” of the app-under-test, e.g. entering keystrokes BEFORE a window has
appeared on the screen. The WaitForImage function is typically used for this purpose.
The finished script should look like this:
Option Strict On
Option Explicit On
Module Script
Sub StartScript()
InitScript
'Launch IE to Foglight login page
returnStatus = AppStart
("""C:\Program Files\Internet Explorer\iexplore.exe""
http://stlvmta01:8080", "FglLoginPg.bmp")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
Delay
("3")
'Maximize IE
returnStatus = ClickOnImage("MaximizeButton.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT,
"NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
'Login to Foglight
returnStatus = ClickOnImage("UserName.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
KeystrokeString ("foglight")
returnStatus = ClickOnImage("Password.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
KeystrokeStringEncryptEx("147170497363252014fa7fae217e273913")
returnStatus = ClickOnImage("LoginButton.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
'Click on the End User Overview link
returnStatus = ClickOnImage("EndUserOverview.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT,
"NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
'Wait for the End User Overview link
returnStatus = WaitForImage("EndUserResult.bmp", STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
November 14, 2011
v1.1
Page 6 of 10
'Log out of Foglight
returnStatus = ClickOnImage("SignOut.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
'Close IE
returnStatus = ClickOnImage("CloseButton.bmp", LEFT_BUTTON, 1, STANDARD_TIMEOUT, "NONE")
If returnStatus <> SUCCESS Then
AbortScriptEx (SCRIPT_FAIL)
Exit Sub
End If
End Sub
End Module
9. Create and test a FTR script containing the CitraTest script
Once this script is running in CitraTest, create a new FTR script and insert a CitraTest instruction using
the Insert Wizard.
1. Create a new FTR script
2. Insert a CitraTest Script Instruction
3. Set the CitraTest executable according to the directories used in CitraTest.
4. Run the FTR script.
5. Once this runs correctly, publish it to the Foglight server, configure the Service Model to include
the new script, and start the Transaction Player agent.
6. Once the basic script is deployed and running successfully, write the rest of the script, insert
timers, etc.
7. When the script has been completed, replay the script in the Transaction Recorder and republish
to the Foglight server. Stop and restart the Transaction Player to start monitoring the new script.
November 14, 2011
v1.1
Page 7 of 10
10. Use the restore desktop features of CitraTest and FTR
When a script fails, the application is left in an unknown state. To ensure a consistent launch point
and avoid other problems such as multiple versions of the application running, restore desktop is
advisable in many situations. CitraTest and FTR each have the ability to restore the desktop to the
state prior to script execution, and both should be set to ensure a consistent script startup state.
1. In CitraTest choose Playback Options from the play back menu and check the “Restore desktop to
the script start time state” option. This will close any windows that were not open when the
script launched.
2. To enable FTR’s restore desktop feature, set the Restore Desktop option to True in the CitraTest
instruction properties.
Note:
There are certain applications, (often within Citrix), where closing the window or killing the
process creates problems for the next playback. For example, closing a Citrix client window
leaves the session open on the server, which often causes the next playback to fail. A formal
“Citrix Log Off” will result in much more robust playbacks.
In such cases, the Restore Desktop property in the FTR instruction should be left at False. Logic
should be added in CitraTest to the AbortScript function and/or at the beginning of each script
that will ensure the application is shut down properly. For example, at the beginning of the Citrix
script, use the ImageExists function to check for the preexistence of the Citrix client, and if it
exists click the Start menu->Shut Down in the Citrix client window and execute a clean Log Off.
November 14, 2011
v1.1
Page 8 of 10
11. Disable the screensaver, enable autologon and schedule automatic reboots
To ensure 24x7 operation disabling the screensaver is required, but also a weekly reboot is
recommended to complete for example windows updates or to kill hanging applications.
After the reboot auto logon needs to be enabled, otherwise the scheduled FTR-A (CitraTest) script
will fail to start.
The following sample script (.cmd or .bat file) can be scheduled (weekly or daily) via the Windows
Task Scheduler for this purpose:
@echo off
REM
Name:
REM Description:
REM
REM
REM
REM Version Who
REM ------- --REM
1.00 ???
scheduledReboot.cmd
Command file to manage the scheduled reboot, including various settings
to disable the screensaver and enable Windows auto logon.
All to support a robust 24x7 operation of FTR-A (CitraTest)
Date
----------dd Mon YYYY
Comment
--------------Initial version
SET MYDIR=C:\Windows\Temp
SET LOG=%MYDIR%\scheduledReboot.log
echo Setting registry values to enable autoLogon >> %LOG% 2>&1
reg ADD "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
reg ADD "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
reg ADD "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
reg ADD "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
reg ADD "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
/v
/v
/v
/v
/v
DefaultUserName /d <userName> /f
DefaultPassword /d <passWord> /f
DefaultDomainName /d <domain> /f
AutoAdminLogon /d 1 /f
ForceAutoLogon /d 1 /f
echo Setting registry values to disable the screensaver >> %LOG% 2>&1
reg ADD "HKCU\Software\Policies\Microsoft\Windows\Control Panel\Desktop" /v ScreenSaveActive /d 0 /f
echo Starting scheduled reboot on %DATE% %TIME% >> %LOG% 2>&1
C:\WINDOWS\system32\shutdown -t 0 -r
>> %LOG% 2>&1
REM End of Script
NOTES:
 The script is provided as is. Use it at your own risk.
 The script requires elevated permissions (e.g. Local Administrator), and potentially different
group policy settings to allow for the various registry changes.
In case security policies prohibit the above solution, a partial alternative can be created by using the
CitraTest script logoff and logon features. Create for this purpose a single FTR script with 3 CitraTest
scripts embedded. The 1st to logon to the playback machine, the 2nd to start the application and
execute transactions as normal, and the 3rd to logoff again. See also appendix L of the CitraTest User
Guide for more details.
To periodically reboot the playback machine, a script (.cmd or .bat) still needs to be scheduled via the
Windows Task Scheduler.
November 14, 2011
v1.1
Page 9 of 10
12. Trouble shooting and common playback problems
1. Trouble shoot by watching the application playback on the physical console. For remote
locations, use DameWare, a VNC alternative or a VMware console.
The most common problem is that playback hangs or a WaitForImage()function call times out.
These problems are mostly related to different resolution and color depth settings between
recording and playback.
Sometimes image recognition is too fast and CitraTest starts with the next instruction too
quickly, without waiting for the complete window drawing. Improve synchronization by waiting
for another image, wait for two images (e.g. Left upper and Right down) or add Delay()
function calls.
2. Check the log files in:
<path>\Foglight_Agent_Manager\state\default\process\FTR\
agents\FTR\<version>\FTR_on_<hostname>\results
<path>\Foglight_Agent_Manager\state\default\process\FTR\logs\FTR\<version>\FTR
3. Create a support case (https://support.quest.com), give a short description of the problem and
upload a zip file of all below:
<path>\Foglight_Agent_Manager\state\default\process\FTR\
November 14, 2011
v1.1
Page 10 of 10