SetupSAFS.README

==========================================================================
Author: Carl Nagle
Update: May 31, 2013

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

Definitions:

Simple Install Accepting All Defaults:

1. Verify 32-bit Java and any other prerequisites per the Release Notes for your platform (WIN/MAC) from the SAFS download directories.
2. Download the appropriate SAFS Distributable (WIN/MAC) and extract to a known location.
3. Perform the install according to the Release Notes.
4. Optional: Configure JSAFS development environment, if applicable, per Setup JSAFS.
5. Optional: Configure IBM Rational Functional Tester per Setup Functional Tester
6. Optional: Configure SmartBear Test Complete per Setup Test Complete
7. Optional: Configure Android testing per Setup Robotium Remote Control
8. Optional: Configure Apple iOS testing per the SAFS Mac Release Notes.

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

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.5 or higher is recommended.

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

2. HOWEVER: SAFS and STAF will require a 32-bit Java JVM to use at runtime.

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

We now release SAFS with STAF V3.4.x 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.5 (can NOT be Java 1.6 or higher)
STAF V3.4.x		Java 1.5 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:

Older Java:	Sun Java Archives
Latest Java:	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 Platform Only)

For Windows: 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 Download Center

Assets for SAFS Framework install on Windows:

    SetupSAFS_WIN64.BAT           ------ Main Setup Script for 64-bit (and 32-bit) Windows
    STAF3410-setup-win32-NoJVM.exe ----- STAF InstallShield Installer (STAF V3.3.3)

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

Default Installation Destination Directories on Windows:

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

Windows 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

Windows Simple Install Accepting Default Install Directories:

1. Double-Click the SetupSAFS_WIN64.BAT script (for 32-bit and 64-bit Windows)
2. Optional: Configure IBM Rational Functional Tester per Setup Functional Tester
3. Optional: Configure SmartBear Test Complete per Setup Test Complete
4. Optional: Configure Android testing per Setup Robotium Remote Control

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.

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

Assets for SAFS Framework install on Mac (for Apple iOS):

Please consult the SAFS Mac Release Notes for your specific SAFS Mac distributable.

Verifying a successful SAFS install on Windows:

    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 IBM Rational Functional Tester, if applicable:

    C:\SAFS\Project\runRFTTest.BAT

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

    C:\SAFS\Project\Datapool\Logs

Verifying successful configuration of SmartBear Test Complete, if applicable:

    C:\SAFS\Project\runTCAFSTest.BAT

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

    C:\SAFS\Project\Datapool\Logs

Verifying successful configuration of Android SDK and SAFS/Robotium Remote Control, if applicable:

    C:\SAFS\samples\Droid\runDroidTest.BAT

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

    C:\SAFS\samples\Droid\Datapool\Logs

SAFS Project Directories:

C:\SAFS\Project contains a sample SAFS Project.  Your own product SAFS 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 older RRAFS)
• [ProjectRoot]\Datapool\Test

Following an install on Windows, there should be SetupSAFSProject.VBS script in the SAFS\bin directory.  This script can be placed in any directory intended as a new SAFS project directory.  Execute the script in the intended directory and it will create the default SAFS Project 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 in it.)  Remember, any BATch executables and INI configuration files copied may need to be edited to account for the new Project directory location.

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 of cscript on 64-bit systems is found at:

    %SYSTEMROOT%\SysWOW64\cscript.exe

  Install SAFS and STAF Version 3.4.x (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, 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.4.x (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, 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

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

Manual System DLL Placement\Registration:

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

Copy the following DLLs to <Windows>\System32--the "System" directory.
On 64-bit systems the "System" directory is in <Windows>\SysWOW64 for our 32-bit DLLs.
• C:\SAFS\bin\CWPHooker.DLL
• C:\SAFS\bin\ComponentFunctions.DLL
• C:\SAFS\bin\STAFWrap.DLL (only copy to overwrite in the "System" directory)

Execute the following DLL registration script
• C:\SAFS\bin\DDVariableStoreREGISTER.VBS

Edit custom install paths as necessary

Following a successful custom install to non-default directories, you may 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
    [safsroot]\Project\runTCAFSTest.BAT
    [safsroot]\Project\TCAFSTest.INI
    [safsroot]\samples\Droid\runDroidTest.BAT
    [safsroot]\samples\Droid\DroidTest.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