Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



What it is

EventRecorder is an infrastructure that provides automated web application testing on Android-based devices. It consists of a device tool and a host machine recording client. This client application receives a playback script from the device tool at the end of the recording. The script is a self-contained program that is able to contact the device tool and send all the recorded events in order to reproduce the session as closely as possible.

Currently it is possible to:

  • Load URLs
  • Execute JavaScript and log evaluations via console.log()
  • Record and play back touch and physical keyboard events
  • Capture the device screen leaving status and title bars out
  • Fill text in form fields via the host machine

Supported platforms

Any platform that is simultaneously supported by the Android Debug Bridge (adb), and Python. Currently, it is targeted at devices running Android and it has been tested with Froyo, Gingerbread and Honeycomb. If you successfully use it on Eclair, please let us know. You can either use a real device or an emulator.

Tested Devices

Please help us grow this list by reporting your working devices:

  • Android emulator
  • Droid Incredible
  • Evo 4G
  • Nexus One
  • Nexus S
  • Galaxy Tab (see also Known Issues)
  • Xoom


The Android SDK is necessary to run the application. In particular, the adb tool is required to be in your $PATH. To run the shell recorder, a Python (v2.6+) environment is required.

How to record

Run the recorder.py file with the test name as an argument, i.e.

python recorder.py <test>

The recorder script will then automatically install an android tool on your device. If you wish to bypass this step, you can pass the "-n" option. Next, a prompt will be displayed where you can use a few commands. These are as follows:

  • s or screen: Capture screen.
  • t or text: Input text.

Any commands not using any of these prefixes will be either interpreted as an URL load (if it starts with http:// or www) or as JavaScript input, which will be evaluated by the browser. Your first command should always be an URL.

JavaScript values can be logged using the console.log() method.

All touch events and hardware keyboard events will also be recorded in this stage.

When recording is complete simply press ENTER at the prompt. This will cause the recording to stop and a python script named testname.py should be available in your current directory when the recorder exits. Note that an initial run of the generated playback script is necessary to generate the baseline result.

How to play

Simply execute the script generated by the recorder:

python <test.py>

The recorded events will then be played back, and all screen captures and the console log will be available in the current directory. They can then be compared against a baseline if wished.

Detecting Visual Regressions

For convenience, we provide the simple imagediff.py tool. It expects two input screen captures and an output file name. The generated image will represent a grayscale difference between the input images. This tool can be easily incorporated in regression suites to generate fault reports. If the two input images are identical, no output image is generated. The format of the output image will be determined by the file name extension.

Note: if you need a more complete solution, you might want to consider using the ImageMagick compare tool.

Detecting Non-Visual Regressions

The other existing mechanism consists of logging JavaScript code results. The console.log output file resulting from a playback contains everything that was logged during the execution of the test. In order to detect regressions, one simply needs to perform a diff between the log present in the baseline and the log that resulted from the latest playback.

How it works

When the application is started, it automatically installs an Android package (APK) called EventRecorder on your selected device. If a package already exists, it is uninstalled first.

The android package is responsible for recording all events the user initiates and write this to a file that is later fetched from the phone. It is also responsible for replaying events from an existing file when told to do so.

The application on the host is responsible for notifying the android side when the user initiates certain events (loading URLs, capturing screenshots etc) and also has to fetch the event file when recording is complete. When replaying, it also needs to send the event file to the device for execution.

Known Issues

  • Events recorded through soft keyboard typing won't be reproduced in the playback.
  • The Samsung Galaxy Tab will always send the framebuffer in landscape mode. This means the user needs to test applications in landscape mode on this device.
  • Some event sequences might not be exactly reproduced on playback compared to their results during recording. This is because the timing between the events is not 100% accurate in relation to the originally recorded. In particular, fling scroll might lead to different end offsets.

Customizing the Android Tool

If you wish to make changes to the Android tool for your own needs you'll need, in addition to the above mentioned requirements, an Ant environment. Make sure the android application is in your $PATH. Once ready, go to the android folder and run the following on your shell:

android update project -p .

Please note that the above step only needs to be executed once per workstation. It will generate a file called local.properties.

Next, type:

ant debug

A debug package named bin/EventRecorder-debug.apk will be generated. If you wish to sign your application, follow these steps.

Finally, switch to the shell directory and run:

python inline-apk.py

This will embed the APK in the recorder, so that it doesn't need to be installed manually on all devices. The recorder is now ready to be used.