========================================================================== Author: Carl Nagle UPDATED: Apr 18, 2007 Copyright (C) SAS Institute General Public License: http://www.opensource.org/licenses/gpl-license.php ==========================================================================Remember: "RobotJ", "XDE Tester", and "Functional Tester" are names for the same IBM Rational test tool as habitually (re)named by IBM Rational. We collectively refer to all of these as "RobotJ", or simply "RJ" in much of our documentation and class names. (After all, we can't continuously rework all our documentation and class implementations just because IBM Rational has an identity problem.)
Backup selected customized files before installation:
If you have never installed RRAFS or SAFS before, then this doesn't apply to
you.
If you have previously installed but never modified any of the files then this doesn't apply
to you. Still, you may want to review the mentioned files "just in case".
Affected customizable files from previous releases:
If you have taken advantage of any of the customization capabilities of this framework, then you must take some simple precautions prior to installing this new release. Installing a new version of the framework will install new, default versions of these files. Failure to perform any of these prescribed backups may erase your previous customizations. Hopefully, you have backed them up somewhere already as part of your normal ongoing activities...You have done this, right?!
Uninstall Pre-2003.08 RRAFS Release:
Installations of RRAFS Release 2003.01.27 (Jan 2003) and earlier installed via the Windows Installer .MSI need to be uninstalled before installing this new release. You must do this to avoid unexpected backward versioning that can occur if the Windows Installer update or repair feature is ever invoked.
RRAFS Release 2003.08.27 (Aug 2003) and later do not have this uninstall requirement as we implemented the ability to patch and install on top of releases using different technologies.
To uninstall these older releases, uninstall "SAFS Engine for Rational Robot" from the Windows Control Panel "Add/Remove Programs" application if present.
Future releases of the framework will not have this problem as we will have the ability to patch and install on top of releases using Scripting technology. If you manually installed the engine previously, you should not need to delete your existing installation. Manual installation and the new Installer will simply overwrite existing files. Instructions for manually installing the engine are at the end of this document.
Basic Install Steps if Accepting all Defaults:
Now, on to "why you should read the rest of this first..."
Install Java Runtime Necessary for SAFS Framework.
The additional SAFS installation requires that a Java Runtime Rnvironment (JRE) is already
installed on the target machine. For best results and ease of installation, a JRE version of
1.4.2 or higher is recommended.
Note: The automated install of old STAF versions (before 2.6.10) will fail with Java V1.5.
However, Java V1.5 should work fine once the STAF install with a lesser version of Java
is successful. This has not been evaluated. We now distribute STAF version 2.6.10
so new installations with this version of STAF should have no problems using and installing
with Java 1.5.
The JRE must be in the normal search path for the system. The install scripts now check this automatically. You can check this manually using the following command typed at any command prompt:
java -version
The command should list the version of JRE installed. You can download and install a JRE if necessary from the Java Sun Site
You may also be able to use the JRE that is installed as part of the IBM Rational TeamTest, IBM Rational XDE Tester or Functional Tester if the version is high enough.
Windows Scripting Host 5.6 must be installed and available via the normal system search path for the install script to run. STAF and the SAFS pieces can be installed manually without the script, but the script can automatically error-correct important values and set environment variables that the separate Java installs cannot.
The install scripts now check this automatically. You can check this manually using the following command typed at any command prompt:
cscript
The command should list the version of Windows Scripting Host installed. You can download and install WSH 5.6 if necessary from Microsoft Windows Script Downloads
The RRAFS engine installation uses simple Scripting technology. It includes everything you need to use the engine with the latest version of Robot. Even compiled versions of all the core libraries are included. You can download the installation from our SAFSDEV Project FileList Page.
Consult SetupSAFS.README to proceed with additional steps necessary to take advantage of the many new features provided by the shared SAFS Framework.
If necessary, you can instead perform a manual install. A manual install requires extra install steps that are prone to human error. Manual installs are not recommended, but not terribly difficult.
Further Setup is necessary for:
Rational Robot Configuration
In order to use the Rational Robot implementation of the engine there are a few
settings that should be made in Robot. In addition, the routines currently expect
a specific directory structure to exist in each of the projects that intend to
make use of the engine.
*Required* Robot Playback Option Settings:
Recommended Playback Options:
The RRAFS engine has thus far proven very robust. Low settings for command and keystroke delays have not adversely affected playback accuracy in the limited number of applications that have been tested with it. Thus, you may be able to set Robot's playback delays extremely low (less than 10 milliseconds) or even to 0. These delay settings can be found in Robot's Playback Options dialog.
Recommendations would be to start with no delays ( 0 milliseconds ). If your tests experience no inexplicable playback problems then you can keep these settings. However, if playback experiences problems with object clicking or other activities that might be attributable to Robot running too fast, increase the delay settings to see if that resolves the problem. But remember, there can be other causes to playback errors. If larger delays do not fix these problems, don't forget to go back and set your delays to their original low settings. This will help improve the performance of your RRAFS tests.
Disable Unnecessary Extensions:
To significantly improve performance, you should disable all unnecessary extensions in Robot. You do this via Robot's Tools->Extension Manager dialog. Disable all extensions you do not need. You may need to restart Robot for the changes to take affect.
Required Robot Project Subdirectories:
* The Datapool\Runtime directory is used to store project-specific RRAFS.INI files and other project-specific items we may introduce over time.
Following an install, there should be SetupSAFSProject.VBS script in the DDE_RUNTIME install directory and in SAFS\bin (if installed). This script can be placed in a project's root directory, executed, and it will create the default directory structure for you.
You can also just Drag-N-Drop the files and subdirectory structure from \SAFS\Project\*.* to your project's root directory. You don't copy the "SAFS\Project\" folder itself, just all the files and folders beneath it.
The RRAFS.INI configuration file actually lets the user configure the framework to use alternate locations for the Bench, Dif, Logs, and Test directories--among other things. The Datapool\Runtime directory is OPTIONAL only as long as you do not intend to place a version of the RRAFS.INI file in that location. If you do intend to deploy a project-specific version of RRAFS.INI, then it must be placed in the <Project>\Datapool\Runtime location and that directory cannot be "moved" to any alternate location.
By default, a "global" copy of the RRAFS.INI exists in the DDE_RUNTIME directory (Program Files\Rational\Rational Test\sqabas32) where all the source was installed. This copy affects all projects accessed by the local machine. Settings placed in a project-specific Datapool\Runtime RRAFS.INI will override the "global" settings in DDE_RUNTIME.
Set Windows Environment Variables:
The RRAFS.INI file and other changes have removed most requirements for Environment Variable settings for RRAFS. However, the shared SAFS Framework and STAF each have one Environment setting noting their root install directories.
These root install directories are:
Setup Development Environment
If/How/Where to Setup and Build a RRAFS development environment:
The RRAFS release ZIP includes everything you need to use the engine with Robot. Even compiled versions of all the core libraries are included. If you don't intend to add new functionality, then you may not need to setup a development environment and you should not have to compile the code.
Of course, if Robot complains about the compiled code format when you attempt to execute a test then you might need to compile the source SBLs with your version of Robot.
If you are using an incompatible version of Robot, you may have to create a development project and compile all the libraries to work with your version. You will also need to create a development project if you are planning to develop new functionality or customizations for the engine.
To do this, Create a separate Rational project. This one will be your *DEVELOPMENT* project--the one you will use to build the engine (and/or enhance it so that you can pass that on to SAFSDEV and the rest of the world :)
This project should not be used for anything other than building, enhancing, and testing the engine. It is not recommended for production testing of another application.
Next, UnZIP/Extract the RRAFS release ZIP file into the project's .\TMS_Scripts\SQABas32 directory. Only the *.SBL and *.SBH files need to be extracted into this directory.
You must *NOT* run the "SetupRRAFS.wsf" script from this project directory!
You will then need to do a batch compile in Robot (File->Batch Compile) of all SQABasic library source. If you make changes that you want available to all projects, then those changes and the associated compiled *.SBX files should be moved or copied to the DDE_RUNTIME location where the Rational product is installed. Changes are only local to that project until they are copied or moved to the DDE_RUNTIME location.
Once changes are copied or moved to your DDE_RUNTIME location, ALL projects accessed by this machine will find the modified files in this location. The modified files must also be copied (dragon drop?) to each Robot machine that is to run with the modifications. You only have to modify/build once on one machine. Then just copy to all other machines that need it. The other machines must have completed the initial RRAFS install and the other setup described at the top of this document.
This provides a neat development advantage. All projects can use and run a PRODUCTION version of the engine from the DDE_RUNTIME directory. Your special DEVELOPMENT project can be used to play with, modify, and enhance the version in DEVELOPMENT without impacting the PRODUCTION version. And you don't have to do anything special to take advantage of this. Robot always looks for files in the active Project's sqabas32 directory before it goes looking in your DDE_RUNTIME directory. So it will find modified development files before it will find the production DDE_RUNTIME versions.
Note: Users who have disabled the Repository or Project SQABas32 directory by specifying a path to a "common" directory will either have to temporarily disable this setting or use that common directory to build the engine. They will then also have to make their own determination as to whether they want to install the engine files to each machine's DDE_RUNTIME directory, or leave it in the "common" directory. I have not used this type of setup but imagine you loose the advantages of separate DEVELOPMENT and RUNTIME environments as discussed above.
Manual Installation Instructions:
These instructions are for those folks who need to manually install a release. This is generally only necessary if you do not have access to and/or are not allowed to use Microsoft's Scripting technologies. Manual installs are not recommended, but not terribly difficult. Use the Scripting technology whenever possible.
1. Download the latest RRAFS release ZIP file.
2. UnZIP/Extract "All Files" into your Rational install directory C:\Program Files\Rational\Rational Test\sqabas32 (This is a.k.a. the DDE RUNTIME location.)
3. Move the following files from your DDE_RUNTIME directory into your System Folder. This is often [Windows Dir]\System32.
4. Register the DDVariableStore.DLL extracted into your DDE_RUNTIME directory. This is done from a command line with regsvr32:
- CWPHooker.DLL
- STAFWrap.DLL
- MSXSL.EXE
regsvr32 "[path to DLL]\DDVariableStore.DLL" [Enter]
There is also a DDVariableStoreREGISTER.VBS script you can double-click to do this.
5. The following items need to be installed to take advantage of the ever-growing XML features of the engine. However, they do not need to be reinstalled for every release. Check with Microsoft or your system administrator because you may have these installed already depending on the version of your operating system.
- If necessary, download and install the Microsoft XML Parser from Microsoft XML Core Support. More than likely you don't need to do this.
- Optionally download/copy Microsoft's XSL Processor (MSXSL.EXE) and place it in your System Folder directory. (MSXSL.EXE is an addon that probably does not come as part of any Microsoft operating system. You will only need this if you plan to execute any of our XML transformations for documentation or XML log reporting. An older version of this file is included in the DDE_RUNTIME location extracted from the RRAFS release ZIP file.)
6. Consult SetupSAFS.README to proceed with additional steps necessary to take advantage of the many new features provided by the shared SAFS Framework.
7. Enjoy!
SAFSDEV Web and SAFSDEV Project on SourceForge.net