Tutorials

Build from AOSP
Using VALERA on emulator
Using VALERA on real Android devices
Record and replay Android app

Build from AOSP

VALERA uses the "android-4.3_r1" version of the Android source code. You need to download Android source code first and test your build environment works properly.

% mkdir -p ~/valera/valera-4.3_r1
% cd ~/valera/valera-4.3_r1
% repo init -u https://android.googlesource.com/platform/manifest -b android-4.3_r1
% repo sync
... wait

After the source code is downloaded, you need to apply the patch for the AOSP source code. Copy and paste the following content into .repo/local_manifests/local_manifest.xml

Next, pull the source code with version "valera-4.3_r1".

% cd ~/valera/valera-4.3_r1 % repo sync % repo forall dalvik libcore frameworks/base external/apache-http hardware/ril -c 'git checkout -b valera-4.3_r1 && git pull'

Finally, build the AOSP project:

% . build/envsetup.sh % lunch % make -j4

Using VALERA on emulator

You can run the following command to start the emulator. The emulator version images are test on 14.04 Ubuntu Linux (64 bit).

% emulator

The emulator fits most of the usage scenarios. In case the app uses hardware sensors (e.g. GPS, camera, audio etc), the app should run on real phone. You need to follow the instructions below to flash VALERA into Galaxy Nexus phone.

Using VALERA on real Android devices

We test VALERA on Galaxy Nexus. The Galaxy Nexus requires proprietary binaries not included in the AOSP release. Download the drivers and extract the files into your source directory.

% cd ~/valera/valera-4.3_r1
% wget https://dl.google.com/dl/android/aosp/broadcom-maguro-jwr66y-5fa7715b.tgz
% tar -zxvf broadcom-maguro-jwr66y-5fa7715b.tgz
% ./extract-broadcom-maguro.sh # (view the license and then type "I ACCEPT")
...
% wget https://dl.google.com/dl/android/aosp/imgtec-maguro-jwr66y-b0a4a1ef.tgz
% tar -zxvf imgtec-maguro-jwr66y-b0a4a1ef.tgz
% ./extract-imgtec-maguro.sh # (view the license and then type "I ACCEPT")
...
% wget https://dl.google.com/dl/android/aosp/invensense-maguro-jwr66y-e0d2e531.tgz
% tar -zxvf invensense-maguro-jwr66y-e0d2e531.tgz
% ./extract-invensense-maguro.sh # (view the license and then type "I ACCEPT")
...
% wget https://dl.google.com/dl/android/aosp/nxp-maguro-jwr66y-d8ac2804.tgz
% tar -zxvf nxp-maguro-jwr66y-d8ac2804.tgz
% ./extract-nxp-maguro.sh # (view the license and then type "I ACCEPT")
...
% wget https://dl.google.com/dl/android/aosp/samsung-maguro-jwr66y-fb8f93b6.tgz
% tar -zxvf samsung-maguro-jwr66y-fb8f93b6.tgz
% ./extract-samsung-maguro.sh # (view the license and then type "I ACCEPT")
...
% wget https://dl.google.com/dl/android/aosp/widevine-maguro-jwr66y-c49927ce.tgz
% tar -zxvf widevine-maguro-jwr66y-c49927ce.tgz
% ./extract-widevine-maguro.sh # (view the license and then type "I ACCEPT")

Next, we can build VALERA.

% . build/envsetup.sh
% lunch full_maguro-userdebug
% make -j8

Finally, flash the images to the device

% cd out/target/product/maguro
% fastboot flash boot boot.img
% fastboot flash system system.img
% fastboot flash userdata userdata.img

Record and replay Android app

In this tutorial, we will use Nori app as an example. The apk can be downloaded from:

Nori.apk

Step 0: Initialization

First of all, give adb the root priviliage since VALERA will put some config files into the app's private folder. Then you should install the Nori app. Please run the following two commands:

% adb root
% adb install nori.apk

Step 1: Configuration

The configuration file should contain the package name and main entry activity of the app so that VALERA script can start the app automatically. In addition, you can select to do tracing and record network connection. The tracing option enables the dalvik vm to log every method entry and exit as well as branch instructions. Thus the overhead is very high if you enable it for whole program tracing. We suggest to trace just for a few looper actions that you are interested in. Here is the example configuration file for Nori app:

PKG=pe.moe.nori
MAIN=pe.moe.nori.SearchActivity
TRACING=0
NETWORK_REPLAY=1
APP_HOME_DIR=/data/data/$PKG

Step 2: Recording

VALERA client side source code is in the following github page. Make sure TraceInflater and ValeraTrace sub-projects are correctly built.

https://github.com/frankhuhu/valera

To start recording app execution, use the command below.

% cd ValeraClient
% ./scripts/run.sh --config=config.txt --cmd=record

The script will automatically start the app. You just need to use the app as normal. Tap CTRL + C to stop recording when you finish running the app. The critical execution information, such as touch events, sensor events, IO data and schedules, will be logged properly.

Step 3: Post processing

The result folder contains all the logged data. inputevent.bin includes all the touch screen events. io.bin record all the HTTP/HTTPS connection data if the network log option is speified in the configuration file. record.trace & replay.trace captures some important schedule information such as thread creation, internal message posting etc.

If you want fully deterministic schedule replay, i.e. all the actions executed on looper thread is the same during record and replay, you can run the following command to extract the schedule:

% java -jar ./bin/ValeraTool.jar generate_schedule record.trace > schedule.txt

Note that VALERA only ensure the deterministic replay of the specific app. Some events from system level services such as AMS, WMS maybe missing during replay. Although VALERA runtime sets timeout during replay execution, it is suggested to filter out these events in the schedule file thus not hurt the replay performance. Example of these events include TRIM_MEMORY event from AMS, animation related events from WMS, and onProgressUpdate in AsyncTask.

Step 4: Replaying

Replay is simple. You just need to specify config file and schedule file. Then run this command:

% ./scripts/run.sh --config=config.txt --schedule=schedule.txt --cmd=replay

VALERA runtime will load the necessary data to the device and auto start replaying the app.