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 shipped with a predefined set of run configurations for Intellij IDEA (tested with 2017.2 and 2017.3) . They exist to assist you to get started with running DroidMate from IDE while developing it. They include commands to inline and explore apps. Set up Intellij, if necessary.

If you want to use DroidMate API from your Java program, without editing DroidMate sources, please see repo/RUNNING.md.

Application run configs

The Explore apks randomSeed=0 reset=30 actionsLimit=50 run configuration show you example ways of running DroidMate. You can ignore run configs in Reporting folder. They are either deprecated or experimental. In both cases they are not supported.

Gradle run configs

Use clean to reset everything, build install to build everything and install to local maven repository, and testDevice to run tests requiring device.

JUnit run configs

FastRegressionTestSuite is the main test suite of DroidMate, it can be executed by the IDE or run by the :projects:command:test Gradle task. Explores monitored apk on a real device api23 is being run by :projects:command:testDevice Gradle task.

The root of all test suites is org.droidmate.test_suites.AllTestSuites.

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