Using JSAFS, the Java API for SAFS

Author: Carl Nagle
Since: MAR 30, 2006
Update: JUL 01, 2016

Copyright, SAS Institute
General Public License (GPL):

JSAFS Developers should refer to: SAFS JavaDoc.(Src)
Key documentation of interest therein are the packages for:

Installation and setup of Instructions for JSAFS.

The source and class files for the JSAFS API are provided in safsmodel.jar.
Note, also, the documentation for the JSAFSDriver (Src)--intended for Advanced Runtime frameworks and scenarios (discussed later).

Back To Top, Advanced Runtime Development

What exactly is JSAFS?

JSAFS is a Java API for writing tool-independent tests that can be executed in the SAFS environment.  The SAFS environment provides these key test automation features not readily available in one package anywhere else:

With this "Advanced Runtime", the Java code *is* the test and it contains runtime calls to the SAFS framework to accomplish tool-independent test activities.  There generally are no SAFS test tables created and all testing is driven from the developer's independent JSAFS-enabled Java program sending test records to the running engine(s).

While the JSAFS API is provided for Java test development, the code or applications to be tested are not limited to Java clients.  You can develop tests for:

The most common SAFS engines (testing tools) in use are:

Why use JSAFS?

JSAFS attempts to engage Java-savvy developers and testers exploiting tools like Eclipse allowing them to develop tool-independent SAFS tests in a familiar development environment (IDE).  It allows them to code tests that are still independent of the testing tools used at runtime while leveraging the Java IDE to provide a wealth of information and documentation for the JSAFS API and the SAFS Keyword implementations--the SAFS Reference.

The detailed information provided in the SAFS Reference is encapsulated into Java functions with JavaDoc.  Thus, the Java IDE is able to present this information to the developer in a context-sensitive manner via the auto-complete, tooltips and popups they already know.  Every SAFS command is available as a "callable" function.  Documentation for commands, component types, available functions, and parameters are available in the IDE, as shown below.

Sample Eclipse IDE Snapshot:

Eclipse IDE Snapshot

How would I use JSAFS?

The SAFS framework has been designed from the ground up with an open architecture.  It is a collection of testing tools and utilities connected together through a SAFS-defined protocol using STAF.

Java is an especially well-supported interface into SAFS which means Java developers using JSAFS have nearly endless possibilities for how they can exploit SAFS.  Other programming languages like VBScript, Perl, and C\C++ are also well supported, but do not (yet) have a comprehensive API interface to SAFS like JSAFS.

While "traditional" SAFS execution has engaged a multi-process STAF service architecture allowing multiple different tools and languages to be used simultaneously, there is the availability of SAFS being operated as a single-process "embedded" service architecture within a single Java JVM--no STAF.  This is only viable in an all-Java runtime in which the test, the runtime engine(s), and the testing services are all Java-based. An example of this is our SeleniumPlus tool using Selenium 2.0 WebDriver Java bindings and all Java-based tools and services.

Integrating with other non-JSAFS assets:
JSAFS tests do not have to live in a JSAFS-only world.  There may be developers writing JSAFS tests (Java) in their environments that must integrate with and have dependencies on SAFS test tables developed in Access, Excel, TextPad, or some other test table development tools.

It is possible for a traditional SAFS test with test tables to invoke the CallJUnit Driver Command to execute any number of Java-based JUnit tests.  And these JUnit tests have full access to the available SAFS services and runtime engines through multiple mechanisms--including the latest (Src).

We also may soon support the execution of any arbitrary Java class or Method via future commands like CallJava.  These too will have access to that same Runner class for exploiting the use of SAFS services and engines.

Back To Top, Background Info

JSAFS Advanced Runtime Development

Because JSAFS is a Java API, and because the SAFS Core is almost entirely Java-based, we are starting to see Java developers and testers coding their test logic in Java and foregoing the use of the SAFS test table processor SAFS DRIVER (Src) altogether.  This is exactly the mode of test development and execution offered in our SeleniumPlus tool wrapping Selenium 2.0 WebDriver support as a SAFS Test Engine.

In other cases, some developer/testers are writing custom test drivers (and sometimes whole frameworks!) in Java.  However, this Java code is still tool-independent and the tests still migrate from one testing tool to another as readily as any other SAFS test deployed as traditional test tables.

One possible (but rarely used) mechanism for using JSAFS in this way is for the new custom Java class to be a direct subclass of SAFSDRIVER (Src), or its superclass: DefaultDriver (Src).  By doing this, the developer inherits all the core startup and initialization capabilities of SAFSDRIVER--including the startup of required SAFS services and engines.   In addition, the custom SAFS driver has easy API access to all the SAFS services for handling variables, appmaps, NLS, and logging.  The new driver will also inherit the running SAFS Monitor allowing the tester or developer to Pause, Resume, Step, and Shutdown a running test, if desired.

SAFS Monitor for Runtime Debugging:

SAFS Monitor Application

However, it is also possible to merely add a comparable JSAFSDriver (Src) object to any Java class or testing framework.  The developer still acquires all the core startup and initialization capabilities of the standard SAFS Drivers--including the startup of required SAFS services and engines.   The custom driver will still have access to the SAFS Monitor allowing the tester or developer to Pause, Resume, Step, and Shutdown a running test--assuming the developer exploits these features in their code.  In addition, the JSAFSDriver provides convenient API access to all the SAFS services for handling variables, appmaps, NLS, logging, and expression handling.

Lastly, as mentioned in the previous section, if the developer's Java class is invoked or instantiated by some other mechanism provided by an already running SAFS test--like the CallJUnit Driver Command, then the Java class can gain access to all services and runtime engines via the latest (Src).

Commented example(s) can be found on GitHub at SAFS JSAFS Model Examples.

The working examples with sourcecode are also provided in the org.safs.model.examples.advanced package.  The sourcecode can be found in the safsmodel.jar file in a SAFS\lib directory following the installation and setup of SAFS. Also refer to additional developer instructions for JSAFS.

The JSAFSDriver (Src) main(String[] args) sourcecode can also act as an example since it is a functional self-test of the class itself:

Back To Top, Background Info