Introduction

SwiftHand is an automated Android GUI testing tool. The tool uses machine learning to learn a model of the target app during testing, uses the learned model to generate user inputs that visit unexplored states of the app, and uses the execution of the app on the generated inputs to refine the model.

The main purpose of the repository is to provide a working demo of the version of the SwiftHand tool submited to the OOPSLA'13 conference. The repository provides source code for both front-end (instrumentation) and back-end (test engine). Example applications to paly with are also included.

The document is assuming that your system is either Linux or OSX. If you are Windows user, we recommend to use a free virtuallization tool such as VirtualBox and Docker.

Installation

Step 1. Install Android Development Kit (ADK)

Before playing with SwiftHand, please make sure to install the Android SDK (ADK). You can download it from http://developer.android.com/sdk/index.html. We recommend to use ADK 4.1.2 or a higher version. After installing ADK, please make sure that you have following six files.

• <ADK_ROOT>/platform-tools/adb
• <ADK_ROOT>/tools/lib/ddms.jar
• <ADK_ROOT>/tools/lib/ddmlib.jar
• <ADK_ROOT>/tools/lib/chimpchat.jar
• <ADK_ROOT>/tools/lib/guava-17.0.jar (version may vary)
• <ADK_ROOT>/build-tools/21.0.3/lib/dx.jar (version may vary)

Please memo your guava.jar version (17.0 in the example), your build-tools version (21.0.3 in the example), and the path to the ADK root directory. We will need this information later.

Step 2. Install JDK 7

The SwiftHand implementation works with JDK version 6 and 7, and we recommend to use JDK version 7. Please check the path to the JDK root directory. We will need this information later.

Step 3. Install Maven.

Maven (http://maven.apache.org) is a project management and comprehension tool. Any recent version of Maven 3 will work.

Step 4. Clone the SwiftHand repository.

Clone the SwiftHand repository to your local disk. Following command will do the work.

git clone git@github.com:wtchoi/SwiftHand.git

Step 5. Editing the build script.

Open build.sh.skeleton, a skeleton of the main build script. You will find out following four commented lines.

#export ADK_ROOT=""
#export JAVA_HOME=""
#export GUAVA_VERSION=""
#export DX_VERSION=""

Assign appropriate values to the variables and uncomment them. Once the editing is done, type the following commands:

cp build.sh.skeleton build.sh
chmod 700 build.sh

Step 6. Build.

Now, it is the time to do the actual build.

./build.sh

If the build process is succesful, you will see two new files in the directory: inst.sh and test.sh. Voila!

Using the Back-End

Step 1. Create an Emulator

Do following steps to create Android Vritual Device. The steps will create an emulator image.

1. Luanch SDK Manager (<ADK_ROOT>/tools/android)
2. Select 'Tools' -> 'Manage AVDs'
3. Push 'New' button to create emulator. To reproduce the experimental result in the paper, We recommand to use 'Nexus S' as a device, 'API Level 16' as a target, 'ARM' as a CPU/API. This step creates Android Virtual Device (AVD) image.

You can find the official guideline about the emulator management from here: 'http://developer.android.com/tools/devices/managing-avds.html'.

Step 2. Start an Emulator

We recommand following command to setup necessary environment variable:

<ADK_ROOT>/tools/emulator -avd <AVD_NAME> -wipe-data -dns-server 127.0.0.1

-wipe-data options it to start an emulator from the factory-reset state -dns-server 127.0.0.1 option is a trick to disabling internet access. <AVD_NAME> refer the name of AVD created by step 2.

Step 3. Execute the Back-End

The tool can be executed using the test.sh script generaated by the build scipt. For example, to test dist/benchmark/mininote.modified.apk using SwiftHand with random seed 0 for 1 hour:

./test.sh dist/benchmark/mininote.modified.apk swift 3600 0 <OUTPUT_DIR> 

Please replace <OUTPUT_DIR> to the output directory you want. You can try any program in the benchmark directory by replacing 'mininote.modified.apk' to an appropriate value.

Execute the Front-End

Step 1. Instrument an Application

With a compiled front-end, you can instrument an apk file using the inst.sh script generated by the build script.

./inst.sh <TARGET.apk>

Please make sure to replace <TARGET.apk> with the path to the target apk file. You can find two example target files located in dist/unmofidied directory. If the instrumentation process success, the front-end generates several files including the following two files, in the direcory containing the original apk file.

• TARGET.modified.apk
• TARGET.modified.json

TARGET.modified.apk is an instrumented application file. TARGET.modified.json is a text file containing an information about the target application. To run a test, the back end requires both files to be in a singles directory.

Acknowledgements

• The front-end only works with ASMDEX library revision 1665 or an older version.
• The front-end only compiles with Scala compiler 2.9.1.
• The back-end only works correctly with an applicatio using a "real" screen resolution.

License

The SwiftHand tool follows BSD licnese. Please check the License.txt file for more details.