SAFS Release Notes
RRAFS and the Shared SAFS Framework
2004.09.08

Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, Comments, New Stuff, Old Stuff,


Definitions:

SAFS Software Automation Framework Support
SAFS Engine A Data Driven Engine implemented using SAFS
RRAFS
RRAFS Engine
A SAFS Engine for Rational Robot
RobotJ Engine
SAFS/RobotJ
A SAFS Engine for Rational RobotJ/XDE Tester
SAFS/DriverCommands A SAFS Engine for tool-independent Driver Commands
Home Page SAFSDEV on Sourceforge

Back2Top, Definitions, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, Comments, New Stuff, Old Stuff,

CRITICAL REMINDERS

Robot Scripts may need to be recompiled.
All existing RRAFS Robot scripts that reference or INCLUDE any part of this framework may need to be recompiled.

Normally, a quick File->Batch Compile of GUI Scripts within Robot will take care of this. You must do this in each project that uses the framework. If you had any custom libs that referenced the framework then they too may need to be recompiled with File->Batch Compile SQABasic Library sources.

Backup selected customized files before installation!
If you have never installed RRAFS or SAFS before, then this doesn't apply to you.
If you installed but never modified any of the files, then this doesn't apply to you. But you may want to review the mentioned files "just in case".

Affected customizable files from previous releases:

If you have taken advantage of any of the customization capabilities of this framework, then you must take some simple precautions prior to installing this new release. Installing a new version of the framework will install new, default versions of these files.

RRAFS.INI
Essentially, you must make a backup of any RRAFS.INI in your Rational install directory (DDE_RUNTIME) if you have made customizations by modifying settings; then evaluate how and if you want to merge with the new file.

Custom Extensions
Backup any Custom Extension libraries in which you have implemented customizations. Users who have implemented customizations in older versions of those libraries can then overwrite the newly installed files with those older versions. This effectively reinserts your customizations into the new version of the framework.

SAFSTID.INI
You should make a backup of any SAFSTID.INI in your SAFS install directory (C:\SAFS) if you have this file and modified settings. Then evaluate how and if you want to merge with the new file.

SAFS Batch Files
If you have previously installed the SAFS Framework separately, then you may have manually modified batch files or VBS script(s) to handle custom project paths. You will need to backup modified files and evaluate how and if you want to merge such changes with the new files.

Failure to perform any of these prescribed backups may render your prior customizations nonexistent. Hopefully, you have backed them up somewhere already as part of your normal ongoing activities. Right?!

Consult Using Custom Extensions for additional information on Custom Extensions with this framework. This HTML doc is also provided in your RRAFS install directory.


Back2Top, Definitions, Critical Reminders, Install Instructions, Setup Notes, RobotJ Notes, Comments, New Stuff, Old Stuff,

A New SAFS Tool in the Framework (2004.08.27)

The SAFS tools are implemented using STAF Technology and have been developed in Java. Use the STAF Technology link for more information on STAF and how it can be used even outside of our SAFS testing framework.

In addition to the existing SAFSVARS, SAFSMAPS, SAFSLOGS, SAFS/RobotJ, and SAFS/DDDriverCommands; we have now added SAFSINPUT.

SAFSINPUT -- Truly Global File Reader

Any number of tools or processes can open, read, and play with files.  Open files can be shared by all processes and tools on the machine.  Thus, different drivers, tools, and engines can all process input from the files and remain in sync. WinRunner, SilkTest, and even a human sitting at a command prompt have access to the contents of these files. The content should also be available to remote machines running the underlying STAF software.


Back2Top, Definitions, Critical Reminders, SAFS Tools, Setup Notes, RobotJ Notes, Comments, New Stuff, Old Stuff,

Installation Instructions

Review Backup Reminders in Critical Reminders

If you have not done so, review the Critical Reminders concerning backups of locally modified or customized files from previous releases. I'd hate to say, "I told ya so."

Uninstall Previous RRAFS Release:

Installations of RRAFS Release 2003.01.27 (Jan 2003) and earlier installed via the Windows Installer .MSI need to uninstall that release before installing this new one. You must do this to avoid unexpected backward versioning that can occur if the Windows Installer update or repair feature is ever invoked.

RRAFS Release 2003.08.27 (Aug 2003) and later do not have this uninstall requirement as we implemented the ability to patch and install on top of releases using different technologies.

Uninstall SAFS Engine for Rational Robot from the Windows Control Panel "Add/Remove Programs" application if present.

Short-N-Sweet install instructions:
Also reference: Engine Setup, a copy of which should be available in your install directory.

Per the Engine Setup doc, a Java JVM and Windows Scripting Host V5.6 or later is required. Refer to the Engine Setup Tools section for more details and install information for those tools.

  1. Extract the Release .ZIP into the RRAFS DDE_RUNTIME directory.
    Extract all files of the ZIP file into your C:\Program Files\Rational\Rational Test\sqabas32 directory (or equivalent...a.k.a. DDE_RUNTIME).

    • DO NOT Extract using foldernames. All files extracted into this one directory.
    • Overwrite Existing Files if a previous release exists.

  2. Run the extracted Setup.vbs script.
    In Windows Explorer, locate "Setup.vbs" in that directory and double-click to execute it.

  3. Setup Rational Robot Playback per DDEngineSetup
    Verify/Complete any Robot Playback Options setup per the DDEngineSetup doc mentioned in the following section.

  4. If desired, setup SAFS and Rational RobotJ/XDE Tester per SetupSAFS.README
    Verify/Complete any setup per doc.

Setup.vbs should take care of all DLL registration and placement required by the RRAFS Engine.  In fact, the Installer even provides compiled Robot code (SBX) into the DDE_RUNTIME directory so that most users can jump right in without having to compile the library source. Users with incompatible versions of the Robot compiler (pre-V2001, I think) will need to recompile the source for their older version of Robot.

Setup.vbs will also install the MSXSL.EXE utility used for XML\XSL transformations. However, the Installer does not install ExamDiff or any other Diff Viewer to take advantage of that new capability. (See the Setup doc for more information.)

(Note: the MSXSL.EXE installed is the pre-msxml4 version. You can download a later version from microsoft.com. The latest version from Microsoft purportedly will not work with pre-msxml4 versions of msxml.)

Setup.vbs will prompt to confirm for the installation of the SAFS Framework and STAF.  The user has the option to skip these installations by pressing "Cancel" when prompted.

Setup.vbs will not install any program that will appear in Control Panel's "Add/Remove Program" application.


Back2Top, Definitions, Critical Reminders, SAFS Tools, Install Instructions, RobotJ Notes, Comments, New Stuff, Old Stuff,

Additional Setup Notes and Information

Additional notes and instructions for this release can be found via the links below. These are generally reviewed in the listed order. The files are contained in the downloaded installation ZIP file and available once all contents of the ZIP file are extracted into the install directory. (The links to these will work once unzipped locally.)

SetupSAFS.README Install STAF and SAFS Services
SetupRobotJ.README Setup RobotJ to use STAF and SAFS Services
SetupRuntime.README Runtime Setup for Testing


Back2Top, Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, Comments, New Stuff, Old Stuff,

SAFS/RobotJ Support Notes

Currently, there is a large array of Component Function libraries and commands supporting the testing of Java applications. The testing of HTML clients with RobotJ is not yet seemless as Java clients. Work is ongoing to add more features for both Web and Java testing.

RobotJ can support all of the Driver Commands made available by the SAFS/DriverCommands engine. If SAFS/DriverCommands is not running for some reason, those Driver Commands will be supported by RobotJ.

Keep in mind that the current implementation is for Robot Classic to be the Driver for RobotJ.  (An independent Driver is currently in development.)  This means ALL of the Component Functions and Driver Commands already available via Robot Classic are fully supported. RobotJ provides some overlap for these commands, but it also provides some new commands not available in Robot Classic. This actually means that development of new commands or features can be developed in either Robot Classic or RobotJ--whichever is more comfortable to the developer.


Back2Top, Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, New Stuff, Old Stuff,

Additional Comments

Some comments about ongoing development...

Releasing the enhanced SAFS framework does not jeapardize your existing non-SAFS tests. Existing tests will still work as they always did. You do not have to use any of the new features provided by the SAFS Framework.


Back2Top, Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, Comments, Old Stuff,

New, Fixed, or Enhanced Stuff

Most notable, but not all-inclusive is:


Back2Top, Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, Comments, New Stuff,

Old Stuff

Older Notes That Are Still Important and Applicable:

If you do download Web or CVS updates regularly, or even daily, you can keep your RRAFS Action Map (XLSComponentActions.MAP) up-to-date by replacing it with the one generated daily at:

RRAFS Component Actions

The extracted MAP file goes into the DDE_RUNTIME directory overwriting the existing file of the same name.

Clearing App Map Cache and Variable Values:

We often get reports that "changes to my App Map are not getting picked-up".  It is always a good idea to start your test with a known "clean" state for App Map entries and Variable values.  At or near the top of your test script, is a good place to put the following 2 functions:

   ...
   DDGClearAppMapCache
   DDVClearAllVariables
   ...
Important XML Logging Information For Older Scripts:

The addition of XML Logging in Oct 2002 to LogUtilities will impact scripts whose LogFacility (usually MainLog) is initialized enabling all logs with MAX_LOGMODE. A script enabling individual logs with values like TEXTLOG_ENABLED, SQALOG_ENABLED, CONSOLE_ENABLED, or any combination of these should not be affected.

The issue is that MAX_LOGMODE will automatically enable the new XML Log. However, the older script will not have one or more other function calls to effectively handle that XML log once the test is complete. For example, older scripts will likely close the logs enabled with MAX_LOGMODE via the CloseTextLogs function.

CloseTextLogs does not close XML logs.
The new "close all" function needs to be CloseAllLogs.

To retain existing log behavior in older scripts with the smallest script modification would be to replace each instance of MAX_LOGMODE in these scripts with the binary equivalent that does NOT include the new XML logging:


   (TEXTLOG_ENABLED OR SQALOG_ENABLED OR CONSOLE_ENABLED)

No other script modification should be required.

Q: So, what happens if I don't make this change in my scripts and the XML logs are enabled by MAX_LOGMODE?

Your script should function just fine as it always did. However, the framework will enable a default XML log for each test run. At the end of each test run, the log may remain open unless your script performs a "Reset" subroutine call. The log will also likely close when Robot is shutdown or other times that Robot would try to shutdown its File IO.

However, the RRAFS framework logging has always been done in APPEND mode. Each new RRAFS test run APPENDS to any log of the same name that was not renamed or deleted prior to initializing the Log Facility. Since your older script does not know about the new XML log being created, it will not attempt to delete the XML log from previous runs. Thus, you will be growing a nice, large XML log history of every test run by all scripts that launched a test using MAX_LOGMODE.

Q: How can I modify my older scripts to *properly* take advantage of this new XML logging?

Folks do different things in their scripts to initialize the logs and run the tests. I can't possibly address all possibilities here. However, some general guidelines for modifying existing scripts are below.

  1. Provide a unique XML log name just as with the Text log.
  2. Delete the previous XML log just as you do the Text log.
  3. CloseALLLogs instead of only CloseTextLogs
  4. "Cap" the XML log with appropriate HEADERS and FOOTERS.

Example modified Robot script code including all XML handling:

    ....
    'clear cached maps and variables
    DDGClearAppMapCache
    DDVClearAllVariables

    'setup lognames, delete previous logs, initialize new logs
    MainLog.logid = "MyImportantTestLog"
    logfile = GetDDELogsDirectory() & MainLog.logid
    on error resume next
    kill logfile &".txt"
    kill logfile &".xml"
    on error goto 0

    'caution, resource intensive and new log formats automatically enabled
    InitLogFacility MAX_LOGMODE, MainLog

    <... any other script code and running the test ...>

    'close the logs
    CloseAllLogs MainLog, 1
    LUCapXMLLog Mainlog.xmllog
    Reset

    'shutdown SAFS Framework pieces if AutoLaunched
    SAFSShutdownDriverCommands
    SAFSShutdownRobotJ
    DelayFor 4000
    'SAFSShutdownSTAF

    'view the text log at the end of the test
    StartApplication "notepad.exe "& MainLog.textlog

    ....


Definitions, Critical Reminders, SAFS Tools, Install Instructions, Setup Notes, RobotJ Notes, Comments, New Stuff, Old Stuff,
Carl Nagle, SAS
Project Manager, SAFSDEV
***REMOVED***