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
- 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
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.
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)
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.
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:
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
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.
- 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.
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:
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.