A customized version of Ella used in the paper An Empirical Study of Android Test Generation Tools in Industrial Cases. See here for the original version by Saswat Anand. Some implementations are still ad-hoc and improvements are welcomed.
Basically, I added support for MultiDex, fixed numerous bugs in the original implementation, and simplified some code. The usages are mostly the same with several exceptions stated below. Note that I only preserved the cumulative method coverage recorder in this version.
- Modify
ella.x.aapath
to point it to the directory containingapkanalyzer
(available in recent versions of Android SDK tools). - It's recommended to use ADB (instead of network) as the communication channel between Ella runtime and server. To do this, keep using
127.0.0.1
inella.server.ip
, and set upadb reverse tcp:23745 tcp:23745
on the computer before running the instrumented app. Note thatadb reverse
is not available on Android 4.4 butadb forward
and one relay app accepting two incoming connections (will be released later) can be used. - The generated keystore seemed to have some issues. Thus I (shamelessly) took the keystore from SwiftHand. BTW, thanks, Wontae :-)
The following steps are required only once before instrumenting the first app with multiple DEX files.
- Make sure the directory containing
dx
(available in Android build tools) is in$PATH
(or alternativelygen-ella-wrappers.py
). - Modify
MAX_COUNT
ingen-ella-wrappers.py
to be the maximum number of additional DEX files you want to instrument. The default value is 20. - Run
gen-ella-wrappers.py
to generate wrapper classes for additional DEX files, which would be used subsequently by instrumentation.
Ella is a tool to instrument Android APK's for various purposes. Out of the box, it instruments apps to record which methods gets executed. It can also record time-stamped trace of executed methods, values of arguments passed at call-sites, values of formal parameters of methods, etc.
Several tools exist that can instrument APK's to some degree. But they usually do not work very reliably because they translate Dalvik bytecodes to another form such as Java bytecode or internal representations of other tools, and this translation is quite challenging. Thus, Ella's approach is to instrument at the Dalvik bytecode level. It does so by builiding atop the DexLib2 library (a part of the Smali project).
- Unix-like operating system. Minor tweaks to scripts and build files may be needed to run ella on Windows.
- Android SDK
- Java SDK
- Apache Ant
- Rename
ella.settings.template
file toella.settings
, and if needed, set values of different environment variables of ella. - If the instrumented app will be executed on an emulator and the ella server will be run on the host machine of the emulator, then do nothing. Otherwise, set:
ella.use.emulator.host.loopback=false
If ella.use.emulator.host.loopback
is set to false
and the ella server will be running on a machine that is different from the machine on which the instrumentor is run, then set ella.server.ip
to the IP address of the machine on which the ella server will be run. For example,
ella.server.ip=1.2.3.4
Otherwise, do nothing.
Execute the following command inside ella's installation directory.
ant
Execute the following command.
ella.sh i <path-to-apk>
<path-to-apk>
is the Apk that you want to instrument. This command would produce the instrumented apk named instrumented.apk
inside a subdirectory inside <ella-home>/ella-out
directory, where <ella-home>
represents the installation directory of ella. The name of the subdirectory is derived from <path-to-apk>
.
Before executing any instrumented app, ella server must be up and running. To start the ella server, execute the following command.
ella.sh s
Whenever needed, the ella server can be shutdown by executing the following command
ella.sh k
- Install the
instrumented.apk
on the emulator or device. You may have to uninstall it first if the app is already installed. - Execute the instrumented app. The instrumented app will send coverage data periodically to the ella server.
- To end recording and uploading coverage data, either simply kill the app or execute the following command on computer connected to the device/emulator.
e
stands for "end" in end recording coverage data.
ella.sh e
The coverage data are stored inside a subdirectory of <ella-home>/ella-out
directory, where <ella-home>
represents the installation directory of ella. The name of the subdirectory is derived from <path-to-apk>
. Currently, coverage data are stored in files coverage.dat
and covids
. covids
contain the list of method signatures; index of a method is its identifier. coverage.dat
contains the list of method identifiers that were executed.