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. |
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:
Using the above diagram for reference, keyword development essentially follows the steps below:
|
|
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:
The literal ScriptName or ApplicationConstant can contain:
safs/IOS/jscript/custom/
safs/IOS/jscript/
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 Command | TRD.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.