SAFS iOS Developer's Guide
2012.10.26

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:

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

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.

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

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

• The SAFS/IOS Engine Java code receives the Test Record Data (inputrecord) to execute.
• The Java code has no way of knowing which type of component the command is for.
  
• All Component Functions will be implemented in or routed thru:
  org.safs.ios.CFComponent

• All IOS-specific Driver Commands will be implemented in or at least routed thru:
  org.safs.ios.IDriverCommand

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":

   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":

   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.

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:

DEBUG_TAG    ;Log a message to the SAFS Debug Log.
COMMENT_TAG  ;Log this Comment when logging to the SAFS Test Log.
DETAIL_TAG   ;Log these additional Details when logging to the SAFS Test Log.
STATUS_TAG   ;Set the Status Code to the provided Constant value (below).

The most typical Status Constants of interest:

NO_SCRIPT_FAILURE       ;The script executed with no problems.
SCRIPT_WARNING          ;The script is setting a WARNING status.
GENERAL_SCRIPT_FAILURE  ;The script is setting a FAILURE status.
EXIT_TABLE              ;The script is requesting an exit/abort of the test table.

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

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

// set an initial default status
UIALogger.logDebug(STATUS_TAG + GENERAL_SCRIPT_FAILURE);
UIALogger.logDebug(DEBUG_TAG +"My JavaScript file is now running...");

...do stuff...

// set whatever the actual final status is
UIALogger.logDebug(STATUS_TAG + NO_SCRIPT_FAILURE);
UIALogger.logDebug(DEBUG_TAG +"My JavaScript file has finished.");

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.

var DEBUG_ENABLED = false;

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

UIALogger.logDebug(DEBUG_TAG + message); // use this to ALWAYS send the message
safs_debug(message);                     // use this to conditionally send the message

Modified example using conditional SAFS Debug logging:

// set an initial default status
UIALogger.logDebug(STATUS_TAG + GENERAL_SCRIPT_FAILURE);
safs_debug("My JavaScript file is now running...");

...do stuff...

// set whatever the actual final status is
UIALogger.logDebug(STATUS_TAG + NO_SCRIPT_FAILURE);
safs_debug("My JavaScript file has finished.");

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

safs/IOS/jscript/

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

safs/IOS/jscript/custom/

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

• A variable value used to define the ScriptName or ApplicationConstant
• An ApplicationConstant to be retrieved from the AppMap

  The literal ScriptName or ApplicationConstant can contain:

• A relative "<filename>" relative to safs/IOS/jscript/custom/
• A relative "<filename>" relative to safs/IOS/jscript/
• An absolute full filepath accessible anywhere on the system.

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.

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.