README

Build

Ape is developed in Java using Android SDK (including some private internal APIs) and can be compiled by a Java source compiler (e.g., javac or Eclipse JDT). To run ape in an Android device, we need to convert the Java bytecode class files generated by a Java source compiler into dalvik bytecode. We have built the SDK from AOSP and put it as a library (see dalvik_stub/ and framework/) in this project.

System requirements:

Java 7 and above
Ant
Dalvik compiler: dx
- Add $ANDROID_HOME/build-tools/<version>/ to your PATH

We started to develop Ape at the beginning of 2017 on an old Nexus 5 device, running Android Marshmallow. At that time, we used the old dalvik compiler dx. Developers may also want to use the new compiler d8 in the new SDK.

Ape can be built by simply running ant or ant assemble in the root folder of the project (where the build.xml is.). Developers can also clean the build by running ant clean first for a clean build.

Development

This project can be loaded into eclipse for development since it is a pure Java project. Remember to set the JDK compliance level to 1.7.

Right click the project monkey in Package Explorer.
Select properties.
Click Java Compiler and make sure the compliance level is 1.7.

Developers may need to update the compliance when Android updates its JDK compliance of Java.

Usage

See Ape's website.

Support New Android Versions

We tested the compatibility of Ape by using it to test Google Maps for 10 minutes in Android Marshmallow, Nougat, Oreo, Pie and Q emulators.

Ape is developed based on some release of Android Marshmallow (Sorry, I cannot remember the exact tag/commit). The easiest way to track the API changes of Ape is to check the change log of Monkey. Since Monkey is no longer actively developed, one can easily identify patches/commits of Monkey that are related to API changes.

Repository: https://android.googlesource.com/platform/development/
Monkey folder: https://android.googlesource.com/platform/development/+/refs/heads/master/cmds/monkey

We do not want to build the new Android SDK to get its Java bytecode version after each new Android has been released. We can use reflection APIs because these internal APIs are mostly invoked at the startup phase and should not be a performance bottleneck of Ape. More details can be found in source file src/com/android/commands/monkey/ApeAPIAdapter.java

In addition to private APIs used by Monkey, Ape also uses many new private APIs. We will use reflection to replace the direct usage of these APIs when these APIs have incompatible changes.

Basic Notes for Development

Ape is the prototype of our ICSE paper. One probably needs to read the paper first in order to understand the implementation of model refinement. If you use Ape for academic, please cite our ICSE 2019 paper:

@inproceedings{gu_practical_2019,
  author    = {Tianxiao Gu and Chengnian Sun and Xiaoxing Ma and Chun Cao and Chang Xu and Yuan Yao and Qirun Zhang and Jian Lu and Zhendong Su},
  title     = {Practical GUI Testing of Android Applications via Model Abstraction and Refinement},
  pages     = {to appear},
  year      = {2019},
  booktitle = {Proceedings of the 41st ACM/IEEE International Conference on Software Engineering (ICSE 2019)},
}

Here is a list that may help understand the implementation after reading the paper.

Abstraction function: See Naming.java
Attribute path: See Name.java
Reducer: See Namer.java
Model abstraction and refinement: See NamingFactory.java

Known Issue

OutOfMemoryError: Ape is running in the Android device. It has a limited amount of memory. The current implementation of Ape keeps every GUI tree in the memory so it may run out of memory in a couple of hours, depending on the actual configuration of the Android device and the app under testing.

Contact

Tianxiao Gu (tianxiao.gu@gmail.com)
Chengnian Sun (cnsun@uwaterloo.ca)
Zhendong Su (zhendong.su@inf.ethz.ch)

tianxiaogu / ape

readme