Initial commit of open source Workload Automation.

doc/source/revent.rst

@@ -0,0 +1,97 @@
+.. _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).