SetupRFT.README

==========================================================================
Author: Carl Nagle
UPDATED: Oct 08, 2015

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 Functional Tester tool. We historically referred to all of these as "RobotJ", or simply "RJ" in much of our documentation and class names.

The tool is now most often referred to as, Functional Tester or simply "RFT".

Configure for Execution ,  Use with TID ,  Configure for Development

1. STAF and SAFS Required:

   These instructions assume the tester has already installed STAF and SAFS services via the SetupSAFS script (or alternative methods).  If this is not the case, please refer to the SAFS for Windows Release Notes for information on the SAFS setup procedure.

   Users are encouraged to install the *latest* SAFS Snapshot or Overlay available.  Read and follow any additional instructions provided with the Snapshot or Overlay.

   The SAFS/DriverCommands and SAFS/RobotJ engines will not function
   if STAF and associated services are not properly installed.

   We will not attempt to duplicate information on setting up RFT for general testing.  Information for creating a Project and other tool configuration information can be found in RFT's User's Guide and other references available from RFT's Help menu.

   The RFT project in the SAFS 'DatastoreJ' subfolder is just a bare bones project that will NOT work for developing your own custom RFT-based scripts.  It will work for pure SAFS/RFT testing with no custom scripts, however.

   If you intend to have your own RFT scripts, or if you intend to use RFT Object Maps with your SAFS tests, then you must create a valid RFT Project then configure it as descibed below for your production testing.

   With RFT V8 and later, the project setup requirements are significantly simpler than previous versions of RFT.

   ---

   Back to Top ,  Use with TID ,  Configure for Development

2. Configure RFT Project for simple SAFS Execution:

   If all you want to do is run the SAFS/RobotJ engine then preparing a RFT Project requires these steps which are discussed in more detail immediately following:

   • Use the C:\SAFS\DatastoreJ RFT datastore,  OR
   • Create/Enable your own Project datastore.
   • Run the RFT Test Enabler (if needed)

   Now the Details:

   Note different versions of RFT behave very differently and have different project repository setup requirements.  Unfortunately, it is not within the scope of this document to hit them all.  We will focus on what works for RFT V8 below.

   Assets provided by SAFS for an RFT project should be located in C:\SAFS\DatastoreJ or, in extreme circumstances, may need to be extracted from C:\SAFS\lib, SAFS.JAR, or SAFSRATIONAL_FT.JAR.

   • Populate one of your existing RFT V8 Project / Create a RFT Datastore:
     • Copy the following files from the C:\SAFS\DatastoreJ directories:
       • <projectroot>\TestScript.testsuite
       • <projectroot>\resources\TestScript.rftdef

     • Delete any other (outdated) references to TestScript and TestScriptHelper, if present.
       • There should be no TestScript.java, no TestScript.class
       • There should be no ...\resources\TestScriptHelper.java, no TestScriptHelper.class

     Note: TestScript.rftmap should be ensured to stay in <projectroot>\resources\ if SAFS-based scripts need to use RFT Object Map objects.   Refer to Using RFT Object Maps with SAFS.

   • Enable a RFT datastore

     To execute your own SAFS tests, you run SAFSDRIVER with an argument, your SAFSDRIVER configuration file, in which various options are defined. Those information tells SAFS where and how to load the tests, launch SAFS/RobotJ engine and etc.

     One of the options indicates the RFT datastore you created:
     [SAFS_ROBOTJ]
     DATASTORE=<projectroot>\DATASTOREJ     (Here it is!)
     

   • A simple SAFSDRIVER configuration file for executing SAFS tests using RFT:

     C:\mySAFSTest\helloSafs.ini
     -------------------------------------------------------------------------------------------
     [SAFS_DRIVER]
     DriverRoot="C:\safs"                        (SAFS's home)
     
     [SAFS_PROJECT]
     ProjectRoot="C:\mySAFSTest"                 (the root of your SAFS test project)
     
     [SAFS_TEST]
     TestName="helloSafs"                        (start from this SAFS script: helloSafs.CDD)
     TestLevel="Cycle"                           (Cycle file, suffixed with '.CDD')
     CycleSeparator=","                          (the delimiter to seperate different fields in a same line of SAFS script)
     CycleLogName="helloSafs"                    (the file name of the SAFS log produced by running this SAFS script, the log file shall be output to C:\mySAFSTest\Datapool\Logs)
     CycleLogMode="TEXTLOG"                      (the format of the SAFS log producted by running this SAFS script)
     
     [SAFS_ROBOTJ]
     AUTOLAUNCH=TRUE                             (autolaunch the hook of SAFS/RobotJ engine)
     DATASTORE=C:\mySAFSTest\DATASTOREJ          (the RFT Datastore your test script intends to use)
     TESTDOMAINS="Java, Html"                    (domains to search)
     
     
     [SAFS_ENGINES]
     First=org.safs.tools.engines.SAFSROBOTJ     (SAFS/RobotJ engine defined to be used)
     --------------------------------------------------------------------------------------------
     

     • The command to execute SAFS tests with the SAFS Driver:

       %SAFSDIR%\jre\bin\java -Dsafs.project.config="C:\mySAFSTest\helloSafs.ini" org.safs.tools.drivers.SAFSDRIVER

       Via above command, SAFS takes 'C:\mySAFSTest\DATASTOREJ' as the RFT datastore, and runs the SAFS tests in 'C:\mySAFSTest\Datapool\helloSafs.CDD'.

   • Associate or Disassociate RFT with Test Manager

     RFT may be configured to associate itself with Test Manager and a Test Manager repository.  If you are not associating with a Test Manager repository and not using Test Manager logs then you may need to change Logging and Playback settings.

     SAFS can now change these automatically, so you can skip these steps unless you have already encountered certain TSS Services ClassNotFoundExceptions.

     • Open Preferences via RFT's Window->Preferences menu.
       • Expand "Functional Test" to edit Logging and Playback options.
         (Some of these options may not be available or shown.)
       • Disable any Script Launch Wizards
       • Disable Prompt before Overwriting Logs
       • Disable Default Log Type to disassociate Test Manager.
         Many users choose to set "text" logging instead of the default.

   • Make sure RFT has enabled your environments for testing.
     • Select the Configure->Enable Environments for Testing menu.
     • Enable all environments you will be using for testing.
     • You may have to use the 'Search' capability to locate all possible environments.

   • If needed, execute the C:\SAFS\install\SetupRationalClasspath.wsf script to locate and add IBM Rational JAR files to the CLASSPATH.
     (The SAFS install does this for you.  You only need to do this if you bypassed the Rational install during the SAFS install, or if you recently upgraded RFT *after* the SAFS install.)

   • Verify SAFS RFT setup with SAFS Sample Project:
     • Locate and Run C:\SAFS\Project\runTIDTest.BAT
     • Log results in C:\SAFS\Project\Datapool\Logs\TIDTest.SAFS.txt should contain:

           OK    TIDTest Services all present and working.

     • Locate and Run C:\SAFS\Project\runRFTTest.BAT
     • Log results in C:\SAFS\Project\Datapool\Logs\RFTTest.txt should contain:

           OK    RFT ClearAppMapCache was successful.

   ---

   Back to Top ,  Configure for Execution ,  Configure for Development

3. To use with the Tool-Independent Driver (TID):

   Consult the documentation for the TID SAFSDRIVER for a more complete introduction to TID setup.   You can also review sample TID configuration (.INI) and batch (.BAT) files in the C:\SAFS\Project directory.

   The TID configuration file(s) would be a TIDTEST.INI and\or SAFSTID.INI file usually created and located in the root project directory as you can see in the C:\SAFS\Project samples.   Below we show only those settings that may need editing relevant to the use of RFT.   Other settings as required by the TID are not shown but are still necessary.

   The documentation specific to the RFT interface to the TID can be found in org.safs.tools.engines.SAFSROBOTJ.

   Sample TID INI settings:

   [SAFS_ENGINES]
   First=org.safs.tools.engines.SAFSROBOTJ
   
   [SAFS_ROBOTJ]
   AUTOLAUNCH=TRUE
   DATASTORE=C:\SAFS\DatastoreJ  (fullpath to the RFT Project root directory)
   TESTDOMAINS=Java,Html,Win,Net,Swt,Flex -- Enable your specific test domains only
   

   There is also this SAFS Quick Start Guide for using RFT with SAFS.

   ---

   Back to Top ,  Configure for Execution Use with TID

4. Configure RFT Project for SAFS Debugging and\or Development:

   Any RFT Project can be configured to run the engine, but each Project must be configured separately.  To actually develop new code or keywords for RFT or other Java-based engines, or to debug RFT test execution the user would have to prepare the RFT Project for development. Note: The Eclipse and\or IBM Rational IDE for Java development does not use the System \ CLASSPATH to locate class files and other resources.

   • Configure the system for debugging:
     • Put\Extract TestScript.java into root project directory.
       (You may have to extract it from SAFSRATIONAL_FT.JAR or another source.)
     • Configure Java Build Path to include references to JARS:
       • C:\Program Files\IBM\SDP\FunctionalTester\bin\rational_ft.jar
       • C:\STAF\bin\jstaf.jar
       • C:\SAFS\lib\JSTAF2.jar
       • C:\SAFS\lib\safs.jar
       • C:\SAFS\lib\jaccess.jar
       • C:\SAFS\lib\safsrational_ft.jar
       • C:\SAFS\lib\safsrational_ft_enabler.jar

       • There may be other JARs you must include from the SAFS\lib directory.
         For example, if using JSAFS you would want to include "safsmodel.jar"

       • Configure Java Build Path to include SAFS SOURCE JAR\ZIP\Files.
         (These are normally not included in a SAFS install.)

   • Run SAFS RFT TestScript in debug mode:

     Start STAF

     "Start->Programs->STAF->Start STAF"
     This may or may not be in QuickLaunch.  I'd place it there if I were doing this repetitively.
     CMD Window will open and remain.
     

     Start SAFS Services

     Run "SAFSStartupSAFSProject.BAT"
     Should be located in C:\SAFS\Project directory.   May need to be edited for your desired runtime SAFS Project location.
     4 CMD Windows should open and may immediately close.
     

     'Run' or 'Debug' RFT Project "TestScript"

     RFT Playback Monitor should open and remain.
     RFT and STAF are now connected via STAF SEMaphore events.

     (You may have to 'Reset Java Build Path' in your RFT Project's Properties if RFT does NOT have its internal JARS listed in the Java Build Path.)

     *** DO NOT SHUTDOWN STAF or STOP RFT TESTSCRIPT EXCEPT AS FOLLOWS ***

     Stop RFT TestScript interface to STAF

     Run "SAFSRobotJShutdown.BAT"
     Should be located in C:\SAFS\Project
     RFT will take 5-10 seconds to cleanup and shutdown.
     

     You can leave STAF and services running for additional RFT TestScript executions,
     but you will eventually need to:
     

     Shutdown STAF

     "Start->Programs->STAF->Shutdown STAF"

   • Configure the system for development:
     • Configure Java Build Path to include references to necessary JARS:
       (See the Environment Setup for Developers doc on GitHub SAFSDEV Core for latest info.)
       • C:\Program Files\IBM\SDP\FunctionalTester\bin\rational_ft.jar
       • C:\STAF\bin\jstaf.jar
       • C:\SAFS\lib\JSTAF2.jar
       • C:\SAFS\lib\bsh.jar (Abbot support)
       • C:\SAFS\lib\AutoItX4Java.jar
       • C:\SAFS\lib\clibwrapper_jiio.jar
       • C:\SAFS\lib\dom4j-2.0.0-ALPHA-2.jar
       • C:\SAFS\lib\jacob.jar
       • C:\SAFS\lib\javax.mail.jar
       • C:\SAFS\lib\jai_core.jar
       • C:\SAFS\lib\jai_codec.jar
       • C:\SAFS\lib\jai_imageio.jar
       • C:\SAFS\lib\jakarta-regexp-1.3.jar
       • C:\SAFS\lib\jaxen-1.1.3.jar
       • C:\SAFS\lib\juniversalchardet-1.0.3.jar
       • C:\SAFS\lib\nekohtml.jar
       • C:\SAFS\lib\org.json.jar
       • C:\SAFS\lib\SeInterpreter.jar
       • C:\SAFS\lib\selenium-server-standalone-N.N.N.jar (latest installed)
       • <pathTo>\cucumber-java-1.1.3.jar (Cucumber install location)
       • <pathTo>\ddmlib.jar (Android SDK)
       • <pathTo>\jna-3.4.0.jar

       If dependencies like Cucumber or Android are NOT to be used and are NOT available ' then the associated classes/packages using those dependencies will need to be removed from the project:

       • org.safs.abbot
       • org.safs.cukes
       • org.safs.android (but not necessarily org.safs.android.auto)

     • Insure "Installed JREs" knows about all your used Java runtimes.

     • Optionally Set Build Output to \classes subdirectory.

       Existing build utilities like JARIT.BAT assume the project class files are stored in a \classes subdirectory off the project root directory.   If you intend to use these build utilities then you will need to set your project Build Output accordingly:

       1. Right-Click your RFT Project in the RFT Project Explorer.
       2. Select 'Properties' from the popup menu.
       3. Select 'Java Build Path' in the Properties Dialog.
       4. Select the 'Source' Tab in the Dialog.
       5. Set the 'Default output folder:' to '<projectroot>/classes'.

          If you are prompted to 'clean' and\or 'perform a new build' then you can do this.

     • Checkout\Update the latest sourcecode from GitHub place it into the root RFT Project directory.
       (See the Environment Setup for Developers doc on GitHub SAFSDEV Core.)

   More SAFSDEV-specific developer information:

   • SAFSDEV Developer Environment
   • More (older) SAFSDEV Developer Info

   Note: The RFT Engine has reserved the RFT script name "TestScript" for its internal use.   This script is already compiled and stored in SAFSRATIONAL_FT.JAR and may have been copied into the RFT Project directory.   The user should not attempt to create a new RFT script by this name as one may override the other.

Carl Nagle, SAS
Project Lead, SAFSDEV
Subscribe to appropriate Support Forums to review support archives and ask questons.