SAFS iOS Developer's Guide
2012.10.26


Definitions:

SAFS Software Automation Framework Support
SAFS Driver The tool that initializes, opens, parses, and routes SAFS test records to available SAFS Engines.
SAFS Engine A keyword-driven automation tool capable of interpreting and executing SAFS test records.
SAFS/IOS (IOS) A SAFS Engine for the UIAutomation Instrument provided by the Apple IOS Development SDK.

Design:
Top, Develop, Debug, CallScript

A typical SAFS Engine can dynamically interact at runtime with the SAFS Driver via a Java API, COM objects, or some other mechanism allowing 2-way communication:

Typical Driver Engine App Interface

The SAFS IOS Engine is a bit more complicated than that:

SAFS IOS Engine App Interface

Note the denotes areas requiring development for each SAFS keyword to be implemented.  As you can see, a typical implementation is handled in one location using one codebase or API.  In SAFS/IOS, we are required to develop a SAFS Java side and a UIAutomation Javascript side for every implemented keyword.


Develop:
Top, Design, Debug, CallScript

Below is an attempt to show SAFS IOS keyword development requirements:

SAFS IOS Engine Keyword Development

Note a few items that are important to recognize during keyword development:

Using the above diagram for reference, keyword development essentially follows the steps below:

  1. Implements the "click.js" JavaScript code to process the keyword "click":
    SAFS IOS JavaScript
    • tag any debug messages for the Java code to log,
      (See the Debug section below for more info.)
    • extract window and component recognition information from trd.js,
    • extract any other information (ex: coords) required from trd.js,
    • search for the IOS window and component to be acted upon,
    • perform the action on the component, or log "not found",
    • tag appropriate return codes and messages for the Java code to log.

  2. Implement Java code to process the keyword "click":

    SAFS IOS Engine Java Code
    • verify all required parameters are present,
    • gather all necessary SAFS Test Record Data to convert to JavaScript,
    • gather any App Map data needed to convert to JavaScript,
    • gather any parameter data needed to convert to JavaScript code,
    • write the trd.js JavaScript for import into static SAFSRuntime.js,
    • copy "click.js" to "hook.js" for import into static SAFSRuntime.js,
    • trigger the execution of SAFSRuntime.js in Instruments,
    • wait for the execution to be finished,
    • log the results of the execution as parsed from the UIAutomation Instruments log.

Developers should review existing SAFS IOS keyword implementations on both the Java side and the JavaScript side for real-world examples and reference.


Debug:
Top, Design, Develop, CallScript

The SAFS/IOS Engine can only know what's going on in the device by monitoring the UIAutomation debug log.   Thus, all standard SAFS messaging, status, and debug logging from the device is retrieved out of the UIAutomation log while the test is running.

On the JavaScript side all UIAutomation messaging intended for SAFS monitoring and logging are prefixed with special TAGS indicating the type of message being logged so that SAFS can route the message appropriately.

Generally, there are 4 TAG Constants of interest:

The most typical Status Constants of interest:

The developer should review the safs/IOS/jscript/constants.js file for more.

Example usage within the JavaScript: [ UIALogger.logDebug(<TAG> + message) ]

Note that every message logged directly via UIALogger is sent and impacts overall performance.
Embedding a large amount of SAFS Debug messages (DEBUG_TAG) in this way can potentially produce a significant and noticeable performance degradation.

To alleviate this, there is a safs/IOS/jscript/safs_debug_settings.js file in which we can enable and disable SAFS Debug messages from actually being sent.   By setting the DEBUG_ENABLED var in this file we can turn on or off the sending of these messages.

In order to take advantage of this feature there is another function to call when logging the SAFS Debug messages:

Modified example using conditional SAFS Debug logging:


CallScript:
Top, Design, Develop, Debug

SAFS testers have access to a special "CallScript" Driver Command.

This allows testers to create their own custom JavaScript to be executed at runtime.   Any number of custom scripts can be called at various times during the testing run without having to close and reopen the UIAutomation Instrument--or the Application being tested.

The IOS JavaScript developer has access to all the normal JavaScript objects and API provided by UIAutomation.   In addition, the developer has access to all the SAFS JavaScript code and Utilities found at

This includes all the SAFS logging and SAFS Debug logging capabilities discussed in the preceding Debug section.

Note the custom JavaScript must be accessible to Java on the system.  By default, we have provided a custom JavaScript directory for IOS at

However, the IOS CallScript implementation will allow for the ScriptName parameter to be:

In addition, the SAFS tester can pass variable parameters making them available to the custom JavaScript.   See the "CallScript" command documentation for usage.

In essence, the parameters are available to the JavaScript via trd.js as variables.   The name of each custom variable is dependent upon how they were processed by the CallScript DriverCommand.

CallScript CommandTRD.js Variables
C, CallScript, "MyScript",  "USERID=papa",  "DOMAIN=ios" var USERID="papa"
var DOMAIN="ios"
C, CallScript, "MyScript",  "papa",  "ios" var VAR1="papa"
var VAR2="ios"
C, CallScript, "MyScript",  ^USERID="papa",  ^DOMAIN="ios" var VAR1="papa"
var VAR2="ios"

A simple reminder to SAFS testers: it is important to note that SAFS variable expressions are processed and dereferenced BEFORE the CallScript command is executed.  That is why the 3rd example above produces the JavaScript variables shown.


Top, Design, Develop, Debug, CallScript