workload-automation/doc/source/revent.rst

.. _revent_files_creation:

revent
======

revent utility can be used to record and later play back a sequence of user
input events, such as key presses and touch screen taps. This is an alternative
to Android UI Automator for providing automation for workloads. ::


        usage:
                revent [record time file|replay file|info] [verbose]
                        record: stops after either return on stdin
                                or time (in seconds)
                                and stores in file
                        replay: replays eventlog from file
                        info:shows info about each event char device
                        any additional parameters make it verbose

Recording
---------

To record, transfer the revent binary to the device, then invoke ``revent
record``, giving it the time (in seconds) you want to record for, and the
file you want to record to (WA expects these files to have .revent
extension)::

        host$  adb push revent /data/local/revent
        host$  adb shell
        device#  cd /data/local
        device#  ./revent record 1000 my_recording.revent

The recording has now started and button presses, taps, etc you perform on the
device will go into the .revent file. The recording will stop after the
specified time period, and you can also stop it by hitting return in the adb
shell.

Replaying
---------

To replay a recorded file, run ``revent replay`` on the device, giving it the
file you want to replay::

        device#  ./revent replay my_recording.revent


Using revent With Workloads
---------------------------

Some workloads (pretty much all games) rely on recorded revents for their
execution. :class:`wlauto.common.GameWorkload`-derived workloads expect two
revent files -- one for performing the initial setup (navigating menus,
selecting game modes, etc), and one for the actual execution of the game.
Because revents are very device-specific\ [*]_, these two files would need to
be recorded for each device.

The files must be called ``<device name>.(setup|run).revent``, where
``<device name>`` is the name of your device (as defined by the ``name``
attribute of your device's class). WA will look for these files in two
places: ``<install dir>/wlauto/workloads/<workload name>/revent_files``
and ``~/.workload_automation/dependencies/<workload name>``. The first
location is primarily intended for revent files that come with WA (and if
you did a system-wide install, you'll need sudo to add files there), so it's
probably easier to use the second location for the files you record. Also,
if revent files for a workload exist in both locations, the files under
``~/.workload_automation/dependencies`` will be used in favor of those
installed with WA.

For example, if you wanted to run angrybirds workload on "Acme" device, you would
record the setup and run revent files using the method outlined in the section
above and then pull them for the devices into the following locations::

        ~/workload_automation/dependencies/angrybirds/Acme.setup.revent
        ~/workload_automation/dependencies/angrybirds/Acme.run.revent

(you may need to create the intermediate directories if they don't already
exist).

.. [*] It's not just about screen resolution -- the event codes may be different
       even if devices use the same screen.


revent vs. UiAutomator
----------------------

In general, Android UI Automator is the preferred way of automating user input
for workloads because, unlike revent, UI Automator does not depend on a
particular screen resolution, and so is more portable across different devices.
It also gives better control and can potentially be faster for ling UI
manipulations, as input events are scripted based on the available UI elements,
rather than generated by human input.

On the other hand, revent can be used to manipulate pretty much any workload,
where as UI Automator only works for Android UI elements (such as text boxes or
radio buttons), which makes the latter useless for things like games. Recording
revent sequence is also faster than writing automation code (on the other hand,
one would need maintain a different revent log for each screen resolution).