SetupJSAFS.README


Author: Carl Nagle
UPDATED: 2016.01.21

Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php

  1. 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.

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


  2. 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.


  3. 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.


    Back to TopSAFS ProjectsUsing JSAFS
  4. 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.


    Back to TopJava JarsUsing JSAFS

  5. 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:

    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:

    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.


    Back to TopJava Jars, , SAFS Projects

  6. Using JSAFS in your code:

    There are simple steps to follow to use JSAFS in your own custom Java classes:

    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();


    Back to TopJava JarsSAFS ProjectsUsing JSAFSSAFS Monitor

  7. Minimum Config INI File:

    Below is the minimum config information needed in the INI file to use JSAFS with the default Driver Commands and SAFS Services NOT needing one of the add-on SAFS Engines like Functional Tester, Test Complete, or Robotium RemoteControl:

      
      [SAFS_DRIVER]
      DriverRoot="C:\SAFS"
      
      [SAFS_PROJECT]
      ProjectRoot="c:\pathTo\my\new\SAFSProject\directory"
      
      [SAFS_TEST]
      CycleLogName="MyJSAFSLog"
      CycleLogMode="TEXTLOG XMLLOG"
      
      ;optional
      [SAFS_ENGINES]
      First=org.safs.tools.engines.SAFSDRIVERCOMMANDS
      
      

    This minimum configuration tells JSAFSDriver where to find any additional SAFS configuration information--like safstid.ini--and where the SAFS Project directory structure is located.

    The SAFS_TEST section tells JSAFSDriver the root name to use for the SAFS Logs, and whether it should create TEXT logs, or XML logs, or both.

    The SAFS_ENGINE section tells JSAFSDriver to go ahead and use the generic SDC SAFS Engine to provide many SAFS Driver Commands.  Since it is the only add-on engine in use at this time, it is listed as the "First" engine to try.  If any other engine is added later, like the SAFSROBOTJ (RFT), SAFSTC (TestComplete), or SAFSDROID (Android); then the SDC engine would be listed as "Second", or not at all in some cases.

    The config file can have any name and is usually placed in the root directory for your new SAFS project.
    That is normally the Parent directory of the Datapool directory of the SAFS Project.

    The path to this config file is passed to the JSAFSDriver instance as the System Property "safs.project.config" as specified in the section above.


    Back to TopJava JarsSAFS ProjectsUsing JSAFS

  8. Using the SAFS Debug Log:

    Invariably, you will run into cases where you need more information--debug information.
    SAFS provides a Debug Log capability so that you can find out much more detailed information about what occurred during a running test.

    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.


    Back to TopJava JarsSAFS ProjectsUsing JSAFS

  9. 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:

    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.


Back to TopJava JarsUsing JSAFSSAFS Projects