SAFS Android Setup
for Windows

Updated 2015.10.15

Authors:

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


Definitions, Critical Reminders, Setup Instructions, Test It RemoteControl

Definitions:

SAFS Software Automation Framework Support
DeviceThe actual Android device to be used for testing.
An Emulator is also considered a device.
On-DeviceCode or applications on the device targetted for testing.
AUTApp Under Test--the on-device target APK to be tested.
MessengerThe on-device SAFS TCP Messenger APK for Android testing.
TestRunnerThe on-device SAFS Test Runner APK for SAFS Android Remote Control testing.
ControllerThe computer used to remotely control the test on the device.
For simplicity, the test development machine and the Controller are assumed to be the same.
For SAFS, the SAFS Android Engine is considered the Controller.
The TestThe SAFS keyword-driven tests or JSAFS tests developed for execution by SAFS.
More native SAFS/Robotium Remote Control tests are also possible.

Definitions, Setup Instructions, Test It RemoteControl

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.


Definitions, Critical Reminders, Test It RemoteControl

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:

  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.

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

  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.


Definitions, Critical Reminders, Setup Instructions RemoteControl

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 Droid Support Icon Android (DRD) support currently available in SAFS.

Specifically:

Enjoy!


Definitions, Critical Reminders, Setup Instructions Test It

Remote Control Development:

You can also use the SoloRemoteControl project installed with the Droid samples as a reference for your own Java test development project for SAFS/Robotium Remote Control.  This is completely different than writing SAFS Test Tables with Driver Commands and Component Functions.  This is for Java developers, or testers with Java develoment experience.

The SoloRemoteControl/src directory contains all the sourcecode contained in the safs-remotecontrol.jar.

  1. Create your Java development project and reference the following JAR file:
    It can be found in SoloRemoteControl/libs:

    The quickest way to do the above in Eclipse:
    
        Create a New->Java Project from the existing source at:
    
        samples\Droid\SoloRemoteControl
    

  2. Create/Review your MyTest class:
    For simplicity, this class should extend the SoloTest class.
    The source for SoloTest can be found in the SoloRemoteControl/src folder at:

    You can find the existing sample MyTest code in the SoloRemoteControl/src folder at:

    Your MyTest class will need to minimally import a few classes:

  3. Review/Override/Provide and invoke the same constructors as SoloTest:

  4. Review/Override the static 'main' method for MyTest:

  5. Review/Override and implement your 'test()' method:
    This is where your remote control test code will go.
    Below is the code in the existing MyTest.java:

    Refer to: JavaDoc for com.jayway.android.robotium.remotecontrol.solo
              JavaDoc for com.jayway.android.robotium.remotecontrol
    
    Also review: Using Serializable in SAFS/Robotium RemoteControl
    

  6. Compile your work appropriate for your development environment:
    Remember, the minimum JAR file needed in the Java build path (CLASSPATH):

    (The above can be found in the SoloRemoteControl/libs folder.)

  7. Run the test using all appropriate command-line parameters for SoloTest:
    Remember, the same JAR files needed for the build are needed in the CLASSPATH for execution.
    In addition, there is also a runtime dependency on an Android SDK lib:

    The following command (all on one line) for MyTest (see the runSoloTest file below):

    Of course, you can hardcode your arguments and paths in MyTest.java, or create a script file that performs the invocation for you.  We show the arguments here so the user can get an idea of what is involved, and arguments that might be able to be changed with the same test class.  The same test can be run against different AVDs or devices, too.

    1. Navigate to and verify/edit samples\Droid\runSoloTest.

      • Verify -Dandroid-home= points to the Android SDK.
      • Edit/Verify paths in the BAT file:

        1. avd=yourAVD, if any
        2. aut=pathTo\SpinnerActivity-debug.APK
        3. runner=pathTo\SAFSTestRunner-debug.APK
        4. messenger=pathTo\SAFSTCPMessenger-debug.APK
        5. instrument=org.safs.android.engine/org.safs.android.engine.DSAFSTestRunner

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

    3. If you have used SAFS/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\runSoloTest.

      • 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.

    Hopefully, upon execution you should see a torrent of activity appear in the console as everything mentioned above transpires.

    Upon completion, the default "RemoteControl.log" is stored in the "current working directory".
    The default runSoloTest script should have that in the SoloRemoteControl\bin.

    The log will contain something like:


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