SAFS Framework for Mac/iOS Release Notes
2012.06.22

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

Install Instructions:

1. After you login, go to directory where you put the SAFSIOSRelease ZIP file.
2. Double-Click it or otherwise extract the contents of the ZIP file into a directory.
3. In Terminal, navigate to the Setup-IOS-SAFS.sh installation script.
4. Run 'sudo ./Setup-IOS-SAFS.sh' in Terminal. (OS X Lion requires 'sudo' for mkdir and chmod.)

   If the script does not run at all:

   • make sure the scripts and installers are executable:
     chmod u+x *.sh
     chmod u+x *.bin
     

   • prefix the shell: '/bin/sh Setup-IOS-SAFS.sh'
     (Don't forget to use sudo, if necessary.)

5. Follow the script's instructions which will prompt for things like:
   • Confirm to install STAF and where to install STAF.
   • Confirm to install SAFS and where to install SAFS.
   • Confirm to see verbose information during installation.
   • Use {Enter} at each prompt to install SAFS and STAF to the default locations:

     STAF --> /Library/staf
     SAFS --> /Library/safs

6. Run the runTIDTest (SAFS Tools below) to verify a successful SAFS install.
7. Run the runIOSTest (SAFS Tools below) to verify successful SAFS/IOS integration.
8. The log outputs for those tests can be found at:
   /Library/safs/Project/Datapool/Logs

SAFS Tools:

After a successful install, these can be found in your SAFS Project directory which, by default, is located at:

/Library/safs/Project:
• runTIDTest
  Used generally to verify the SAFS Install, or that SAFS is currently configured correctly for execution.

• runIOSTest
  Used to run a sample IOS test against our SAFS/samples/UICatalog application.

• runIOSProcessContainer
  Used to run the IOS Process Container tool for app exploration and SAFS App Map creation.

• runImageManager
  A Java-based Image Manager option for capturing images to be used for SAFS Image-Based Testing.

• SAFSTESTLOG_Startup
  Used to start a SAFS Debug Log.
  There is also a (silent) Using Debug Video Tutorial for Windows users that is just as valuable to Mac users.
  (Though it does require a Flash Player.!)

• SAFSTESTLOGShutdown
  Used to stop a running SAFS Debug Log.  See the same doc and video for SAFSTESTLOG_Startup.

Setup Notes:

In order to process or test your own applications with SAFS/IOS, you must create one or more UIAutomation Instrument Trace Templates.  It is beyond the scope of this document to go into any detail on using Instruments.  Please consult the Apple Documentation for Instruments for more information.

Different versions of OS X and the IOS SDK have different variations of the supplied tools.  The information below was originally captured using a version of IOS SDK 5 on OS X Snow Leopard (OSXSL).  OS X Lion (OSXLN) support info is also provided.

To create a proper trace template, these basic steps need to be accomplished:

1. Launch a new blank Instruments app:
   Default OSXSL: /Developer/Applications/Instruments.app
   Default OSXLN: /Applications/Xcode.app/Contents/Applications/Instruments.app

2. In Instruments, "Choose Target" and navigate to the Application and Device/Simulator to be tested.
   

3. Specify the Options for this specific Application and Template:
   
4. Load the Built-In UIAutomation Library (Automation) as the default (only?) Instrument to record.
   
   

5. Enable the Bottom Pane for Automation Options, if necessary
   

6. Specify to "Run on Record" and "Continuously Log Results".
   

7. "Choose Location" to specify the output directory for Automation Results.
   This will be the location where the Instruments log will be generated and monitored by SAFS.
   

   Navigate to the location of your expected output.  For our SAFS example:

   /Library/safs/samples/UICatalog

8. Save this as a Trace Template.
   

   Navigate to the location to store and name the Trace Template.  For our SAFS example:

   /Library/safs/samples/UICatalog/UICatalogInstruments.tracetemplate

   NOTE: SAFS expects the ".tracetemplate" extension to be used for these templates.

9. Currently, SAFS can only handle testing IOS applications through Instruments as long as it is SAFS that has prepped and launched the Instruments application with an appropriate UIAutomation Trace Template.

10. The same Trace Template used for the SAFS runtime can be used by the IOS Process Container.

11. To launch your application during SAFS testing, you must use the following Driver Commands:

    C, UseIOSFunctions  , ON
    C, LaunchApplication, "AppName", TemplatePath, OutputDirectory
    

    TemplatePath and OutputDirectory should be the full paths to the Instruments Trace Template and the Logging output directory specified in the Trace Template.   You can review IOSTest.CDD and iosPOC.map in the /Library/SAFS/Project/Datapool directory for examples of using these commands and storing these settings in the Application Map ApplicationConstants.

    OS X Lion introduces new defects in Xcode Instruments and AppleScript execution that prevent the previously simple use of Instruments Trace Templates.  For this reason, IOS Process Container and the LaunchApplication Driver Command REQUIRE the specification of devicename and appname parameters when using OS X Lion.

12. To close your application during SAFS testing, or when ending SAFS testing, you must use the following Driver Commands:

    C, UseIOSFunctions , ON
    C, CloseApplication, (Anything)
    

    We can use "Anything" for the IOS CloseApplication implementation because it knows we are shutting down all running Instruments UIAutomation traces.

Critical Reminders:

1. Run all SAFS Shell scripts using appropriate shell command-line syntax.
2. Most SAFS Shell scripts are currently expected to be run from their parent directory.
3. Examples of command-line invocation--all from a Terminal working directory of /Library/safs/Project:

   . runTIDTest.sh  OR
   /bin/sh runTIDTest.sh
   
   . runIOSTest.sh  OR
   /bin/sh runIOSTest.sh
   

4. Always make sure Shell scripts are "executable":

   chmod u+x *.sh
   

New Stuff: