SAFSDROID (SAFS API DOCUMENT)

java.lang.Object
- org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass
- - org.safs.tools.engines.GenericEngine
  - - org.safs.tools.engines.SAFSDROID

All Implemented Interfaces:: ConfigurableToolsInterface, EngineInterface, GenericToolsInterface, ITestRecordStackable, RuntimeDataInterface

public class SAFSDROID
extends GenericEngine

A wrapper to Google's Android Automation SAFS engine--the "Droid" engine. This engine can only be used if you have a valid install of the Android Developer SDK tools (>=r16)--initially on a Windows computer, but intended to support Unix/Mac systems as well.

This is intended for testing of Android Smartphone and Tablet applications.

The default SAFSDRIVER Tool-Independent Driver (TID) does not provide for any command-line options to configure the Engine. All configuration information must be provided in config files. By default, these are SAFSTID.INI files. See SAFSTID Config Files for more information.

The Droid supported config file items are listed below. Remember, this engine has only been tested on Windows, so all sample file paths are in Windows format:

 [SAFS_DROID]
 AUTOLAUNCH=FALSE                     (Defaults to FALSE because config info must be valid.)
 DroidProject=C:\SAFS\samples\Droid   (Sample Droid Automation Project Location)
 Console2Debug=True/False             (Allow the process console (adb) into the driver console/debug log.)
 ;ShutdownDelay=N                      (default: 0, Delay in seconds to delay the shutdown to allow remote process completion.)
 ;HOOK=org.safs.android.DJavaHook     (Java SAFS Engine Class)
 ;EMULATOR_AVD="SprintEVO"            (User-Defined Emulator AVD to use, if any)
 ;ANDROID-SDK=Android SDK Root Dir    (Root dir for Android SDK)
 ;ANDROID-TOOLS=Android SDK Tools Dir ([Sub]Dir for Android SDK Tools)
 ;TCPMessengerAPK=path to Messenger   (default: SAFSTCPMessenger\bin\SAFSTCPMessenger-debug.apk)
 ;TCPMessengerPackage=packageName     (default: org.safs.android.messenger )
 ;TestRunnerAPK=path to Engine APK    (default: SAFSTestRunner\bin\SAFSTestRunner-debug.apk)
 ;TestRunnerPackage=packageName       (default: org.safs.android.engine )
 ;TestRunnerSource=path to source     (Ex: "SAFSTestRunner"  (Project relative or absolute)
 ;DeviceSerial=serial number          (a specific adb -s device/emulator if multiple are present)
 ;PersistEmulators=True/False         (default: false. True to NOT force shutdown of emulators)
 ;PersistJVM=True/False               (default: false. True to try to stop the shutdown of JVM.)
 ;TIMEOUT=120                         (Alternate AutoLaunch timeout value in seconds)
 ;STAFID="SAFS/DROID"                 (Normally never used.)
 ;JVM=JVMpath                         (Full path to desired Java executable if "java" is not sufficient.)
 ;JVMARGS=JVM Args                    (Ex: "-Xms512m -Xmx512m", will be used unmodified.)
 ;CLASSPATH=altClasspath              (Generally overrides system classpath.)
 ;XBOOTCLASSPATH=<CLASSPATH>       (CLASSPATH needed for rare cases. Normally never used.)
 ;ConvertSAFSInputKeysSyntax=ON|OFF   ([FUTURE]ON to use SAFS InputKeys syntax on Android)

We do use a ProcessConsole to keep the Process in, out, and err streams from filling up.

Runtime.exec
Runtime.exec Process

@author Carl Nagle DEC 15, 2011 Original Release

See Also:: ProcessCapture

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`AUTOLAUNCH_OPTION`
`static java.lang.String`	`DEBUG2CONSOLE_OPTION`
`static int`	`DEFAULT_INIT_TIMEOUT`
`static java.lang.String`	`EMULATOR_AVD_OPTION`
`static java.lang.String`	`ENGINE_NAME` "SAFS/DROID" -- The name of this engine as registered with STAF.
`static java.lang.String`	`HOOK_CLASS` "org.safs.ios.JavaHook"
`static java.lang.String`	`HOOK_OPTION`
`static java.lang.String`	`JVM_OPTION`
`static java.lang.String`	`JVMARGS_OPTION`
`static java.lang.String`	`PROJECT_OPTION`
`static java.lang.String`	`SHUTDOWN_DELAY_OPTION`
`(package private) int`	`shutdown_delay_seconds` Default 0.
`static java.lang.String`	`TIMEOUT_OPTION`
`static java.lang.String`	`XBOOTCLASSPATH_OPTION`

Fields inherited from class org.safs.tools.engines.GenericEngine
console, process, testRecordData, testrecordStackable

Fields inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass
config, customStr, customText, debugStr, debugText, driver, DRIVER_TEMP_PROCESS, failedStr, failedText, genericStr, genericText, launchCount, log, machine, otherStr, otherText, passedStr, passedText, processName, running, SAFS_RESBUN_NAME, servicename, shutdownCount, staf, STAFPROC_EXE, warningStr, warningText, weStartedService, weStartedSTAF

Fields inherited from interface org.safs.tools.engines.EngineInterface
COMMAND_SHUTDOWN_HOOK

Constructor Summary

Constructors
Constructor and Description

SAFSDROID()
Constructor for SAFS/DROID.

SAFSDROID(DriverInterface driver)
PREFERRED Constructor for SAFS/DROID.

Constructors
Constructor and Description
`SAFSDROID()` Constructor for SAFS/DROID.
`SAFSDROID(DriverInterface driver)` PREFERRED Constructor for SAFS/DROID.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`launchInterface(java.lang.Object configInfo)` Extracts configuration information and launches SAFS/DROID initialization in a new process.
`protected void`	`postShutdownServiceDelay()` Allow any emulator shutdown activities to complete before JVM terminates.
`long`	`processRecord(TestRecordHelper testRecordData)` Override superclass to catch unsuccessful initialization scenarios.

Methods inherited from class org.safs.tools.engines.GenericEngine
deduceBenchFile, deduceProjectFile, deduceTestFile, getAppMapItem, getEngineName, getVariable, isToolRunning, logMessage, makeQuotedPath, makeQuotedString, popTestRecord, pushTestRecord, reset, resetShutdownSemaphore, saveTestRecordScreenToTestDirectory, setTRDStatus, setVariable, shutdownService, waitHookShutdownAndReset

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.safs.tools.GenericToolsInterface
getCoreInterface, shutdown

- Field Detail
  - ENGINE_NAME
```
public static final java.lang.String ENGINE_NAME
```
    "SAFS/DROID" -- The name of this engine as registered with STAF.
    
    See Also:
    
    Constant Field Values
  - HOOK_CLASS
```
public static final java.lang.String HOOK_CLASS
```
    "org.safs.ios.JavaHook"
    
    See Also:
    
    Constant Field Values
  - AUTOLAUNCH_OPTION
```
public static final java.lang.String AUTOLAUNCH_OPTION
```
    See Also:
    
    Constant Field Values
  - HOOK_OPTION
```
public static final java.lang.String HOOK_OPTION
```
    See Also:
    
    Constant Field Values
  - DEBUG2CONSOLE_OPTION
```
public static final java.lang.String DEBUG2CONSOLE_OPTION
```
    See Also:
    
    Constant Field Values
  - SHUTDOWN_DELAY_OPTION
```
public static final java.lang.String SHUTDOWN_DELAY_OPTION
```
    See Also:
    
    Constant Field Values
  - PROJECT_OPTION
```
public static final java.lang.String PROJECT_OPTION
```
    See Also:
    
    Constant Field Values
  - EMULATOR_AVD_OPTION
```
public static final java.lang.String EMULATOR_AVD_OPTION
```
    See Also:
    
    Constant Field Values
  - JVM_OPTION
```
public static final java.lang.String JVM_OPTION
```
    See Also:
    
    Constant Field Values
  - JVMARGS_OPTION
```
public static final java.lang.String JVMARGS_OPTION
```
    See Also:
    
    Constant Field Values
  - XBOOTCLASSPATH_OPTION
```
public static final java.lang.String XBOOTCLASSPATH_OPTION
```
    See Also:
    
    Constant Field Values
  - TIMEOUT_OPTION
```
public static final java.lang.String TIMEOUT_OPTION
```
    See Also:
    
    Constant Field Values
  - DEFAULT_INIT_TIMEOUT
```
public static final int DEFAULT_INIT_TIMEOUT
```
    See Also:
    
    Constant Field Values
  - shutdown_delay_seconds
```
int shutdown_delay_seconds
```
    Default 0. A delay (in seconds) during shutdown allowing the remote engine process to complete shutdown activities.
- Constructor Detail
  - SAFSDROID
```
public SAFSDROID()
```
    Constructor for SAFS/DROID. Call launchInterface with an appropriate DriverInterface before attempting to use this minimally initialized object.
  - SAFSDROID
```
public SAFSDROID(DriverInterface driver)
```
    PREFERRED Constructor for SAFS/DROID.
- Method Detail
  - launchInterface
```
public void launchInterface(java.lang.Object configInfo)
```
    Extracts configuration information and launches SAFS/DROID initialization in a new process.
    
    Specified by:
    
    launchInterface in interface ConfigurableToolsInterface
    
    Overrides:
    
    launchInterface in class GenericEngine
    
    Parameters:
    
    configInfo - can be whatever the final implementation needs it to be. This might be a String with configuration information, the name of a class, or an instance of some object used to provide configuration assets.
    
    See Also:
    
    GenericEngine.launchInterface(Object)
  - postShutdownServiceDelay
```
protected void postShutdownServiceDelay()
```
    Allow any emulator shutdown activities to complete before JVM terminates. We will wait shutdown_delay_seconds seconds.
    
    Overrides:
    
    postShutdownServiceDelay in class GenericEngine
  - processRecord
```
public long processRecord(TestRecordHelper testRecordData)
```
    Override superclass to catch unsuccessful initialization scenarios.
    Specified by:
    
    processRecord in interface EngineInterface
    
    Overrides:
    
    processRecord in class GenericEngine
    
    Returns:
    the status code resulting from the processing.
    
    4 -- SCRIPT NOT EXECUTED. "I did not process this record."
    -1 -- NO SCRIPT FAILURE. "I processed the record successfully."
    -2 -- SCRIPT WARNING. "I processed the record, issued warning(s)."
    0 -- SCRIPT FAILURE. "I processed the record, issued failure(s)."
    2 -- IO FAILURE. "I process the record, issued IO failure(s)."
    8 -- EXIT TABLE. "I processed the record, exit current table."
    16 -- IGNORE STATUS. "I processed the record, ignore code and continue."
    See Also:
    
    EngineInterface#processRecord()

Class SAFSDROID

Field Summary

Fields inherited from class org.safs.tools.engines.GenericEngine

Fields inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

Fields inherited from interface org.safs.tools.engines.EngineInterface

Constructor Summary

Method Summary

Methods inherited from class org.safs.tools.engines.GenericEngine

Methods inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

Methods inherited from class java.lang.Object

Methods inherited from interface org.safs.tools.GenericToolsInterface

Field Detail

ENGINE_NAME

HOOK_CLASS

AUTOLAUNCH_OPTION

HOOK_OPTION

DEBUG2CONSOLE_OPTION

SHUTDOWN_DELAY_OPTION

PROJECT_OPTION

EMULATOR_AVD_OPTION

JVM_OPTION

JVMARGS_OPTION

XBOOTCLASSPATH_OPTION

TIMEOUT_OPTION

DEFAULT_INIT_TIMEOUT

shutdown_delay_seconds

Constructor Detail

SAFSDROID

SAFSDROID

Method Detail

launchInterface

postShutdownServiceDelay

processRecord