Running

!!! Please note: Ensure you have built DroidMate according to the build instructions before proceeding.

Compiling and executing

DroidMate can be compiled into an executable Jar file to be externally used.

It can also be imported as a dependency into projects for extension or executed from the IDE.

Compiling and executing as an external Jar

To run DroidMate you can create an executable jar with all dependencies using:

cd repo/dev/droidmate

./gradlew :projects:shadowJar

The executable jar will be generated under repo/dev/droidmate/projects/command/build/libs with the name shadow-*-all.jar.

This jar can be executed using java -jar shadow-*-all.jar, plus command line arguments.

If not command line arguments are provided, DroidMate will read command line arguments from a local args.txt file if available

Example

java -jar droidmate.jar -apksDir=/home/test/apks -randomSeed=0 -resetEvery=100 -actionsLimit=500

Importing as dependency into your project

See the dedicated importing DroidMate as a dependency page for more information.

Running from the IDE

!!! Please note: this method of running DroidMate is not recommended. Instead, use the API from your Java app as described above.

DroidMate is currently shipped with a basic set of profiles for Intellij IDEA (tested with 2017.2 and 2017.3) which can be straightly executed. They include commands to inline apps and explore.

To access DroidMate with the Intellij profiles, open the repo/dev/droidmate directory with Intellij (File -> New -> Project from Existing Sources) and refresh the Gradle projects.

Required input

DroidMate reads as input all .apk files located in the directory specified by the -apksDir parameter

Preparing apps for DroidMate

While DroidMate can explore normal apps, it is intended to run on inlined ones. When run on inlined apks, DroidMate is able to monitor which Android APIs are being acessed. For normal APKs it can only measure the exploration coverage.

To inline apps run DroidMate with -inline argument. The original app files (apks) will be retained and new inlines apk files will be created.

Inlined apks can be distinguished by an -inlined suffix in their name.

Example (assuming executable Jar)

java -jar droidmate.jar -inline -apksDir=/home/test/apks

Obtaining apks

You can obtain .apk files of the apps in following ways:

• Use a dedicated app for that. See androidpit.com/how-to-download-apk-file-from-google-play
• Copy the artificial apk fixtures coming from DroidMate, that can be found in repo/dev/droidmate/projects/core/src/test/resources/fixtures/apks after DroidMate was successfully built. Their sources are available in the repo/dev/apk_fixtures_src project.
• Copy an apk downloaded from Google Play Store located in repo/dev/droidmate_usage_examples/apks/inlined.
• Download Samples for SDK using Android SDK Manager and build them.
• Install an app from Google Play Store to an Android device and then pull the app from the device using adb from Android SDK. For example, the currency converter has id=com.frank_weber.forex2 in its URL, denoting its package name. After you install it on the device, you can pull it in the following way:

$ adb shell pm path com.frank_weber.forex2
package:/data/app/com.frank_weber.forex2-1.apk
$ adb pull /data/app/com.frank_weber.forex2-1.apk
3674 KB/s (2361399 bytes in 0.627s)
// The file is now in the current dir