mirror of
https://github.com/ARM-software/workload-automation.git
synced 2025-01-19 20:34:30 +00:00
bc87eacde2
Update the documentation and build system for producing documentation for WA3 with support for automatic building on readthedocs. Note: This is currently a WIP.
156 lines
6.9 KiB
ReStructuredText
156 lines
6.9 KiB
ReStructuredText
.. _revent_files_creation:
|
|
|
|
Revent
|
|
======
|
|
|
|
Overview and Usage
|
|
------------------
|
|
|
|
The 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.
|
|
|
|
Using revent with workloads
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Some workloads (pretty much all games) rely on recorded revents for their
|
|
execution. ReventWorkloads will require between 1 and 4 revent files be be ran.
|
|
There is one mandatory recording ``run`` for performing the actual execution of
|
|
the workload and the remaining are optional. ``setup`` can be used to perform
|
|
the initial setup (navigating menus, selecting game modes, etc).
|
|
``extract_results`` can be used to perform any actions after the main stage of
|
|
the workload for example to navigate a results or summary screen of the app. And
|
|
finally ``teardown`` can be used to perform any final actions for example
|
|
exiting the app.
|
|
|
|
Because revents are very device-specific\ [*]_, these files would need to
|
|
be recorded for each device.
|
|
|
|
The files must be called ``<device name>.(setup|run|extract_results|teardown).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>/wa/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 favour of those
|
|
installed with WA.
|
|
|
|
.. [*] It's not just about screen resolution -- the event codes may be different
|
|
even if devices use the same screen.
|
|
|
|
.. _revent-recording:
|
|
|
|
Recording
|
|
^^^^^^^^^
|
|
|
|
WA features a ``record`` command that will automatically deploy and start revent
|
|
on the target device.
|
|
|
|
If you want to simply record a single recording on the device then the following
|
|
command can be used which will save the recording in the current directory::
|
|
|
|
wa record
|
|
|
|
There is one mandatory stage called 'run' and 3 optional stages: 'setup',
|
|
'extract_results' and 'teardown' which are used for playback of a workload.
|
|
The different stages are distinguished by the suffix in the recording file path.
|
|
In order to facilitate in creating these recordings you can specify ``--setup``,
|
|
``--extract-results``, ``--teardown`` or ``--all`` to indicate which stages you
|
|
would like to create recordings for and the appropriate file name will be generated.
|
|
|
|
You can also directly specify a workload to create recordings for and WA will
|
|
walk you through the relevant steps. For example if we waned to create
|
|
recordings for the Anybirds Rio workload we can specify the ``workload`` flag
|
|
with ``-w``. And in this case WA can be used to automatically deploy and launch
|
|
the workload and record ``setup`` (``-s``) , ``run`` (``-r``) and ``teardown``
|
|
(``-t``) stages for the workload. In order to do this we would use the following
|
|
command with an example output shown below::
|
|
|
|
wa record -srt -w angrybirds_rio
|
|
|
|
::
|
|
|
|
INFO Setting up target
|
|
INFO Deploying angrybirds_rio
|
|
INFO Press Enter when you are ready to record SETUP...
|
|
[Pressed Enter]
|
|
INFO Press Enter when you have finished recording SETUP...
|
|
[Pressed Enter]
|
|
INFO Pulling '<device_model>setup.revent' from device
|
|
INFO Press Enter when you are ready to record RUN...
|
|
[Pressed Enter]
|
|
INFO Press Enter when you have finished recording RUN...
|
|
[Pressed Enter]
|
|
INFO Pulling '<device_model>.run.revent' from device
|
|
INFO Press Enter when you are ready to record TEARDOWN...
|
|
[Pressed Enter]
|
|
INFO Press Enter when you have finished recording TEARDOWN...
|
|
[Pressed Enter]
|
|
INFO Pulling '<device_model>.teardown.revent' from device
|
|
INFO Tearing down angrybirds_rio
|
|
INFO Recording(s) are available at: '$WA_USER_DIRECTORY/dependencies/angrybirds_rio/revent_files'
|
|
|
|
Once you have made your desired recordings, you can either manually playback
|
|
individual recordings using the :ref:`reply <replay-command>` command or, with
|
|
the recordings in the appropriate dependencies location, simply run the workload
|
|
using the :ref:`run <run-command>` command and then all the available recordings will be
|
|
played back automatically.
|
|
|
|
For more information on available arguments please see the :ref:`Record <record_command>`
|
|
command.
|
|
|
|
.. note:: By default revent recordings are not portable across devices and
|
|
therefore will require recording for each new device you wish to use the
|
|
workload on. Alternatively a "gamepad" recording mode is also supported.
|
|
This mode requires a gamepad to be connected to the device when recording
|
|
but the recordings produced in this mode should be portable across devices.
|
|
|
|
.. _revent_replaying:
|
|
|
|
Replaying
|
|
^^^^^^^^^
|
|
|
|
If you want to replay a single recorded file, you can use ``wa replay``
|
|
providing it with the file you want to replay. An example of the command output
|
|
is shown below::
|
|
|
|
wa replay my_recording.revent
|
|
INFO Setting up target
|
|
INFO Pushing file to target
|
|
INFO Starting replay
|
|
INFO Finished replay
|
|
|
|
If you are using a device that supports android you can optionally specify a
|
|
package name to launch before replaying the recording.
|
|
|
|
If you have recorded the required files for your workload and have placed the in
|
|
the appropriate location (or specified the workload during recording) then you
|
|
can simply run the relevant workload and your recordings will be replayed at the
|
|
appropriate times automatically.
|
|
|
|
For more information run please read :ref:`replay-command`
|
|
|
|
Revent vs UiAutomator
|
|
----------------------
|
|
|
|
In general, Android UI Automator is the preferred way of automating user input
|
|
for Android 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 doing 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).
|
|
|
|
.. note:: For ChromeOS targets, UI Automator can only be used with android
|
|
applications and not the ChomeOS host applications themselves.
|
|
|
|
|