JSAFS Advanced Runtime
SAFS Java API test development instead of SAFS CSV Test Tables.

JSAFS Annotations
Automatic Java dependency injection and dynamic test execution.

This document discusses assets provided by the SAFS Windows Release. However, the details of how to configure and use these features are similar for all SAFS installations.

Using SAFS

This tutorial assumes that SAFS is successfully installed and functioning normally.
In this tutorial (and most online documentation):
%SAFSDIR%
Refers to the installation directory of SAFS.
WIN Default: C:\SAFS
UNX Default: (future)


%STAFDIR%
Refers to the installation directory of STAF.
WIN Default: C:\STAF
UNX Default: (future)


%MYTEST%
Refers to the sample Eclipse Project provided.
Default: %SAFSDIR%\samples\eclipse\MyTest

Configure Eclipse

We will assume Eclipse is being used for Java development. But other Java development environments can be used and configured similarly.

1. Create a New->Java Project
   1. Instead of using the default workspace location, Browse to the %MYTEST% directory.
   2. Select the MyTest directory as your project location and use MyTest as the project name.
   3. Set the Java Build Settings Default Output Folder to be MyTest/bin

2. Make sure the Java Runtime associated with the Project is the one installed with SAFS.
   1. In Eclipse, this is done at Window->Preferences  Java->Installed JREs.

   

3. Review the Project structure and contents of the MyTest project:

   \com\sas\test
   \Datapool\
             \Bench\
             \Test\
             \Logs\
             \Dif\
   test.ini
      

   

   Some of the subdirectories of Datapool may not be present
   That is OK. Missing directories should be automatically created at runtime.

4. Review the test.ini file in a text viewer/editor.

   You should note the [SAFS_ENGINES] entries for SmartBear's TestComplete and IBM Rational Functional Tester are intentionally commented out (disabled).
   This sample test will be using the internal AutoIt Engine for test execution.

5. Verify the Project's Java BuildPath contains the JARS and JavaDoc locations listed below.
   (Setting the JavaDoc location is extremely important to learn how this all works!)
   %STAFDIR% /bin/ JSTAF.jar

   %SAFSDIR% /lib/ SAFS.jar
   JavaDoc location: http://safsdev.sourceforge.net/doc

   %SAFSDIR% /lib/ safsmodel.jar
   JavaDoc location: http://safsdev.sourceforge.net/doc

   

6. Open and Review the com.sas.test.MyTest.java Class in the Editor.
   Note:
   • the imports provided for the Class.

   • the @AutoConfigureJSAFS Annotation above the MyTest class definition.
     Hover over that @AutoConfigureJSAFS annotation and see documentation related to its use.

   • the REQUIRED default, no-argument constructor for any class that will be auto-configured:
     public MyTest() {
     super();
     }

   • the @JSAFSTest Annotation above the TestMethodA method definition.
     Hover over that @JSAFSTest annotation and see documentation related to its use.

   • the main( String[] args ) method which invokes:
     Runner.autorun(args)
     Runner.shutdown()
     

7. Setup a "Run Configuration" for the MyTest Class:

   In the Run Menu->Run Configurations Dialog:

   New Java Application Launch Configuration:
   
      Name: Run MyTest
   
      Main Tab:
      Project: MyTest
      Main class: com.sas.test.MyTest
      Press Apply to commit these changes.
   
      
   
      Arguments Tab:
      VM Arguments:
   
          -Dsafs.project.config="./test.ini"
   
      Ensure "Working Directory" is set to ${workspace_loc:MyTest}
      Press Apply to commit these changes.
   
      
   
      JRE Tab:
      Runtime JRE:
      If the Project JRE is not the (SAFS) JRE, then
      Execution environment: must point to the <SAFS\jre>
      (If the SAFS\jre is NOT listed, you will need to add it via "Installed JREs".)
      Press Apply to commit these changes.
      Press Close to finish the Run Configuration settings.
   
      
   
      

8. In the project's Datapool open and review the AppMap file App.map.

   This is a standard text-based SAFS App Map file.
   AppMap files are, essentially, in Windows INI file format.

9. Now open and review the com.sas.test.AppMap.java class file..

   You should notice that the Datapool \ App.map text file and the AppMap.java file have references to the same things.
   In fact, you MUST NOT edit the AppMap.java file because it can be dynamically built for you from the text file.
   Any manual edits you make to AppMap.java will be wiped out the next time it is dynamically generated.

10. Setup a new Eclipse "Run Configuration" to use the ComponentGenerator tool to generate this AppMap.java class.

    In the Run Menu->Run Configurations Dialog:

    New Java Application Launch Configuration:
    
       Main Tab:
       Name: Generate MyTest AppMap
       Project: MyTest
       Main class: org.safs.model.tools.ComponentGenerator
    
       
    
       Arguments Tab:
       Program Arguments:
           -in "./Datapool/App.map"
           -package "com.company.test"
           -out "./com/company/test"
           -name "AppMap"
    
       Ensure "Working Directory" is set to ${workspace_loc:MyTest}
       Press Apply to commit these changes.
    
       
    
       JRE Tab:
       Runtime JRE:
       If the Project JRE is not the (SAFS) JRE, then
       Execution environment: must point to the <SAFS\jre>
       (If the SAFS\jre is NOT listed, you will need to add it via "Installed JREs".)
       Press Apply to commit these changes.
       Press Close to finish the Run Configuration settings.
    
       
    
       

11. Now lets see this AppMap.java file get updated with changes to our App.map text file:
    1. Add a new Constant in the [ApplicationConstants] section of the App.map text file:
       UserID="myUserID"

       Be sure to Save your changes to the App.map text file.

    2. Select Run->Run Configurations... from the menu.
    3. Select the Java Application->Generate MyTest AppMap in the Dialog.
    4. Press Run to execute it.
       (Note, "Generate MyTest AppMap" will now appear in the Run History and be easier to select next time!)

    5. In Eclipse, Refresh the MyTest project by selecting it and pressing F5
       Or by right-clicking the MyTest project and selecting Refresh in the popup menu.

    6. Now look at the contents of  AppMap.java again.

       You should find in the Package Explorer, and in the Editor Window, references to the UserID item you added will now appear in AppMap.java.

12. Don't forget!
    • Any time you make a change to the  Datapool \ App.map text files
    • You need to Run the Generate AppMap tool to rebuild  AppMap.java
    • Then Refresh the project to see the changes in AppMap.java.

13. You should now review the contents of MyTest.java method TestMethodA.

    Review how the AppMap Components and Constants are used with the Runner to build SAFS tests.
    Don't forget to HOVER the mouse over the Runner, the AppMap, and their associated items and methods to see the reference documentation for each one.

    

14. Run the MyTest test using the Run MyTest Run Configuration previously prepared.
    • There should be some Console output in Eclipse showing the JSAFS bootstrap process.
    • Followed by the launching of the optional SAFS Monitor Dialog.
    • Then the launching of the Windows Calculator application.
    • Followed by SetFocus changes between the SAFS Monitor and Calculator application.
    • Finally, the shutdown of the SAFS Monitor, Calculator, and the overall test.

15. At the end of testing, Refresh the MyTest project.

16. Review the  Datapool \ Logs \ MyTest.txt  log for the test results.

17. Note the accompanying  MyTest.xml   log file has the same information along with timestamps and other information.
    The XML log is suitable for XSL Transforms into any type of test data, log, or report needed for external systems.
    There are sample XSL Transforms in %SAFSDIR% \ samples \ Log Transforms.

Carl Nagle, SAS Institute
Project Manager, SAFSDEV
Subscribe to appropriate Support Forums to review support archives and ask questons.