SetupSAFS.README

==========================================================================
Author: Carl Nagle
Update: Sep 16, 2010

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 (RFT)	A SAFS Engine for testing using Functional Tester by IBM Rational.
SAFS/TC (TCAFS)	A SAFS Engine for testing using TestComplete by AutomatedQA.
SAFS IBT (Pat.Pend.)	An embedded SAFS Engine for Image-Based Testing. (Patent Pending)
JSAFS (New!)	The Java API for embedding SAFS in custom frameworks and SAFS Advanced Runtime Development.

-------------------------------------------------------------------------------
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_WIN64.BAT 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 unless you have
      installed RRAFSPatch2010.01.14 (or later) for IBM Rational Robot.  Only the 2010.01.14 patch
      (and later) for RRAFS supports using STAF V3.

This SAFS README 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 unless you have
      installed RRAFSPatch2010.01.14 (or later) for IBM Rational Robot.  Only the 2010.01.14 patch
      (and later) for RRAFS supports using STAF V3.

IBM Rational Functional Tester Datastore Setup:

Once this SAFS setup has been completed, the tester can use the default SAFS\DatastoreJ project to take advantage of the "SAFS/RobotJ" engine. Note, however, this Datastore is not a fully functioning RFT Datastore. For example, a tester cannot readily add new scripts to this datastore.

Alternatively, you can create a separate RFT Project Datastore for use by SAFS. Refer to the instructions in SetupRFT.README to configure an alternative RFT Datastore, if desired.

Java Runtime Necessary

The 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.

It is important to note that 64-bit systems might have a 64-bit Java JVM installed. Testing has shown that we can install 32-bit SAFS and STAF using the 64-bit JVM, but SAFS and STAF will require a 32-bit Java JVM to use at runtime. SAFS batch files in the SAFS install directories, including those in the SAFS\Project space may need to be edited to point to the desired 32-bit JRE installed on the 64-bit system.

See cautions that follow...

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, including Java 1.5 and 1.6 or higher

For installs, 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

Don't forget, you may have to install a 32-bit JRE on 64-bit systems if one does not already exist. 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                        (default)
    %SYSTEMROOT%\SysWOW64\cscript  (32-bit version on 64-bit systems)

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 on Windows:

    SetupSAFS_WIN64.BAT           ------ Main Setup Script for 64-bit (and 32-bit) Windows
    SetupSAFS.WSF                 ------ Main Setup Script on 32-bit Windows only
    _SharedFunctions.VBS          ------ Functions shared by multiple scripts
    _SharedRationalFunctions.VBS  ------ Functions shared by SetupRationalClasspath.wsf
    SetupTSAFS.WSF                ------ Setup Script for TestComplete called by SetupSAFS
    ocr\setOCREnv.WSG             ------
    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.

Assets for SAFS Framework install on Linux:

    Please consult the Linux Install Readme for Linux-specific information.
    (This information is still in its early stages of development.)

Default Installation Destination Directories on Windows:

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

System 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
    TESTCOMPLETE_HOME <none>              TestComplete install directory
    TESSDATA_PREFIX   <none>              Tesseract OCR data directory

Simple Install Accepting Default Install Directories:

    1) Double-Click the SetupSAFS_WIN64.BAT script (for 32-bit and 64-bit Windows)
    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.

    SetupSAFS_WIN64.BAT

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 any directory you wish to create a new blank SAFS project in, executed, and it will create the default SAFS Project 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.


    -notcafs

          Do not process support for Automated QA Test Complete at this time.
          NOTE: the TCAFS engine may not function without this install.

    -noocr

          Do not process support for Image-Based Testing OCR. [C:\SAFS\ocr]

    -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:

Note: Any reference to "cscript" below must take into account that 64-bit Systems have two versions of cscript.exe. On 64-bit systems, you must invoke the 32-bit version of "cscript" for most operations.
The 32-bit version on 64-bit systems is found at:

    %SYSTEMROOT%\SysWOW64\cscript.exe

  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.)
  IBM Rational is changing the JAR naming convention constantly.  So JAR filenames in RFT V8.1
  and later may not be listed here!

    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

<Windows>\SysWOW64

C:\SAFS\bin\CWPHooker.DLL
C:\SAFS\bin\ComponentFunctions.DLL
C:\SAFS\bin\STAFWrap.DLL (only copy to overwrite in the "System" 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.