Android Runner

Android Runner (AR) is a tool for automatically executing measurement-based experiments on native and web apps running on Android devices.

The following scientific publication gives an overview about the main components, plugins, and configurations of Android Runner (as of 2020): A-Mobile 2020 publication

A complete tutorial on how to use Android Runner is available in the following YouTube playlist: Android Runner Tutorials.

As visualized below, Android Runner consists of the following components:

• Experiment orchestrator: Is in charge of executing the whole experiment according to the experiment configuration provided by the user.
• Devices manager: Is responsible for providing a layer of abstraction on the low-level operations involving the Android devices.
• Progress manager: Keeps track of the execution of each run of the experiment.
• Plugin handler: Provides a set of facilities for managing the profilers and an extension point that third-party developers can use for integrating their own measurement tools into Android Runner.

Table of Contents

• Android Runner
  • Table of Contents
  • How to Cite Android Runner
  • Setup
  • Setup with docker
    • Build the container
    • Configure your experimentation
    • Run the container
      • Linux
      • Windows
  • Quick Start

How to Cite Android Runner

If Android Runner is helping your research, consider to cite it as follows, thanks!

@inproceedings{A_Mobile_2020,
  title={{A Framework for the Automatic Execution of Measurement-based Experiments on Android Devices}},
  author={Ivano Malavolta and Eoin Martino Grua and Cheng-Yu Lam and Randy de Vries and Franky Tan and Eric Zielinski and Michael Peters and Luuk Kaandorp},
  booktitle={35th IEEE/ACM International Conference on Automated Software Engineering Workshops (ASEW '20)},
  year={2020},
  url= {https://github.com/S2-group/android-runner/blob/master/documentation/A_Mobile_2020.pdf},
  organization={ACM}
}

Setup

Instructions can be found here. Instructions for specific plugins are included in the plugins' READMEs.

Setup with docker

Build the container

docker compose build

Configure your experimentation

Create a folder with all files to define your experimentation (See myexperiment or examples). Change your docker-compose.yml to mount your experiment in a folder in the container:

volumes:
      - ./myexperiment:/exp

Change your docker-compose.yml and define in the command the path to the config.json file you want to execute (be careful to use the name of the internal folder defined before):

command: /exp/config_web.json

Run the container

Linux

docker compose up

Windows

Run adb server on your windows:

adb start-server

In your config.json file, change the adb_path to use your adb server launched on windows (See example here):

{
    "adb_path": "adb -H host.docker.internal ",
...
}

Run the container:

docker compose up

Quick Start

To run an experiment, run:

python3 android-runner path_to_your_config.json

Example configuration files can be found in the subdirectories of the examples directory.

More information about the specifics of Android Runner and use cases can be found in the Wiki tab.