Testing can be boring and tedious, but its role is very important. In the long run you’ll save time fixing bugs in your application. Fortunately, Android supports many tools for testing. The ones we’ll cover include Monkey, MonkeyRunner, Robotium, and UIAutomator.

Monkey

Monkey is a simple and easy to use command line tool that is part of the Android SDK.

Monkey’s only purpose is stress testing your application. This means testing the things you would normally not test or think to test. Monkey provides a stream of random input events while your application is running with the primary goal of determining how your app preforms under such a load. This will test all kinds of strange input events and I assure you, your app will crash at some point under a corner case that you never imagined.

Monkey is not for testing specific app features and it is not smart (smart being, scriptable – you don’t tell Monkey what to do). Finally, Monkey is not a “cure-all.” It won’t find the bugs that other types of testing will find.

Monkey is simple, easy, and while not terribly exciting, it’s most definitely useful.

Monkey in action.

MonkeyRunner

In addition to stress testing, you may want to test a specific sequence of inputs. MonkeyRunner allows you to easily script your tests.

MonkeyRunner is a smarter Monkey in that it allows for better structured tests. You can do functional and regression testing using MonkeyRunner.
Some of its features include support for scripts written in Python, ability to take screenshots of the device, and the MonkeyRunner API is extensible. On the downside, it isn’t fast.

Things you’ll need to do:
• Learn Python
• Be aware that MonkeyRunner uses Jython. This means that your Python scripts can interface with java classes.

Understand how to use the three main modules of MonkeyRunner:
• MonkeyRunner – Connect to device
• MonkeyDevice – Call functions on the device (examples below)
• MonkeyImage – Take screenshots

The MonkeyRunner module allows your to connect to your device through a device object (MonkeyDevice). The device object allows you to call various methods, like:
• installPackage
• touch (pass in touch type)
• takeSnapshot
• startActivity

MonkeyRunner in action.

Robotium

Robotium is a powerful tool and API for testing your Android applications.

Robotium is more in depth and more robust than the tools mentioned above. The basic idea of Robotium is to create a testing APK that will exercise your target app through test cases that you write. In that way, it is very much like any standard testing framework. Robotium’s tag line is, “Like Selenium for Android,” so if you come from a web development background Robotium should be familiar ground for you. One more thing to note, Robotium is very fast which is a great boon to the testing experience.

On the downside, Robotuim requires some boilerplate. You’re going to have to create an APK, build with the Robotium JAR, and in general, be aware of the internals of the app you wish to test. That being said, it is quite powerful and, some might say, the de-facto testing tool for Android apps.

Robotium requires the Robotium JAR which can easily be downloaded from the Robotium website.

You’re going to need to know your APK’s package name and signature, though, you should have both if you are developing the app you wish to test.

Tests are set up by extending the main test class and writing methods for each test case. The Robotium Solo class provides the interface for testing on the device. That is, all of your testing commands will be issued from a solo object. As is the norm with testing, you’ll want to use assert to ensure test results.

If you take a look at the API later you’ll see that Robotium provides a bunch of methods, allowing you to do a lot with the app (switching activities being quite useful).

Finally, Robotium can be run from Eclipse or the command line (your preference) and provides output regarding test case success, failure, and error.

Robotium in action. 

UIAutomator

UIAutomator is a testing framework that has been added fairly recently.

It is part of the Android SDK revision 21 and up and requires your test device to have Android API version 16 or higher.

UIAutomator consists of:
• A command-line tool found on the device
• A Java library (uiautomator.jar found in the sdk/tools/) which you use in your tests
• The Android SDK tool UIAutomatorViewer which comes in handy for writing your tests
• The ability to reference UI Objects by name

UIAutomator comes with the UIAutomatorViewer tool that captures screenshot of the device and lists all the UI objects (great for identifying which components you want to test).

UIAutomater in action.

To see examples on using each tool, here are some of our presentation files:
Instrumentation101.zip

So far the tools we’ve seen, with the exception of Robotium, have done black box testing of the UI. However white box testing, whereby you test units internally, is just as important (there are a whole host of other tools that fill this role that we’ll cover in a future blog). For now, this is a primer on the types of tools available, what they are capable of,  and the roles that they fill. We hope we’ve provided a good launching point for you to get started.

The biggest thing to take away from the presentation and this blog is that you should make a habit of using some combination of these tools to test your apps. Develop a testing framework and stick to it. You are all programmers, so it should be no trouble for you to automate your tests. Don’t forget to test before every pull request!

Have any questions? Let us know in the comments.

Happy hacking,
Alex Bannerjee and Daniel Joyce

*Beginner means that you know a bit about Android and Java in general, if not, learn a bit first and come back. Experience in the terminal environment on your machine is also probably necessary.

The Apk

In order to start reverse engineering, you must first understand what you’re working with. So what exactly is an apk? (hint: not American Parkour.) An Android package, or apk, is the container for an Android app’s resources and executables. It’s a zipped file that contains simply:

• AndroidManifest.xml (serialized, non human readable)
• classes.dex
• res/
• lib/ (sometimes)
• META-INF/

The meat of the application is the classes.dex file, or the Dalvik executable (get it, dex) that runs on the device. The application’s resources (i.e. images, sound files) reside in the res directory, and the AndroidManifest.xml is more or less the link between the two, providing some additional information about the application to the OS. The lib directory contains native libraries that the application may use via NDK, and the META-INF directory contains information regarding the application’s signature.

You can grab the HelloWorld apk we will be hacking here. The source to this apk is available from the developer docs tutorial, and when compiled looks something like this:

Flashy, huh

The Tools

In order to complete this tutorial, you’ll need to download and install the following tools:

• apktool
• jarsigner
• keytool

Disassembling the Apk

Once you’ve installed apktool, go ahead and open up your terminal and change directory into where you’ve placed the downloaded apk.

$ cd ~/Desktop/HelloWorld

Execution of the apktool binary without arguments will give you its usage, but we will only use the ‘d’ (dump) and ‘b’ (build) commandline options for this tutorial. Dump the apk using the apktool ‘d’ option:

$ apktool d HelloWorld.apk

This will tell the tool to decode the assets and disassemble the .dex file in the apk. When finished, you will see the ./HelloWorld directory, containing:

• AndroidManifest.xml (decoded, human readable)
• res/ (decoded)
• smali/
• apktool.yml

The AndroidManifest.xml is now readable, the resources have been decoded, and a smali directory has been created (ignore the apktool.yml as it’s just a configuration for the tool itself). The smali directory is probably the most important of the three, as it contains a set of smali files, or bytecode representation of the application’s dex file. You can think of it as an intermediate file between the .java and the executable.

So let’s take a look at what’s in the smali directory , ‘ls’ yields:

 $ ls HelloWorld/smali/com/test/helloworld/
HelloWorldActivity.smali
R$attr.smali
R$drawable.smali
R$layout.smali
R$string.smali
R.smali

Immediately we notice that the smali directory contains subdirectories defining the application’s namespace (com.test.helloworld). Additionally, we can see an individual smali file for each java class. There’s one catch – any ‘$’ in the smali file’s name means it’s an inner class in Java. Here we see the bytecode representation of the following classes:

• HelloWorldActivity.java
• R.java

Where R.java contains inner classes attr, string, and so on. It’s evident that HelloWorldActivity is the activity that’s displayed when the app launches, so what exactly is R?

R.java is an automatically generated file at application build time that maps resources to an associated id. When a developer wants to use anything in the res folder, he/she must use the R class to appropriately reference that resource. Because of this, we’ll omit the R.java from our investigation, as it really only contains a bunch of constants that no one cares about.

Reading the Smali

Now that we’ve disassembled our apk, let’s take a look at the java and smali representations of our impressive HelloWorldActivity.

package com.test.helloworld;

import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;

public class HelloWorldActivity extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        TextView text = new TextView(this);
        text.setText("Hello World, Android");
        setContentView(text);
    }
}
.class public Lcom/test/helloworld/HelloWorldActivity;
.super Landroid/app/Activity;
.source "HelloWorldActivity.java"

# direct methods
.method public constructor ()V
    .locals 0

    .prologue
    .line 7
    invoke-direct {p0}, Landroid/app/Activity;->()V

    return-void
.end method

# virtual methods
.method public onCreate(Landroid/os/Bundle;)V
    .locals 2
    .parameter "savedInstanceState"

    .prologue
    .line 11
    invoke-super {p0, p1}, Landroid/app/Activity;->onCreate(Landroid/os/Bundle;)V

    .line 13
    new-instance v0, Landroid/widget/TextView;

    invoke-direct {v0, p0}, Landroid/widget/TextView;->(Landroid/content/Context;)V

    .line 14
    .local v0, text:Landroid/widget/TextView;
    const-string v1, "Hello World, Android"

    invoke-virtual {v0, v1}, Landroid/widget/TextView;->setText(Ljava/lang/CharSequence;)V

    .line 15
    invoke-virtual {p0, v0}, Lcom/test/helloworld/HelloWorldActivity;->setContentView(Landroid/view/View;)V

    .line 17
    return-void
.end method

It should be pretty evident which one of these files is written in java, nonetheless, the smali representation shouldn’t be too intimidating.

Let’s break down whats going on here in java first.  In line 07, we define our HelloWorldActivity class that extends android.app.Activity, and within that class, override the onCreate() method. Inside the method, we create an instance of the TextView class and call the TextView.setText() method with our message. Finally, in line 15 we set the view by calling setContentView(), passing in the TextView instance.

In smali, we can see that we have a bit more going on. Let’s break it up into sections, we have:

1. class declarations from lines 01-03
2. a constructor method from lines 07-15
3. a bigger onCreate() method from lines 19-43

V	 void
Z	 boolean
B	 byte
S	 short
C	 char
I	 int
J	 long (64 bits)
F	 float
D	 double (64 bits)

v0 - local 0
v1 - local 1
v2/p0 - local 2 or parameter 0 (this)
v3/p1 - local 3 or parameter 1 (android/os/Bundle)

Opcodes

Dalvik opcodes are relatively straightforward, but there are a lot of them. For the sake of this post’s length, we’ll only go over the basic (yet important) opcodes found in our example HelloWorldActivity.smali. In the onCreate method in HelloWorldActivity the following opcodes are used:

1. invoke-super vx, vy, … invokes the parent classes method in object vx, passing in parameter(s) vy, …
2. new-instance vx creates a new object instance and places its reference in vx
3. invoke-direct vx, vy, … invokes a method in object vx with parameters vy, … without the virtual method resolution
4. const-string vx creates string constant and passes reference into vx
5. invoke-virtual vx, vy, … invokes the virtual method in object vx, passing in parameters vy, …
6. return-void returns void

Hacking the App

Now that we know what we’re looking at, lets inject some code and rebuild the app. The code we will inject is only one line in java and presents the user with the toast message “hacked!”.

Toast.makeText(getApplicationContext(), "Hacked!", Toast.LENGTH_SHORT).show();

How do we do this in smali? Easy, let’s just compile this into another application and disassemble. The end result is something like this:

    .line 18
    invoke-virtual {p0}, Lcom/test/helloworld/HelloWorldActivity;->getApplicationContext()Landroid/content/Context;

    move-result-object v1

    const-string v2, "Hacked!"

    const/4 v3, 0x0

    invoke-static {v1, v2, v3}, Landroid/widget/Toast;->makeText(Landroid/content/Context;Ljava/lang/CharSequence;I)Landroid/widget/Toast;

    move-result-object v1

    invoke-virtual {v1}, Landroid/widget/Toast;->show()V

Now, let’s ensure we have the right amount of registers in our original onCreate() to support these method calls. We can see that the highest register in the code we want to patch is v3, which we have but will require us to overwrite both of our parameter registers. Given we won’t be using either of those registers after setContentView(), this number is appropriate. Our final patched HelloWorldActivity.smali should look like:

.class public Lcom/test/helloworld/HelloWorldActivity;
.super Landroid/app/Activity;
.source "HelloWorldActivity.java"

# direct methods
.method public constructor ()V
    .locals 0

    .prologue
    .line 8
    invoke-direct {p0}, Landroid/app/Activity;->()V

    return-void
.end method

# virtual methods
.method public onCreate(Landroid/os/Bundle;)V
    .locals 2
    .parameter "savedInstanceState"

    .prologue
    .line 12
    invoke-super {p0, p1}, Landroid/app/Activity;->onCreate(Landroid/os/Bundle;)V

    .line 14
    new-instance v0, Landroid/widget/TextView;

    invoke-direct {v0, p0}, Landroid/widget/TextView;->(Landroid/content/Context;)V

    .line 15
    .local v0, text:Landroid/widget/TextView;
    const-string v1, "Hello World, Android"

    invoke-virtual {v0, v1}, Landroid/widget/TextView;->setText(Ljava/lang/CharSequence;)V

    .line 16
    invoke-virtual {p0, v0}, Lcom/test/helloworld/HelloWorldActivity;->setContentView(Landroid/view/View;)V

    # Patches Start

    invoke-virtual {p0}, Lcom/test/helloworld/HelloWorldActivity;->getApplicationContext()Landroid/content/Context;

    move-result-object v1

    const-string v2, "Hacked!"

    const/4 v3, 0x0

    invoke-static {v1, v2, v3}, Landroid/widget/Toast;->makeText(Landroid/content/Context;Ljava/lang/CharSequence;I)Landroid/widget/Toast;

    move-result-object v1

    invoke-virtual {v1}, Landroid/widget/Toast;->show()V

    # Patches End

    return-void
.end method

Lines 40+ contain the injected code.

Rebuilding the Apk

Now all that’s left is to rebuild the app!

$ apktool b ./HelloWorld

This will instruct apktool to rebuild the app, however, this rebuilt app will not be signed. We will need to sign the app before it can be successfully installed on any device or emulator.

Signing the Apk

In order to sign the apk, you’ll need jarsigner and keytool (or a platform specific alternative, like signapk for windows). With jarsigner and keytool, however, the steps are pretty easy. First create the key:

$ keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -validity 10000

Then use jarsigner to sign your apk, referencing that key:

$ jarsigner -verbose -keystore my-release-key.keystore ./HelloWorld/dist/HelloWorld.apk alias_name

Then you’re done! Install the app onto your device or emulator and impress the shit out of yourself!

damn…impressive

That’s it for this tutorial, but stay tuned. There will definitely be more in the future. Feel free to leave any questions in the comment section, or contact me with any questions.

Happy hacking,

David Teitelbaum

One thing that can be a little confusing with Python is how packages work. Packages let you group your modules together and gives you a nice namespace. You can read all about them in the Python docs.

Something that’s pretty confusing is that importing a package does not mean that any modules inside that package are loaded.

Imagine a very simple package called testing, with a single foo module. E.g:

testing/
    __init__.py
    foo.py

The foo module might look something like:

def bar():
    return 'bar'

Now, you might expect to be able to write code such as:

import testing
print(testing.foo.bar())

However, trying this won’t work, you end up with anAttributeError:

Traceback (most recent call last):
  File "t.py", line 2, in 
    testing.foo.bar()
AttributeError: 'module' object has no attribute 'foo'

So, to fix this you need to actually import the module. There are (at least) two ways you can do this:

import testing.foo
from testing import foo

Either of these put testing.foo into sys.modules, andtesting.foo.bar() will work fine.

But, what if you want to load all the modules in a package? Well, as far as I know there isn’t any built-in approach to doing this, so what we’ve come up with is a pretty simple function that, given a package, will load all the modules in the package, and return them as a dictionary keyed by the module name.

def plugin_load(pkg):
    """Load all the plugin modules in a specific package.

    A dictionary of modules is returned indexed by the module name.

    Note: This assumes packages have a single path, and will only
    find modules with a .py file extension.

    """
    path = pkg.__path__[0]
    pkg_name = pkg.__name__
    module_names = [os.path.splitext(m)[0] for m in
                    os.listdir(path)
                    if os.path.splitext(m)[1] == '.py' and m != '__init__.py']
    imported = __import__(pkg_name, fromlist=module_names)
    return {m: getattr(imported, m) for m in module_names}

There are plenty of caveats to be aware of here. It only works with modules ending in .py, which may miss out on some cases. Also, at this point it doesn’t support packages that span multiple directories (although that would be relatively simple to add). Note: code testing on Python 3.2, probably needs some modification to work on 2.x (in particular I don’t think dictionary comprehensions work in 2.x).

If you’ve got a better way for achieving this, please let us know in the comments.

Benno Leslie

Here’s a way to ensure you’ll never have the issue again: we’ve created an adb_usb.ini containing every known Android vendor id! For good measure, we then went and threw in every other USB vendor on the planet – perhaps it will inspire them to some day create an Android device

To clone into your .android directory (for easy updating via git):

$ cd ~/.android
$ rm adb_usb.ini
$ git init
$ git remote add origin git@github.com:apkudo/adbusbini.git
$ git pull origin master

Alternatively, to just copy the latest file directly into your .android:

$ curl -L http://raw.github.com/apkudo/adbusbini/master/adb_usb.ini 
 --O ~/.android/adb_usb.ini

A parseable listing, in case you have other uses for the data, is included in VENDORS, using the following format:

<vendor_id> <is_android_vendor> <vendor_name>

For data sources, we used every Android device that we have (which is, we believe, all of them), the Linux USB listing at http://www.linux-usb.org/usb.ids, and the USB listing at http://www.usb.org/developers/tools/comp_dump. If you’re interested, the tool used to scrape the web data sources is in adbusbini_scrape.py.

Updates are very much encouraged and appreciated – please either submit a pull request or email to josh@apkudo.com.

Happy hacking,

Josh

Alas, our journey continues. Our odyssey starts with the awesome blog post “Installing Google Play on Android Emulator.” The author, Piotr Buda, was able to successfully install the Google Play application on an emulator. However, you’ll notice that in the comments and subsequent blog post he (and his readers) were unable to download and install applications: the effects of the dastardly Error 491. Additionally, the applications they were able to view were severely limited. After reading both posts, the Apkudo team attempted to take it a step further and a) get downloads working and b) be able to browse and download any app.

Installing Google Play on an Android emulator requires three separate APKs: GoogleLoginService.apk, GoogleServicesFramework.apk, and Phonesky.apk (older versions will be named ‘Vending.apk’.) All three are located in the /system/app/ folder on your device. You can issue an adb pull command to pull each one off of your device (you generally don’t need root to pull). We pulled ours off of a Samsung Galaxy S III (the version of the store that we pulled was 3.5.16)

Next we just push the three APKs to install on the emulator (we made a simple modification to the shell script from the original blog post):

#!/bin/sh
echo "remounting..."
adb remount
echo "pushing login apk..."
adb push GoogleLoginService.apk /system/app/.
echo "pushing framework apk..."
adb push GoogleServicesFramework.apk /system/app/.
echo "pushing vending apk..."
adb push Phonesky.apk /system/app/.
echo "done"

Once the three APKs are installed, it is trivial to get the market executing. You’ll need to enter your account information when prompted and accept the market update if required (the update will generally not be successful, but it doesn’t seem to matter). You should now be able to browse and search the Play Store. Except, of course, you’ll usually hit an Error 491 when you try to download!

Solving Error 491

If you have created your AVD for ICS or earlier you will undoubtedly encounter Error 491 when attempting to download an application. The reason is that a shared object file, libdrmframework_jni.so is missing from the /system/lib/ folder. You may also find that the DrmProvider.odex and DrmProvider.apk files are missing from the /system/app/ folder. It seems that standard Android AVD images do not include these files. In order to circumvent this, you can build the Android platform from source (see http://source.android.com/source/initializing.html); your AVDs should now include the relevant DRM files. (Note: pulling the .so off of your device and pushing them to the emulator will generally not work.) You can also, of course, just create an AVD for 4.1 Jelly Bean: AVDs that target 4.1 appear to include those missing files and should be able to download applications easily.

Google Play on an emulator.

Move along, not too many apps to see here!

Downloading Solitaire. Side note: I’m pretty good at Solitaire.

Circumventing Google Play Filters

As you browse the Play Store you’ll notice a startling lack of available applications. The Google Play Store filters the apps that you can view based on a handful of factors relating to hardware, software, and carrier. You can find most filters listed here: http://developer.android.com/guide/google/play/filters.html

Depending on which features you give your AVD, you will see a variety of available apps. However, you’ll still be unable to view a great deal of what the store has to offer simply because your AVD lacks a great many features. Therefore, we’ll need to get our hands dirty with the innards of the Google Play code (this could probably be accomplished in a few other ways, but this was the most practical.)

The basic idea is to capture and mock all of the device identifying information and metadata that Play compiles before it is sent off on the wire. You’ll first need to unzip each APK: unzip {apk} -d {out_dir}. Then, remove the META-INF folder within each (we’ll re-sign each APK later.) Use baksmali on the classes.dex of both Phonesky.apk and GoogleServicesFramework.apk. Now you’ll have access to the smali code for each APK.

Inside the  decompiled GoogleServicesFramework you’ll find a file entitled /com/google/android/gsf/checkin/CheckinRequestBuilder.smali. Poke around a bit, and you’ll notice that it contains a host of device identifying information, all of which we must intercept and mock. Inside the decompiled Phonesky you’ll find two files entitled /com/google/android/finsky/utils/DeviceConfigurationHelper.smali and /com/google/android/finsky/utils/VendingUtils.smali respectively. Again, each file contains device identifying information that Google Play will eventually serialize, send off into the cloud, and use to filter the apps that you can view on the store.

So now that we know what data is being sent, how do we intercept it and mock it?  First, you’re going to need data to mock. This is relativley simple, as you can pull most of that information from a real phone using some combination of adb shell getprop, adb shell pm, and adb shell dumpsys. On the other hand, you can build a simple application that pulls all of this data and dumps it out in a neat little file. The next step is to build a framework for mocking data. I built a java class composed entirely of static methods (it is very easy to hand insert into smali code (with some register finagling)) that I compiled and then decompiled back into smali. Inside each of the decompiled Google APKs, make the appropriate directories for your classes package, and copy over the smali file. You should now be able to call any of your static methods from Google code.

Now its a matter of using grep to find the right method calls in the files mentioned above. For each method found, comment it out, and insert your own, mocked method call.  For example, in DeviceConfigurationHelper.smaliI’ve replaced the call

invoke-virtual {v4}, Landroid/content/pm/PackageManager;->getSystemAvailableFeatures()[Landroid/content/pm/FeatureInfo;

with a call to my own getSystemAvailableFeatures() method. Finally, you’ll need to use smali to re-compile all of the code back into a classes.dex file (replace the old ones in Phonesky and GoogleServicesFramework respectively), re-zip into each into an apk (including GoogleLoginService), and re-sign each using jarsigner. Push them onto the emulator as always and you should be good to go.

Play thinks we’re a Galaxy Nexus!

Downloading Angry Birds Space.

Playing our downloaded app on the emulator!

For now, you can only download and install free apps. As you might imagine, getting paid apps on an emulator is a bit trickier. We’ll save that for a later post.

Happy hacking,

-Daniel Joyce, Software Engineer

You may wish to reference the following:
Smali and Baksmali
Android Api
Google Play Filters