org.safs.tools.engines

Class SAFSROBOTJ

java.lang.Object

org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

org.safs.tools.engines.GenericEngine

org.safs.tools.engines.SAFSROBOTJ

All Implemented Interfaces:

ConfigurableToolsInterface, EngineInterface, GenericToolsInterface, ITestRecordStackable, RuntimeDataInterface

public class SAFSROBOTJ
extends GenericEngine

A wrapper to the IBM Rational Functional Tester SAFS engine--the "RobotJ" engine. This engine can only be used if you have a valid, licensed installation of IBM Rational Functional Tester (a.k.a. XDE Tester and--before that--RobotJ.)
We often refer to IBM Rational Functional Tester as "RFT".

The default SAFSDRIVER Tool-Independent Driver (TID) does not provide for any command-line options to configure RFT. All configuration information must be provided in config files. By default, these are SAFSTID.INI files. See SAFSTID Config Fields for more information.

The RFT supported config file items:

 [SAFS_ROBOTJ]
 AUTOLAUNCH=FALSE            Defaults to FALSE because config info must be valid.
 DATASTORE=<DatastoreJ>      Root directory of RobotJ Project/Datastore. Location of RobotJ scripts.
 
 ;optional args follow
 ;--------------------
 ;PLAYBACK=TestScript        RobotJ script to use as SAFS Hook. (HOOK, HOOKSCRIPT)
 ;STAFID="SAFS/ROBOTJ"       Normally never used.
 ;JVM=JVMpath                Full path to desired Java executable if "java" is not sufficient.
 ;JVMARGS=JVM Args           Ex: "-Xms512m -Xmx512m", will be used unmodified.
 ;CLASSPATH=altClasspath     Generally overrides system classpath.
 ;INSTALLDIR=<wswpluginPath> [-V7]Directory in Rational where rational_ft.jar resides.
 ;                           Do not use INSTALLDIR if using JARPATH and PROJECTPATH.
 ;JARPATH=<FunctionalTester\bin> [V7+]Full file path to rational_ft.jar resides.
 ;PROJECTPATH=<CLASSPATH>    [V7+]CLASSPATH syntax to all needed SAFS\STAF JARS.
 ;                           Do not use JARPATH and PROJECTPATH if using INSTALLDIR.
 ;XBOOTCLASSPATH=<CLASSPATH>    [V8+]CLASSPATH needed by RFT when launching with -jar rational_ft.jar.
 ;PROJECT=<Project.rsp>      Full path to Rational .rsp file for the Rational Project.
 ;BUILD=<Build #>            Build # associated with this Rational Project TestManager.
 ;LOGFOLDER=Default          The name of the root logfolder in the Rational Project.
 ;LOG=TestScript             The name of the TestManager log to use.
 ;USERID=<userid>            Login info for the Rational Project.
 ;PASSWORD=                  Login info for the Rational Project.
 ;TIMEOUT=45                 AutoLaunch timeout value in seconds. Default 45 seconds.
 ;OPTIONS=                   Script -args to be appended, if any. Normally never used.
 
 SECSWaitForWindow=30        Timeout in seconds to look for Windows
 SECSWaitForComponent=30     Timeout in seconds to look for Window Components
 CommandLineBreakpoint=TRUE  Set option to TRUE or FALSE
 TESTDOMAINS=Java,Html,Win,Net,Swt,Flex   Limit the number of domains to search
 ClearProxiesAlways=True     Always Clear reference caches. Force component search for every Action.
 RFSMOnly=Yes                              Run RFSM Search Mode exclusively(recognition string doesn't need :RFSM: prefix). 
 RFSMCache=Yes                     Cache RFSM Search Mode components object(Child object). Main object(main window object) caches by default.
 

Note, the majority of these options are necessary to satisfy the command-line options for RFT ONLY if the project has been associated with a IBM Rational Test Manager project. Consult the RFT command-line options documentation for more details and valid settings.

As of RFT V7, if there is no Test Manager association and logging, then we can usually only need the AUTOLAUNCH and DATASTORE settings in the INI file.

Uses the following logic to deduce some settings:

INSTALLDIR and JARPATH

The use of INSTALLDIR and JARPATH are mutually exclusive. JARPATH launches RFT using the -JAR rational_ft.jar option and REQUIRES the use of PROJECTPATH. However, if neither INSTALLDIR nor JARPATH are provided then we attempt to deduce the JARPATH mechanism of launching RFT and build JARPATH and PROJECTPATH dynamically.

AUTOLAUNCH

True if set to "TRUE", "YES", "ON", or "1". Not case-sensitive.

JVM

If not provided by config file we try to locate the java executable of "./jdk/jre/bin/java.exe" from one of these settings, if found:

1. System.getenv Variable name: IBM_RATIONAL_RFT_ECLIPSE_DIR
2. System getProperty Variable name: IBM_RATIONAL_RFT_ECLIPSE_DIR
3. System getProperty Variable name: IBM.RATIONAL.RFT.ECLIPSE.DIR

Some 8.x versions of RFT (perhaps all?) still contain their own Java 1.6 JDK. For runtime execution with SAFS we now use Java 1.7. at bundles in directory SAFS\jre.

If RFT will not launch successfully using our default launch algorithms pointing to what we think is the right JDK/JRE, the user may have to provide this JVM parameter to point to a JDK/JRE that will work for their case.

JVMARGS

Any JVM options to pass to the Java JVM as part of its invocation.

Ex: JVMARGS="-Xms512m -Xmx1024m"

JARPATH

If not provided by config file we try to locate the rational_ft.jar from one of these settings, if found:

1. System.getenv Variable name: IBM_RATIONAL_RFT_INSTALL_DIR
2. System getProperty Variable name: IBM_RATIONAL_RFT_INSTALL_DIR
3. System getProperty Variable name: IBM.RATIONAL.RFT.INSTALL.DIR

PROJECTPATH

Used with JARPATH. If not provided by config file we try to build this using Environment variables to validate the existence of STAF and SAFS JAR files dynamically:

1. System.getenv Variable name: SAFSDIR
2. System.getenv Variable name: STAFDIR

3. Required JAR file: STAFDIR/bin/jstaf.jar

4. Required JAR file: SAFSDIR/lib/safs.jar
5. Required JAR file: SAFSDIR/lib/jakarta-regexp-1.3.jar
6. Required JAR file: SAFSDIR/lib/safsrational_ft.jar
7. Required JAR file: SAFSDIR/lib/safsrational_ft_enabler.jar
8. Required JAR file: SAFSDIR/lib/jai_core.jar
9. Required JAR file: SAFSDIR/lib/jai_codec.jar
10. Required JAR file: SAFSDIR/lib/jai_imageio.jar
11. Required JAR file: SAFSDIR/lib/jna.zip
12. Required JAR file: SAFSDIR/lib/safscust.jar
13. Optional JAR file: SAFSDIR/lib/safsdebug.jar

XBOOTCLASSPATH

Used to add required JAR libs to RFT JVM when -jar rational_ft is used to launch RFT. The normal launch mechanism already provides a default XBOOTCLASSPATH. The user only uses this option if they need to add more JARS to those used by default. If the user provides the setting, they must include all required JARS in the path since the setting will override the one provided by default.

Example:

XBOOTCLASSPATH="c:\safs\lib\jai_core.jar;c:\safs\lib\jai_codec.jar;c:\safs\lib\jai_imageio.jar;others..."

Other settings are not deduced and must be provided as necessary for your configuration.

This routine appends an -args parameters to the TestScriptHelper hook in the form of: -args safs.config.paths=<paths to chained config files> TestScriptHelper takes this value and stores it as a JVM System.property, "safs.config.paths".

Author:

Carl Nagle DEC 14, 2005 Refactored with DriverConfiguredSTAFInterface superclass, Carl Nagle JAN 14, 2008 Refactored for RFT V7 AUTOLAUNCH., Carl Nagle AUG 07, 2008 Show support for new options SecsWaitForWindow, SecsWaitForComponent, CommandLineBreakpoint, and TestDomains., Carl Nagle APR 22, 2009 Doc update for ClearProxiesAlways., Carl Nagle AUG 14, 2009 Support for JVM Args during AutoLaunch., JunwuMa FEB 26 2010 Added XBOOTCLASSPATH for JVM searching JAI/JAI Imageio during AutoLaunch., JunwuMa APR 02 2010 Removed clibwrapper_jiio.jar from XBOOTCLASSPATH., Carl Nagle JAN 20, 2016 Fixes for launching RFT with SAFS JRE.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static java.lang.String	ENGINE_NAME "SAFS/RobotJ" -- The name of this engine as registered with STAF.
(package private) static java.lang.String	HOOK_CLASS "com.rational.test.ft.rational_ft" -- The Rational class that is RobotJ/XDE Tester.
(package private) static java.lang.String	HOOK_OPTION
(package private) static java.lang.String	HOOK_SCRIPT "TestScript" -- The default script run by the engine.
(package private) static java.lang.String	HOOKSCRIPT_OPTION
(package private) static java.lang.String	JVMARGS_OPTION
(package private) static java.lang.String	PLAYBACK_OPTION
(package private) static java.lang.String	XBOOTCLASSPATH_OPTION

Fields inherited from class org.safs.tools.engines.GenericEngine

console, process, testRecordData, testrecordStackable

Fields inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

config, customStr, customText, debugStr, debugText, driver, DRIVER_TEMP_PROCESS, failedStr, failedText, genericStr, genericText, launchCount, log, machine, otherStr, otherText, passedStr, passedText, processName, running, SAFS_RESBUN_NAME, servicename, shutdownCount, staf, STAFPROC_EXE, warningStr, warningText, weStartedService, weStartedSTAF

Fields inherited from interface org.safs.tools.engines.EngineInterface

COMMAND_SHUTDOWN_HOOK

Constructor Summary

Constructors

Constructor and Description
SAFSROBOTJ() Constructor for SAFSROBOTJ.
SAFSROBOTJ(DriverInterface driver) PREFERRED Constructor for SAFSROBOTJ.

Method Summary

Modifier and Type	Method and Description
void	launchInterface(java.lang.Object configInfo) Extracts or deduces configuration information and launches RFT in a new process.
long	processRecord(TestRecordHelper testRecordData) Override superclass to catch unsuccessful initialization scenarios.

Methods inherited from class org.safs.tools.engines.GenericEngine

deduceBenchFile, deduceProjectFile, deduceTestFile, getAppMapItem, getEngineName, getVariable, isToolRunning, logMessage, makeQuotedPath, makeQuotedString, popTestRecord, postShutdownServiceDelay, pushTestRecord, reset, resetShutdownSemaphore, saveTestRecordScreenToTestDirectory, setTRDStatus, setVariable, shutdownService, waitHookShutdownAndReset

Methods inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

configureJSTAFServiceEmbeddedJVMOption, extendedGenericMessage, finalize, getCoreInterface, getEmbeddedJVMBinPath, getSTAFHelper, logMessage, setLogUtilities, setLogUtilities, shutdown, simpleGenericMessage, simpleGenericSuccessMessage, simpleGenericWarningMessage, simpleSuccessMessage, simpleSuccessMessage, simpleSuccessUsingMessage, standardErrorMessage, waitForServiceStartCompletion

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.safs.tools.GenericToolsInterface

getCoreInterface, shutdown

Field Detail

ENGINE_NAME

static final java.lang.String ENGINE_NAME

"SAFS/RobotJ" -- The name of this engine as registered with STAF.

See Also:

Constant Field Values

HOOK_CLASS

static final java.lang.String HOOK_CLASS

"com.rational.test.ft.rational_ft" -- The Rational class that is RobotJ/XDE Tester.

See Also:

Constant Field Values

HOOK_SCRIPT

static final java.lang.String HOOK_SCRIPT

"TestScript" -- The default script run by the engine.

See Also:

Constant Field Values

HOOK_OPTION

static final java.lang.String HOOK_OPTION

See Also:

Constant Field Values

HOOKSCRIPT_OPTION

static final java.lang.String HOOKSCRIPT_OPTION

See Also:

Constant Field Values

PLAYBACK_OPTION

static final java.lang.String PLAYBACK_OPTION

See Also:

Constant Field Values

JVMARGS_OPTION

static final java.lang.String JVMARGS_OPTION

See Also:

Constant Field Values

XBOOTCLASSPATH_OPTION

static final java.lang.String XBOOTCLASSPATH_OPTION

See Also:

Constant Field Values

Constructor Detail

SAFSROBOTJ

public SAFSROBOTJ()

Constructor for SAFSROBOTJ. Call launchInterface with an appropriate DriverInterface before attempting to use this minimally initialized object.

SAFSROBOTJ

public SAFSROBOTJ(DriverInterface driver)

PREFERRED Constructor for SAFSROBOTJ.

Method Detail

launchInterface

public void launchInterface(java.lang.Object configInfo)

Extracts or deduces configuration information and launches RFT in a new process.

Specified by:

launchInterface in interface ConfigurableToolsInterface

Overrides:

launchInterface in class GenericEngine

Parameters:

configInfo - can be whatever the final implementation needs it to be. This might be a String with configuration information, the name of a class, or an instance of some object used to provide configuration assets.

See Also:

GenericEngine.launchInterface(Object)

processRecord

public long processRecord(TestRecordHelper testRecordData)

Override superclass to catch unsuccessful initialization scenarios.

Specified by:

processRecord in interface EngineInterface

Overrides:

processRecord in class GenericEngine

Returns:

the status code resulting from the processing.

• 4 -- SCRIPT NOT EXECUTED. "I did not process this record."
• -1 -- NO SCRIPT FAILURE. "I processed the record successfully."
• -2 -- SCRIPT WARNING. "I processed the record, issued warning(s)."
• 0 -- SCRIPT FAILURE. "I processed the record, issued failure(s)."
• 2 -- IO FAILURE. "I process the record, issued IO failure(s)."
• 8 -- EXIT TABLE. "I processed the record, exit current table."
• 16 -- IGNORE STATUS. "I processed the record, ignore code and continue."

See Also:

EngineInterface#processRecord()