SetupJSAFS.README

STAF and SAFS Required:

These instructions assume the tester has already installed SAFS with SAFS services via the SetupSAFS script (or alternative methods).  If this is not the case, please refer to the SetupSAFS.README file for information on the SAFS setup procedure.  Users are encouraged to install the *latest* SAFS Snapshot, Overlay, or Update available.  Read and follow any additional instructions provided with Snapshot, Overlay, or Update.

A working SAFS JSAFS Example

New SAFS installations contain a working JSAFS example that also demonstrates the usage of optional AutoConfiguration and execution.
It is recommended you first start with this example to get a feel for JSAFS Project configuration.

See JSAFS AutoConfiguration and Execution for more details regarding a working JSAFS example.

To start a JSAFS Project from scratch, see below.

The Java Project

If you are not enhancing an existing Java Project, then you will need to create a new empty Java Project before proceeding below.

Please note that SAFS JSAFS expects an execution environment of 32-bit Java 7, or higher.
SAFS installs an "embedded" JRE for this purpose in %SAFSDIR%\jre.
This JRE or a comparable 32-bit JRE should always be used to execute SAFS tests.

Add SAFS Java Dependencies

In order to take advantage of JSAFS, the developer will need to add the following Java Archive dependencies to their Java development project.

• JAR file from the STAF install directory, typically in \STAF\bin
  • JSTAF.jar

• JAR files from the SAFS install directory, typically in \SAFS\lib
  • safs.jar
  • safsmodel.jar

  The JavaDoc for SAFS classes is rooted at: http://safsdev.sourceforge.net/doc.
  You should provide this JavaDoc location when adding the SAFS JAR files to your project's build path.

New SAFS Project

For each different test project or product we recommend you create a new and separate SAFS project.
This is an expected directory structure specific for SAFS execution that is independent of Java.

On Windows, copy the following script:

\SAFS\bin\SetupSAFSProject.VBS

Copy the script to the directory where you wish SAFS project assets--like configuration files--to reside. Execute the script by double-clicking on it and the script will create configuration files and utility scripts in that location and add the following required subdirectories:

[ProjectRoot]\Datapool\Bench
[ProjectRoot]\Datapool\Dif
[ProjectRoot]\Datapool\Logs
[ProjectRoot]\Datapool\Test

Note: If the machine is a 64-bit machine and OS, and your default Java is a 64-bit Java, you will need to have a 32-bit JRE/JDK installed for runtime execution.  You will also need to modify the few scripts that invoke Java to point to the 32-bit version instead of allowing the default 64-bit version to execute.

Using JSAFS in your code:

1. Provide SAFS project configuration information for JSAFS
2. Instantiate a new JSAFSDriver object instance
3. "run" the JSAFSDriver instance to initialize with the configuration info
4. Intermix both JSAFS and non-JSAFS operations using the public API...
5. "shutdown" the JSAFSDriver instance when finished with all testing

The details for doing that:

1. Provide SAFS project configuration information for JSAFS:
   This is done through a SAFS configuration (INI) file.
   The config file can have any name and is typically placed in the project's root directory.
   Examples of SAFS INI files can be found in the \SAFS\Project directory where SAFS was installed.
   Normally, the developer will copy and modify one of these for their own use.
   It is easiest to modify an exising INI file that is configured to use the same test automation tool that will be used in your environment.

   Most importantly, the JSAFSDriver needs to know which INI file to use.  It will expect to find the full path to the INI file in the following JVM System Property at runtime:

   safs.project.config

   There are 2 ways to provide this value:

   A JVM command-line argument when you first invoke your Java application:

   java -Dsafs.project.config="fullpath\to\my.ini" org.my.TestApp

   Setting the System Property in code prior to invoking "run" on the JSAFSDriver instance:

   System.setProperty("safs.project.config", "fullpath\to\my.ini");

2. Instantiate a JSAFSDriver object instance.
   import org.safs.tools.drivers.JSAFSDriver;

   JSAFSDriver jsafs = new JSAFSDriver("JSAFS");

3. "run" the JSAFSDriver instance to initialize with the configuration info.
   jsafs.run();

4. Intermix both JSAFS and non-JSAFS operations using the public API...
   Let's put some initial code after the "run()" method to do some simple (but important) commands that don't require an additional SAFS Engine.  As you enter this code in your Java development environment, pay attention to the available JavaDoc for each of the objects and methods provided:

   TestRecordHelper trd = jsafs.runDriverCommand(DDDriverCommands.appMapChaining("ON"));
trd = jsafs.runDriverCommand(DDDriverCommands.appMapResolve("ON"));
trd = jsafs.runDriverCommand(DDDriverCommands.expressions("ON"));


   There is also this simple example of some of the API usage for JSAFS.
   However, this is just for example reference and assumes the SAFS/RobotJ engine using IBM Rational Functional Tester is setup and properly configured for testing.

5. "shutdown" the JSAFSDriver instance when finished with all testing.
   jsafs.shutdown();

Minimum Config INI File:

Using the SAFS Debug Log:

Refer to this basic Debug Log JavaDoc.

If you used the SetupProject.VBS as recommended above when creating your project, then you should have helper scripts for this in your SAFS Project:

1. SAFSDebugStartup.bat
2. SAFSDebugShutdown.bat

These are already configured to startup STAF as necessary before starting the Debug Log.
Remember, the Debug Log must be shutdown before it can be viewed.

Using SAFS Monitor:

Reference: Using the SAFS Monitor

The SAFS Monitor provides a visible UI allowing testers and developers to interact with running SAFS tests.  This includes capabilities such as:

• Pausing a running test
• Resume a paused test
• Stepping through a running test
• Aborting a running test
• Interactively viewing and changing SAFS variables during testing

A JSAFS developer/tester can take advantage of the UI and these same capabilities by using code that checks the appropriate SAFS variable values and reacting accordingly.