SAFS Android Setup
for Windows

Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php

Critical Reminders:

1. The Messenger is a general-purpose SAFS TCP Communication service on Android.  It allows us to provide remote control capabilities over TCP even for AUTs and TestRunners that DO NOT have the required INTERNET permissions necessary for TCP communications.  This service is required (and provided) for Robotium Remote Control and SAFS Android Remote Control even for AUTs that might already have INTERNET permissions.

2. The TestRunner is a general-purpose InstrumentationTestRunner created specifically for SAFS Android Remote Control.  Because the actual AUT-specific tests are on the remote Controller and NOT in the TestRunner, the TestRunner can be resigned and repackaged for testing any number of AUTs without modifying its internal code.  The TestRunner receives its remote command and control data and reports its success, failure, and results data through the Messenger service.

Setup Instructions:

SAFS Android Remote Control support and execution has the same system requirements as those required for developing standard native Android tests.  That means a Java SDK, the Android SDK, and Ant are still required.  Ideally, these should be installed prior to installing SAFS.

1. Verify (Install if needed) a Java JDK (not a JRE):
   The Java SDK should be version 1.7 or higher.
   

   * The System environment variable JAVA_HOME should be set to the path to the Java SDK.
   * The System environment variable PATH should contain the path to the Java SDK 'bin' subfolder.

2. Verify (Install if needed) the Android SDK:
   Minimally we need the Stand-alone SDK Tools. The entire Android Studio suite (Developer tools and IDE) is not required.
   The recommended *minimum* Android API Level should be Revision 15.
   

   * The System environment variable ANDROID_HOME should be set to the path to the Android SDK.
   * The System environment variable PATH should contain the paths to both the Android SDK's 'tools' and 'platform-tools' subfolders.

   NOTE:

   To test on an Android Emulator, you must verify/prepare an appropriate 'AVD' with the 'android' tool provided with the Android SDK.  Refer to the Android Developers documentation for details.

   To test on a real device, you must verify/prepare any required connections and/or drivers for your device.  Refer to the Android Developers documentation for details.

3. Verify (Install if needed) Apache Ant:
   Ant should be version 1.8 or higher.
   

   * The System environment variable ANT_HOME should be set to the path to the Ant SDK.
   * The System environment variable PATH should contain the path to the Ant SDK's 'bin' subfolder.

4. Rebuild SAFSTCPMessenger-debug.apk:
   Required only once to build with your tester/developer debug profile.
   • Go to the samples\Droid\SAFSTCPMessenger project and verify/edit the file local.properties:
     sdk.dir=<path-to-android-sdk>
     safs.droid.automation.libs=<path-to\samples\Droid\SAFSTestRunner\libs>

   • In a CMD/Shell/Terminal window navigate to the samples\Droid\SAFSTCPMessenger project directory.
   • Execute 'build.bat' to build the SAFSTCPMessenger-debug.apk.
   • Verify the APK was built in the SAFSTCPMessenger 'bin' subfolder.

5. Rebuild SAFSTestRunner-debug.apk:
   Required only once to build with your tester/developer debug profile.
   
   • Go to the samples\Droid\SAFSTestRunner project and verify/edit the file local.properties:
     sdk.dir=<path-to-android-sdk>
     

   • For a one-time TestRunner build, edit the SAFSTestRunner AndroidManifest.xml file:
     Within the '<instrumentation ' element set the 'android:targetPackage' attribute to match the package of the AUT you will be testing:
     android:targetPackage="com.android.example.spinner"

     (As an advanced feature, the framework can rebuild the SAFSTestRunner at runtime to match the targetPackage of whatever AUT is specified for testing.)

   • In a CMD/Shell/Terminal window navigate to the samples\Droid\SAFSTestRunner project directory.
   • Execute 'build.bat' to build the SAFSTestRunner-debug.apk.
   • Verify the APK was built in the SAFSTestRunner 'bin' subfolder.

6. This next step is only required to build and test the sample SpinnerActivity App.

   Rebuild Sample SpinnerActivity-debug.apk:
   Required only once to build with your tester/developer debug profile.
   

   • Go to the samples\Droid\SpinnerSample project and verify/edit the file local.properties:
     sdk.dir=<path-to-android-sdk>
     

   • In a CMD/Shell/Terminal window navigate to the samples\Droid\SpinnerSample project directory.
   • Execute 'build.bat' to build the SpinnerActivity-debug.apk.
   • Verify the APK was built in the SpinnerSample 'bin' subfolder.

Test It:

Once you have successfully completed the Setup Instructions above, you should be ready to test/verify that SAFS Android support is working.

The SAFS Droid sample comes with a ready-to-run test for the SpinnerSample provided by SAFS.  As mentioned in Definitions and the Setup Instructions above, you must have a valid emulator AVD or a real Device working properly with your Android SDK.

1. Navigate to and verify/edit samples\Droid\droidTest.ini.
   (Consult the Configuration File Options to list all available INI options for [SAFS_DROID].)
   • Edit/Verify paths in the INI file:
     1. DriverRoot
     2. ProjectRoot
     3. DroidProject
     4. Android-SDK
     5. Android-Tools
     6. TestRunnerAPK
     7. TCPMessengerAPK
     8. TargetAPK

   • Edit/Verify the EMULATOR_AVD setting if using an AVD.

2. Verify your Device is connected and properly configured for Development/Debugging.

3. If you have used Robotium Remote Control or SAFS Android support before, you should make sure you have deleted any TestRunner, Messenger, and AUT APKs previously installed on the Device.  This is especially true if you are using different SDKs on different machines (Mac, Windows, etc.) as your debug profile/certificates are different with different SDK installs.

4. You should now be ready to navigate to and execute samples\Droid\runDroidTest.bat.
   • Using an AVD will be painfully slow as the AVD takes a long time to bootstrap.
     Using a real device will prove much faster!
   • The first indication of activity on the Device will be a short note in the device Notification Bar.
     This indicates the SAFS TCP Messenger Service has been activated.
     The SAFS TCP Messenger Arrows Icon will remain in the device Notification Bar.
   • Shortly thereafter you should see the SpinnerActivity application launched on the Device.
   • The brief test will then shutdown the SpinnerActivity application and exit the test.

5. You should be able to review the test results at samples\Droid\Logs\DroidTestCycle.txt.

Consult the SAFS Keyword Reference for specific Android (DRD) support currently available in SAFS.

Specifically:

Engine Commands List
Driver Commands List
Component Functions List

Enjoy!

Carl Nagle, SAS Institute
Project Manager, SAFSDEV
Subscribe to appropriate Support Forums to review support archives and ask questons.