SetupSAFS.README

==========================================================================
Author: Carl Nagle
Update: Oct 09, 2009

Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php
==========================================================================
Simple Install, RRAFS & RFT, Java Requirements, WSH Requirements, SAFS Install, Verify Install, SAFS Projects, Custom Installs, Manual Setups

Definitions:

SAFS	Software Automation Framework Support
SAFS Driver	The tool that initializes, opens, parses, and routes SAFS test records to available SAFS Engines.
SAFS Engine	A keyword-driven automation tool capable of interpreting and executing SAFS test records.
SAFS/DriverCommands	A SAFS Engine for tool-independent Driver Commands
SAFS/RobotJ	A SAFS Engine for testing using Functional Tester by IBM Rational.
SAFS/TC	A SAFS Engine for testing using TestComplete by AutomatedQA.
SAFS IBT	An embedded SAFS Engine for Image-Based Testing. (Patent Pending)

-------------------------------------------------------------------------------
Simple Install, RRAFS & RFT, Java Requirements, WSH Requirements, SAFS Install, Verify Install, SAFS Projects, Custom Installs, Manual Setups

Simple Install Accepting All Defaults:

    1) Verify Java and WSH prerequisites
    2) Double-Click the SetupSAFS.wsf script
    3) Optional: Configure IBM Rational Software Datastore per SetupRFT.README

Now, on to "why you should read the rest of this first..."

Support for Rational Robot and Rational Functional Tester

This README attempts to detail your installation options for installing SAFS tool-independent pieces. These include STAF and SAFS services developed for tool-independent keyword-based test automation.

The installation also includes the pieces necessary to use IBM Rational Functional Tester (RFT) as a SAFS Engine available to IBM Rational Robot (RRAFS) or the tool-independent SAFS Driver (TID).

      If you intend to use RRAFS with SAFS then you MUST install STAF V2 and NOT STAF V3 when prompted.
      Rational Robot has not been refactored to work with STAF V3.

This information is separate from--and in addition to--the Setup info used to install the SAFS Framework for IBM Rational Robot (RRAFS). See the DDEngineSetup.htm doc for those separate installation instructions, if applicable.

Note: The separate install of SAFS is not necessary if you only intend to use the basic RRAFS Framework for Rational Robot and have no desire to use Rational Functional Tester or the new SAFS services with the RRAFS engine for Rational Robot.

Lastly, the RRAFS SetupRRAFS.wsf script allows the user to run this SAFS install by accepting the standard default installation options. The RRAFS install will ask the user if they wish to install SAFS and STAF to the default install locations. If you answer YES, SetupSAFS will be launched and perform the default SAFS install as part of the RRAFS install.

      When installing RRAFS, you MUST install STAF V2 and NOT STAF V3 when prompted.
      Rational Robot has not been refactored to work with STAF V3.

IBM Rational Functional Tester Datastore Setup:

Once this SAFS setup has been completed, the tester can make or configure a RFT Datastore to take advantage of the "SAFS/RobotJ" engine. Refer to the instructions in SetupRFT.README to configure the RFT Datastore.

Java Runtime Necessary

The additional SAFS installation requires that a Java runtime environment (JRE) is already installed on the target machine. For best results and ease of installation, a JRE version of 1.4 or higher is recommended.

There are known problems installing STAF versions less than V2.6.10 with Java 1.5 or greater.
There are known problems installing STAF V2.6.11 with Java 1.6 or greater.
Note, however, that these limitations are STAF installation issues only.
After STAF is installed, Java 1.6 or later can generally be used in the test environment for both STAF V2.x and V3.x.

We now release SAFS with STAF V3.3.3 support.
Support for STAF V2.6.11 is still available for backward compatibility with existing STAF V2.X infrastructure.

Please refer to the following to choose the Java version for the STAF install you intend to perform:

STAF V2.6.11		Java 1.4 or Java 1.5 (can NOT be Java 1.6 or higher)
STAF V3.3.3		Java 1.4 or higher

The JRE must be in the normal search path for the system. The following command typed at any command prompt should successfully list the version of Java JRE installed:

    java -version

You can download and install the appropriate JRE, if necessary, from:

Java 1.4 or 1.5:	Sun Java Archives
Java 1.6 or later:	Sun Java Downloads

You may also be able to use the JRE that is installed as part of Rational Functional Tester, if available.

Windows Scripting Host 5.6 or higher

Windows Scripting Host 5.6 or higher 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 following command typed at any command prompt should successfully list the version of Windows Scripting Host installed:

    cscript

While this should rarely be necessary, you can download and install WSH 5.6 or higher from:

Microsoft Windows Script Downloads

Assets for SAFS Framework install:

    SetupSAFS.WSF                 ------ Main Setup Script
    _SharedFunctions.VBS          ------ Functions shared by multiple scripts
    _SharedRationalFunctions.VBS  ------ Functions shared by SetupRationalClasspath.wsf
    SetupRationalClasspath.wsf    ------ The script to setup system CLASSPATH for IBM Rational tools
    SetupSAFSClasspath.wsf        ------ The script to setup system CLASSPATH for SAFS
    SetupSTAFClasspath.wsf        ------ The script to setup system CLASSPATH for STAF
    SAFSInstall.jar               ------ Java setup program for SAFS and STAF
    SAFSInstall.zip               ------ SAFS files to be installed
    STAF2611-setup-win32.jar      ------ STAF InstallShield Installer (STAF V2.6.11)
    STAF333-setup-win32-NoJVM.exe ------ STAF InstallShield Installer (STAF V3.3.3)
    (various README files)        ------ Important Information and Instructions

The install can begin from any directory, but all the above assets must exist in that directory.

Default Installation Destination Directories:

    SAFS  -  C:\SAFS
    STAF  -  C:\STAF

Environment Variables

Environment variables may be modified by this script. Prior to making any modification, the current value of the environment variable is saved in a "*_SAFSBAK" backup environment variable. Note, this backup only occurs once--the first time we detect that no backup has been done previously.

The affected environment variables and their backups are listed below:

    VARIABLE          BACKUP VARIABLE     PURPOSE
    ============      ===============     ==================================
    STAFDIR           <none>              Root install directory for STAF
    SAFSDIR           <none>              Root install directory for SAFS
    PATH              PATH_SAFSBAK        Search path for executables
    CLASSPATH         CLASSPATH_SAFSBAK   Search path for Java classes

Simple Install Accepting Default Install Directories:

    1) Double-Click the SetupSAFS.WSF script
    2) Optional: Configure RFT Datastore per SetupRFT.README

You can also launch the script from a command prompt. The command prompt must be pointing to the directory where the setup script and associated assets reside.

    cscript SetupSAFS.WSF

Verifying a successful SAFS install:

Following a successful standard install, you should be able to double-click or otherwise execute the program:

    C:\SAFS\Project\runTIDTest.BAT

This should run a simple SAFS Test and generate logs in:

    C:\SAFS\Project\Datapool\Logs

Verifying successful configuration of RFT, if applicable:

Following a successful configuration of RFT, you should be able to double-click or otherwise execute the program:

    C:\SAFS\Project\runRFTTest.BAT

This should run a simple SAFS Test with RFT and generate logs in:

    C:\SAFS\Project\Datapool\Logs

SAFS Project Directories:

C:\SAFS\Project contains a sample SAFS Project. Your own production test project location requires the same SAFS Project directory structure:

[ProjectRoot]\Datapool\Bench
[ProjectRoot]\Datapool\Dif
[ProjectRoot]\Datapool\Logs
[ProjectRoot]\Datapool\Runtime (* optionally needed for RRAFS)
[ProjectRoot]\Datapool\Test

* The Datapool\Runtime directory is used to store files like RRAFS.INI and other project-specific items we may introduce over time.

Following an install, there should be SetupSAFSProject.VBS script in the SAFS\bin directory. This script can be placed in a desired project's root directory, executed, and it will create the default SAFS subdirectory structure for you.

You can also just Drag-N-Drop the files and subdirectory structure from \SAFS\Project\*.* to your desired project's root directory. You don't copy the "SAFS\Project\" folder itself, just all the files and folders beneath it.

Custom Installation Options:

Both the WSH script and the separate Java installer accept command line options in support of custom installations. The script automatically invokes the Java installer with the provided options when applicable.

Installer Command Line Options:

    -silent  (future)

           All installs are "silent" (GUI-less) at this time.

    -safs 

          Allows the user to specify an alternate install destination.
          Ex: -safs "d:\AltSAFSDir"

    -staf 

          Allows the user to specify an alternate install destination.
          Ex: -staf "d:\AltSTAFDir"

    -nostaf

          Do not install STAF at this time.
          NOTE: SAFS STAF services and the SAFS/RobotJ engine will not function
          without STAF.

    -nosafs

          Do not install SAFS at this time.
          NOTE: SAFS STAF services and the SAFS/RobotJ engine will not function
          without the SAFS install.

    -norational

          Do not process support for IBM Rational tools at this time.
          This option is only for the WSH script, not the Java installer.
          NOTE: the SAFS/RobotJ engine will not function without this install.


    -noprompt

          Proceed with installation without prompting for approval?!
          (Used by Setup.vbs, which already has prompted for approval.)

     -installstafversion installstafversion

           If -nostaf is not present, this indicate the version of STAF to
           be installed. 2 for version 2.6.11 and 3 for version 3.3.3
           Ex: -installstafversion 3

     -removestaf installedstafdir stafMajorVersionTobeRemoved

           If you want to uninstall a previously installed STAF, you can use
           this option.
           installedstafdir indicate the installed directory like C:\STAF\
           stafMajorVersionTobeRemoved indicate the major version of STAF,
           2 for version 2.6.11 and 3 for version 3.3.3
           Ex: -removestaf "C:\STAF" 2

Sample Custom Script Installations:

  Install SAFS and STAF Version 3.3.3 (Version 3.3.3 is default) to alternate directories:
  -----------------------------------------------

    cscript SetupSAFS.wsf -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir"
    cscript SetupSAFS.wsf -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir" -installstafversion 3

  Install SAFS and STAF 2.6.11 to alternate directories:
  -----------------------------------------------

    cscript SetupSAFS.wsf -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir" -installstafversion 2

  Install SAFS, but do not install (re-install) STAF:
  ---------------------------------------------------

    cscript SetupSAFS.wsf -safs "D:\AltSAFSDir" -nostaf

Custom Java Installs:

It is possible to launch the Java installer directly and bypass the WSH script. If you do this, you will need to manually modify 'PATH' and 'CLASSPATH' Environment variables which the WSH script normally handles.

Sample custom Java Installations:

  Install SAFS and STAF 3.3.3 (Version 3.3.3 is default) to alternate directories:
  -----------------------------------------------

    java -jar SAFSInstall.jar -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir"
    java -jar SAFSInstall.jar -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir" -installstafversion 3

  Install SAFS and STAF 2.6.11 to alternate directories:
  -----------------------------------------------

    java -jar SAFSInstall.jar -safs "D:\AltSAFSDir" -staf "D:\AltSTAFDir" -installstafversion 2

  Install SAFS, but do not install (re-install) STAF:
  ---------------------------------------------------

    java -jar SAFSInstall.jar -safs "D:\AltSAFSDir" -nostaf

Manual Environment Variable Modification:

If you bypass the WSH script to perform the Java install or install STAF directly you will need to make the following changes to environment variables. In some cases, a Setup???Classpath.WSF script may exist in the C:\SAFS directory to handle these for you.

    STAFDIR     <staf root directory>

    SAFSDIR     <safs root directory>

    PATH:       append ;<staf root dir>\bin

    PATH:       append ;<safs root dir>\bin

    CLASSPATH:  append ;<staf root dir>\bin\JSTAF.jar

    CLASSPATH:  append ;<safs root dir>\lib\SAFS.jar

  For IBM Rational Robot(RC), Functional Tester(RFT):
  (Execute SetupRationalClasspath.WSF or manually enter these below.  Not all of these will
  exist for your installation (Functional Tester with or without Robot and
  Test Manager.)

    CLASSPATH:  append ;<path to> rational_ft.jar                    RFT

    CLASSPATH:  append ;<path to> rational_ft_core.jar               RFT 6.X

    CLASSPATH:  append ;<path to> com.rational.test.ft.core_XXX.jar  RFT 7.X & 8.X

    CLASSPATH:  append ;<path to> datapool_api.jar                   RFT 6.X

    CLASSPATH:  append ;<path to> rttssjava.jar                      RFT

    CLASSPATH:  append ;<path to> safsrational_ft_enabler.jar        RFT

    CLASSPATH:  append ;<path to> safsrational_ft.jar                RFT

    CLASSPATH:  append ;<path to> sqarobot.jar                       RC

Note: The SAFS JARs are in the SAFS\LIB directory, not the SAFS\BIN directory.

Manual System DLL Placement\Registration:

If you bypass the scripts which automate the install you likely need to manually place and\or register certain DLLs.

<Windows>\System32

C:\SAFS\bin\CWPHooker.DLL
C:\SAFS\bin\ComponentFunctions.DLL
C:\SAFS\bin\STAFWrap.DLL (only copy to overwrite in System32 directory)

C:\SAFS\bin\DDVariableStoreREGISTER.VBS

Edit custom install paths as necessary

Following a successful custom install to non-default directories, you will need to edit the path information in the following files if you wish to run the simple install sanity test:

    [safsroot]\Project\runTIDTest.BAT
    [safsroot]\Project\SAFSTID.INI
    [safsroot]\Project\TIDTest.INI
    [safsroot]\Project\runRFTTest.BAT
    [safsroot]\Project\RFTTest.INI

Once these are correct, you should be able to double-click or otherwise execute the program:

    [safsroot]\Project\runTIDTest.BAT

This should run a simple SAFS Test and generate logs in:

    [safsroot]\Project\Datapool\Logs

RFT Datastore Setup (Reminder):

Did I mention? Once this SAFS setup has been completed, the tester can configure their IBM Rational Functional Tester Datastore to take advantage of the new SAFS framework. Refer to the instructions in SetupRFT.README to configure the Datastore.