==========================================================================
Author: Carl Nagle
UPDATE: Sep 16, 2010
Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php
==========================================================================
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. |
This document instructs the user how to ensure SAFS framework services are invoked at, or prior to runtime when using SAFS RRAFS for Rational Robot.
This doc assumes the user has already installed the latest SAFS Framework via these instructions:
*If* the IBM Rational Functional Tester (RFT) Engine is expected to be part of the RRAFS runtime, then the user is expected to have already prepared the desired RFT Project per these instructions:
Once completed, the following items are all installed and available for use:
With everything installed correctly, the RRAFS engine has the ability to automatically launch STAF, the various SAFS services, the SAFS/DriverCommands Engine, and the SAFS/RobotJ Engine (for RFT). Review the information in the installed RRAFS.INI file found in the "C:\Program Files\Rational\Rational Test\sqabas32" install directory (a.k.a. DDE_RUNTIME).
With the exception of the SAFS/RobotJ Engine, all the other tools can be automatically launched by setting their RRAFS.INI AutoLaunch settings to "TRUE" (AUTOLAUNCH=TRUE).
The SAFS/RobotJ Engine requires project-specific information in RRAFS.INI before we can automatically launch the SAFS/RobotJ Engine with AUTOLAUNCH.
Consult SAFSUtilities for more information on available APIs and the RRAFS.INI settings.
The following API calls can be appended to the SQABasic Script that launches the RRAFS Engine. These APIs can be found in the SQABasic SAFSUtilities library mentioned above. Often these are unnecessary because the AUTOLAUNCH feature will shutdown these items when the script is completed or aborted.
SAFSShutdownRobotJ
SAFSShutdownDriverCommands
SAFSShutdownSTAF
Note: You may not wish to shutdown STAF following a run if you want to review variable settings and other items that persist. If that is the case, you should launch STAF and the services by some means other than AUTOLAUNCH because this mechanism will also automatically shutdown any tool it launches when the test script is completed or aborted.
The remainder of this document details manual methods for launching and shutting down the SAFS framework.
1) STAF (STAFProc) must be running to enable the use of SAFS Framework tools.
2) SAFS Services for STAF must be running.
3) (Optional) SAFS/DriverCommands Engine launched, waiting for commands.
4) (Optional) SAFS/RobotJ Engine launched, waiting for commands.
The STAF install will have placed two important programs in your Start Menu. Use these to start and stop STAF as desired.
1) "Start STAF" 2) "Shutdown STAF"
STAF can also be setup to be launched as an OS service during system startup. Consult the STAF User's Guide and other STAF references for more information on the many varied and fun ways to use STAF. You can find some of these references in your STAF installation directory. Other references and online support can be found via the STAF website:
STAF on SourceForge
STAF can also be launched or shutdown via the SAFSUtilities library.
Currently, we have 3 primary services we rely on in RRAFS:
SAFSMAPS - handles and processes our Application Maps and variable
Application Constants for any/all tools.
SAFSVARS - handles global storage and processing of DDVariables for
any/all tools.
SAFSLOGS - handles logging for any/all tools. All tools thus can
write to the same log(s).
A 4th service, SAFSINPUT, is primarily only used by SAFSDRIVER (TID) when running tests independent of IBM Rational Robot or other test drivers. SAFSDRIVER and RRAFS cannot effectively run simultaneously as only one SAFS Driver should be running during test execution.
There are various .BAT or .VBS files for launching or shutting down various pieces of the framework in the "SAFS\BIN" and "SAFS\Samples\Batch" subdirectories of your SAFS installation.
On 64-bit systems, remember to use the 32-bit version of Windows Scripting Host when necessary:
%SYSTEMROOT%\SysWOW64\cscript.exe
One method for launching the SAFS services for any active project is the VBS script:
%SAFSDIR%\bin\SAFSToolsStartup.VBS
From the HELP info embedded in the script:
------------------------------------------
ARGUMENTS:
==========
ARG(0): App Maps Directory (Ex: "C:\Project\Datapool")
Full path to the location where App Maps will be found for the
locally running project.
ARG(1): Logs Directory (Ex: "C:\Project\Datapool\Logs")
Full path to the location where logs will be written for the
locally running project.
Both of these arguments are required.
Example Invocations:
====================
Command Line CScript.EXE:
-------------------------
cscript "C:\safs\bin\SAFSToolsStartup.vbs" "C:\Project\Datapool" "C:\Project\Datapool\Logs"
Windows Script WScript.EXE:
---------------------------
wscript "C:\safs\bin\SAFSToolsStartup.vbs" "C:\Project\Datapool" "C:\Project\Datapool\Logs"
Of course, a .BAT file or even the above script can be hardcoded to always point to one specific project eliminating the need to pass parameters.
These tools can also be launched or shutdown via SAFSUtilities.
Assuming STAF was setup and configured properly, you can verify the listed SAFS Services are running by typing the following command at any command prompt. The services will appear among a list of other built-in services provided by STAF.
STAF Verification:
-----------------------
staf local service list
There is also a "SAFSDriverCommandsStartup.BAT" file in the %SAFSDIR%\BIN directory that can issue the default startup command. Assuming the %SAFSDIR%\BIN directory was correctly added to the system PATH, the user should be able to invoke the command from any command prompt (or other mechanism).
Command Prompt DriverCommands Startup:
--------------------------------------
SAFSDriverCommandsStartup or
%SAFSDIR%\bin\SAFSDriverCommandsStartup.bat
SAFS/DriverCommands can also be launched or shutdown via SAFSUtilities.
During your RFT Project setup you should have seen a "TestScript" that does nothing more than execute the RFT engine. To launch the SAFS/RobotJ Engine from within the Eclipse IDE all you do is run "TestScript". In the RFT console window you may see a 'resetting events' message, but little beyond that. RFT will appear to be dead, but it should actually be sitting there waiting for someone to send it test records to execute.
SAFS/RobotJ Engine can also be launched or shutdown via SAFSUtilities.
You can verify the running status by looking at a list of active STAF process\handles. "SAFS/RobotJ" should appear among this list, which represents SAFS/RobotJ Engine.
STAF Verification:
---------------------------
staf local handle query all (With STAF 2.6.11)
staf local handle list (With STAF 3.3.3)
There is also a "SAFSDriverCommandsShutdown.BAT" file in the %SAFSDIR%\BIN directory that can issue the shutdown command. Assuming the %SAFSDIR%\BIN directory was correctly added to the system PATH, the user should be able to invoke the command from any command prompt (or just double-click it in Windows Explorer).
Command Prompt DriverCommands Shutdown:
---------------------------------------
SAFSDriverCommandsShutdown or
%SAFSDIR%\bin\SAFSDriverCommandsShutdown.bat
SAFS/DriverCommands can also be launched or shutdown via SAFSUtilities.
Once the SAFS/RobotJ Engine is started, it will not normally shutdown until given the appropriate SAFS test record instruction to do so. This can be done via any client capable of talking to SAFS/RobotJ Engine through our STAF interface.
There is also a "SAFSRobotJShutdown.BAT" file in the %SAFSDIR%\BIN directory that can issue this shutdown command. Assuming the %SAFSDIR%\BIN directory was correctly added to the system PATH, the user should be able to invoke the command from any command prompt (or just double-click it in Windows Explorer).
Command Prompt SAFS/RobotJ Engine Shutdown:
--------------------------------------
SAFSRobotJShutdown or
%SAFSDIR%\bin\SAFSRobotJShutdown.bat
SAFS/RobotJ Engine can also be launched or shutdown via SAFSUtilities.
The normal STAF commands to remove each running service is all we use to shutdown our SAFS services.
There is a "SAFSToolsShutdown.BAT" file in the %SAFSDIR%\BIN directory that can issue these
commands. Assuming the %SAFSDIR%\BIN directory was correctly added to the system PATH, the
user should be able to invoke the command from any command prompt (or just double-click
it in Windows Explorer).
You can also just shutdown STAF and the services will be shutdown automatically.
Command Prompt SAFS Tools Shutdown:
-----------------------------------
SAFSToolsShutdown or
%SAFSDIR%\bin\SAFSToolsShutdown.bat
As mentioned previously, there is a "Shutdown STAF" item in your Start Menu to completely shutdown the STAF system. This will also remove any SAFS services that may still be running. It is not always necessary to shutdown STAF to reset the test environment. Often, simply shutting down and restarting the SAFS Services is sufficient.
STAF can also be launched or shutdown via SAFSUtilities.