Robotium Remote Control Overlay Notes
2013.08.09

Definitions, Critical Reminders, Install Instructions, Test Development, What's New

Definitions:

Overlay	Overwrite an existing install with upgraded assets (Libraries, Scripts, Source, etc).
SAFS	Software Automation Framework Support
Device	The actual Android device to be used for testing. An Emulator is also considered a device.
On-Device	Code or applications on the device targetted for testing.
AUT	App Under Test--the on-device target APK to be tested.
Messenger	The on-device SAFS TCP Messenger APK for Android testing.
RobotiumTestRunner	The on-device RobotiumTestRunner APK for Robotium Remote Control Android testing.
SAFSTestRunner	The on-device SAFSTestRunner APK for SAFS Robotium Remote Control Android testing with SAFS extensions.
Controller	The 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.
The Test	The AUT-specific Java test code developed for execution on the remote Controller.

Definitions, Overlay Instructions, Test Development, What's New

Critical Reminders:

This Overlay requires a previous installation of Robotium RemoteControl. It is intended to overlay/overwrite key portions of RobotiumRCRelease2013.07.12.
This is a cumulative Overlay. This means it contains ALL the assets modified since the Release above--including any Overlay assets that may have been available after the Release but prior to this Overlay. Consequently, you do not have to install multiple Overlays following the Release. Only the latest one needs to be applied.
This Overlay introduces the use of the enhanced 'safs-remotecontrol.jar' and removes the use of robotium-remotecontrol.jar.
The 201307.12 Release and this Overlay are intended for use with Robotium 4.2 testing on Android API Levels 15 and above. You should use earlier releases of Robotium RemoteControl using Robotium 3.6 to test pre-V4 versions of the Android operating system.

Definitions, Critical Reminders, Test Development, What's New

Install Instructions:

It is assumed all RobotiumRC installation requirements have been met. If that is not the case, then you should perform a full Release install and not an Overlay. You can apply an Overlay after installing a Release.

NOTE:

Android Emulator

AVD Manager

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.

Double-click or otherwise extract the contents of the RobotiumRCOverlay ZIP into a directory.: <workdir>
In a CMD/Shell/Terminal window navigate to the <workdir> directory and execute the appropriate installation script:
Rebuild SAFSTCPMessenger-debug.apk:
This step can be skipped if the Messenger was built automatically during the Overlay.
This build is required only once with your specific developer debug profile/certificate following an Overlay.
- Go to the SAFSTCPMessenger project and verify/edit the file local.properties:
- In a CMD/Shell/Terminal window navigate to the SAFSTCPMessenger project directory.
- Enter 'ant debug' to build the SAFSTCPMessenger-debug.apk.
- Verify the APK was built in the SAFSTCPMessenger 'bin' subfolder.
  On Windows:
  If you receive a BUILD FAILED message along with "Could not create task or type of type: componentdef.":
Rebuild RobotiumTestRunner-debug.apk:
This step can be skipped if the TestRunner was built automatically during the Overlay.
This build is required only once per AUT with your specific developer debug profile/certificate after an Overlay.
- Go to the RobotiumTestRunner project and verify/edit the file local.properties:
- For each one-time TestRunner build, edit the RobotiumTestRunner AndroidManifest.xml file:
  Within the '<instrumentation ' element set the 'android:targetPackage' attribute to match the package of the AUT you will be testing:
  (As an advanced feature, the framework can rebuild the RobotiumTestRunner at runtime to match the targetPackage of whatever AUT is specified for testing.)
- In a CMD/Shell/Terminal window navigate to the RobotiumTestRunner project directory.
- Enter 'ant debug' to build the RobotiumTestRunner-debug.apk.
- Verify the APK was built in the RobotiumTestRunner 'bin' subfolder.
  On Windows:
  If you receive a BUILD FAILED message along with "Could not create task or type of type: componentdef.":
Rebuild SAFSTestRunner-debug.apk (Optional):
This step can be skipped if the TestRunner was automatically built during the Overlay.
This build is required once per AUT with your specific developer debug profile/certificate after an Overlay.
- Go to the SAFSTestRunner project and verify/edit the file local.properties:
- 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:
  (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 SAFSTestRunner project directory.
- Enter 'ant debug' to build the SAFSTestRunner-debug.apk.
- Verify the APK was built in the SAFSTestRunner 'bin' subfolder.
  On Windows:
  If you receive a BUILD FAILED message along with "Could not create task or type of type: componentdef.":
Repackage your AUT APK with your tester/developer debug profile(if needed):

This step can be skipped if the SampleSpinner app was automatically re-signed during the Overlay.
This step may be required for each subsequent AUT build if it was not already signed with your specific developer debug profile/certificate.
- 3rd-party 're-sign.jar' is located in the SoloRemoteControl 'libs' subfolder.
- The re-sign application takes 2 parameters:
  1. <in> path to AUT apk to re-sign
  2. <out> path to newly created AUT-debug.apk
- In a CMD/Shell/Terminal window run the re-sign Java program:
  (Practice on the SampleSpinner APK provided with RobotiumRC)
  java -jar <path\to\re-sign.jar> <path\to\SpinnerActivity.apk> <out\to\SpinnerActivity-debug.apk>
- Verify the AUT-debug.apk was built in the target output path.
As a reminder, re-signing the AUT can be done automatically at runtime by properly specifying the resignjar command-line parameter available to SoloTest subclasses. Learn more about that in the section below.

Definitions, Critical Reminders, Install Instructions, What's New

Test Development:

You can use the SoloRemoteControl project installed with Robotium RemoteControl as a reference for your own Java development project.
The SoloRemoteControl/src directory contains all the sourcecode contained in the safs-remotecontrol.jar.

Create your Java development project and reference the following JAR files:
These can be found in SoloRemoteControl/libs:

safs-remotecontrol.jar (robotium-remotecontrol.jar is no longer used.)
robotium-serializable.jar ->(only needed if using new/custom serialized classes)
safsautoandroid.jar
safssockets.jar

re-sign.jar (is also present, but is not normally part of a development project)

The following can be found at <path-to-android-sdk>/tools/lib

ddmlib.jar

Create your MyTest class:
For simplicity, this class should extend the Robotium SoloTest class.
Or the SAFS SoloTest class.

The SAFS SoloTest version allows the user to take advantage of the SAFSTestRunner instead of the RobotiumTestRunner. The SAFS TestRunner provides access to SAFS Driver Commands and SAFS EngineCommands and other exposed SAFS functionality without requiring the full install and capability of the complete SAFS Automation Framework.
The source for both of these SoloTest classes can be found in the appropriate SoloRemoteControl/src subfolders.
You can find a copy of the example MyTest code below in the SoloRemoteControl/src folder at:
This example uses the smaller Robotium SoloTest class and the RobotiumTestRunner instead of the enhanced SAFS SoloTest class using the SAFSTestRunner option, but the concepts are the same for both.
Your MyTest class will need to minimally import a few classes:

Override/Provide and invoke the same constructors as SoloTest:

public MyTest(){ super(); }
public MyTest(String[] args){ super(args); }
public MyTest(String messengerApk, String testRunnerApk, String instrumentArg){
    super(messengerApk, testRunnerApk, instrumentArg);
}

Override the static 'main' method for MyTest:

public static void main(String[] args){
    SoloTest soloTest = new MyTest(args);
    soloTest.process();
}

Override and implement your 'test()' method:
This is where your remote control test code will go.
Below is a simple example of using the remote control API:

protected void test(){
  try{

      String activityID = solo.getCurrentActivity();
      Properties props = solo._last_remote_result;
      String activityName = props.getProperty(Message.PARAM_NAME);
      String activityClass = props.getProperty(Message.PARAM_CLASS);

      System.out.println("CurrentActivity   UID: "+ activityID);
      System.out.println("CurrentActivity Class: "+ activityClass);
      System.out.println("CurrentActivity  Name: "+ activityName);

  }catch(Exception e){

      e.printStackTrace();

  }
}

Refer to RobotiumTestRunner support
JavaDoc in com.jayway.android.robotium.remotecontrol.solo JavaDoc in com.jayway.android.robotium.remotecontrol

Additional SAFSTestRunner JavaDoc support
JavaDoc in org.safs.android.remotecontrol Also review: Using Serializable in Robotium RemoteControl

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

safs-remotecontrol.jar (robotium-remotecontrol.jar is no longer used.)
robotium-serializable.jar   (only needed if using new/custom serialized classes)
safsautoandroid.jar
safssockets.jar
ddmlib.jar                  (<path-to-android-sdk>/tools/lib)

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.
For example, the following command (all on one line) for the RobotiumTestRunner:
The equivalent command (all on one line) for the SAFSTestRunner:
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. For example, the installed MyTest example is able to run the same test with either the RobotiumTestRunner, or the SAFSTestRunner specified in the runner and instrument arguments. The same test can be run against different AVDs or devices, too.
Hopefully, upon execution you should see a torrent of activity appear in the console and, eventually, the SAFS Messenger service go active on the device/emulator. This would be followed by the launching of the AUT, a brief pause for the execution of the getCurrentActivity call, and then a shutdown of the AUT and SAFS Messenger service.
If all went well, you should see your System.out text not too far from the end of the console output. The output will contain something like:

Take your test automation even further...

Robotium Remote Control has been initially coded as a subproject of the SAFSDEV Project.

SAFSDEV has integrated this into the larger and more full-featured SAFS test automation framework. One development environment. One JSAFS API--regardless of the application technology being tested or the tool integrations used to test it. Thus providing extensive support for all of the technologies below within a single reusable testing framework.

Java on Windows
Web Apps on Windows
Flex Apps on Windows
.NET, WPF on Windows
Apple IOS for iPhone and iPad Apps
Android Tablet and Phone Apps
Image-Based Testing (Anything on PC/MAC screen)
Extensive NLS Support (One test, many languages)
Fully extendable for integrating other technologies and platforms.

SAFS Engines (Tool Integrations):

SAFS Android w/ Android SDK
Robotium Remote Control w/ Android SDK
Apple XCode SDK w/ IOS UIAutomation
SmartBear/AutomatedQA Test Complete
IBM Rational Functional Tester
IBM Rational Robot
Java AWT Robot w/ Java Advanced Imaging (JAI)

Definitions, Critical Reminders, Install Instructions, Test Development

What's New:

Since 2013.07.12:

Fixed getViewByName to also look in native android package(s), not just aut packages.
ProgressIndicator added for RobotiumRC Installs and Overlays.
Enhanced takeScreenshot to use SAFS ImageUtils.
Added SAFS RemoteControl (SAFSDriverCommands and SAFSEngineCommands) for RobotiumRC users of a SAFSTestRunner.
SAFS SoloTest updated to initialize robotiumUtils.
safs-remotecontrol.jar replaces robotium-remotecontrol.jar with added functionality.
SAFS FileUtilities and StringUtilities made available to RobotiumRC.
Fixed emulator boot-completion detection and emulator shutdown for all known emulator CPU types.