dump
dump is an extremely valuable tool if you are developing tests or scripts based on AndroidViewClient.
It was created as a simple example to demonstrate AndroidViewClient features but it became something more than that. Nevertheless, the intention is to keep it simple enough to be used as an example, so some extra features will be provided by different tools.
As its name indicates, the main function is to dump the content of the screen present on a device or emulator at any given time, but instead of providing it as a bitmap the result of running dump is the logical representation of the screen as a tree that can be also printed in textual form.
Some time ago, I wrote an article about visual image comparison in monkeyrunner, which is also a valid approach for some situations, but the ability to obtain the tree of Views provides a flexibility and effectiveness very difficult to parallel using graphical methods. One of the advantages is the device, screen, resolution and density independence that allows to run the same test on different devices.
Power came at the cost of simplicity and some command line options were added to permit dump be used in a variety of cases.
In order to run dump and any other AndroidViewClient script some environment variables should be provided containing the right values that allow the script to find other components.
PATH should contain the <android-sdk>/tools and <android-sdk>/platform-tools directories.
In the example above <android-sdk> represents the path to your Android SDK installation directory.
ANDROID_VIEW_CLIENT_HOME contains the path to the AndroidViewClient directory. This is the directory containing /src.
For example:
export ANDROID_VIEW_CLIENT_HOME=/home/user/workspace/AndroidViewClient
PYTHONPATH alternatively this variable can be used to locate modules. This is very useful when scripts are run from Eclipse using PyDev.
Points to the directory where Android SDK is installed.
This is used by AndroidViewClient to find some components (i.e. adb or adb.exe)
Optional variable to specify the serial number of the device or emulator to use.
Optional variable to specify the location of Android Studio installation. Use to obtain device art if -A or --device-art is used in conjunction with -f or --save-screenshot.
usage: dump [OPTION]... [serialno]
Options:
-H, --help prints this help
-V, --verbose verbose comments
-v, --version
-I, --ignore-secure-device ignore secure device
-E, --ignore-version-check ignores ADB version check
-F, --force-view-server-use force view server use (even if UiAutomator present)
-S, --do-not-start-view-server don't start ViewServer
-k, --do-not-ignore-uiautomator-killed don't ignore UiAutomator killed
-w, --window=WINDOW dump WINDOW content (default: -1, all windows)
-a, --all dump all information about Views
-i, --uniqueId dump View unique IDs
-x, --position dump View positions
-b, --bounds dump View bounds
-d, --content-description dump View content descriptions
-g, --tag dump View tags
-c, --center dump View centers
-f, --save-screenshot=FILE save screenshot to file
-W, --save-view-screenshots=DIR save View screenshots to files in directory
-D, --do-not-dump-views don't dump views, only useful if you specified -f or -W
-A, --device-art=MODEL device art to frame screenshot
-Z, --drop-shadow drop shadow for device art screenshot
-G, --glare screen glare over screenshot
Prints the help message and command line usage
Sets the verbose mode for ViewClient.
Ignores that a device is in secured as explained in secure mode.
This is useful when used in combination with LocalViewServer.
Ignores the ADB version check. In some cases, the ADB version running on the device does not match the version expected by AndroidViewClient and thus it exists with an error. This option allows you to bypass the test.
Forces the use of ViewServer even if the conditions to use UiAutomator are present. These conditions are depicted in Select the correct implementation. Basically, if the device run on API 16 or greater it can use UiAutomator, but if for some reason you want to still use the previous ViewServer method you can force it using this option.
ViewServer is much slower than UiAutomator, so it seems there are no reasons to use it when the latter is available. However there is one reason that may have some weight and this is the availability of the same View ID's used in the layouts.
Avoids starting the ViewServer even when it's not present on the device.
This is useful when used in combination with LocalViewServer.
Dumps the content of WINDOW.
Dumps unique ID's for all the Views. Sometimes Views have no unique ID's or even no ID's at all. This option generates a unique ID for each View and is printed in the dump.
Dumps the Views' positions on the screen as (top, left, width, height)
Dumps the content description for each View. NAF is printed for Views with no content description.
Dumps the View center coordinates as (x, y).
Specifies the serial number of the device to use if the device serial number cannot be determined automatically for some reason or if there are several devices connected.
This examples uses UiAutomator as the API 16 present in the emulator allows it.
Dumps center coordinates. Also sets verbose output.
$ dump -Vc
the dump obtained is
Connecting to a device with serialno=.* with a timeout of 60 secs...
Connected to device with serialno=.*
/home/user/workspace/AndroidViewClient/AndroidViewClient/src/com/dtmilano/android/viewclient.py:1076: UserWarning: Running on emulator but no serial number was specified then 'emulator-5554' is used
warnings.warn("Running on emulator but no serial number was specified then 'emulator-5554' is used")
android.widget.FrameLayout id/no_id/1 (400, 608)
android.widget.LinearLayout id/no_id/2 (400, 608)
android.widget.FrameLayout id/no_id/3 (400, 624)
android.widget.FrameLayout id/no_id/4 (400, 624)
android.widget.TabHost id/no_id/5 (400, 624)
android.widget.LinearLayout id/no_id/6 (400, 624)
android.widget.FrameLayout id/no_id/7 (400, 84)
android.widget.TabWidget id/no_id/8 (400, 84)
android.widget.TextView id/no_id/9 Apps (47, 84)
android.widget.TextView id/no_id/10 Widgets (155, 84)
android.widget.FrameLayout id/no_id/11 (400, 670)
android.view.View id/no_id/12 (400, 670)
android.view.View id/no_id/13 (400, 659)
android.view.View id/no_id/14 (400, 669)
android.widget.TextView id/no_id/15 --HW Drawing Performance (80, 229)
android.widget.TextView id/no_id/16 API Demos (240, 229)
android.widget.TextView id/no_id/17 Browser (400, 229)
android.widget.TextView id/no_id/18 Calculator (560, 229)
android.widget.TextView id/no_id/19 Calendar (720, 229)
android.widget.TextView id/no_id/20 Camera (80, 405)
android.widget.TextView id/no_id/21 Clock (240, 405)
android.widget.TextView id/no_id/22 Custom Locale (400, 405)
android.widget.TextView id/no_id/23 Dev Settings (560, 405)
android.widget.TextView id/no_id/24 Dev Tools (720, 405)
android.widget.TextView id/no_id/25 Downloads (80, 581)
android.widget.TextView id/no_id/26 Gallery (240, 581)
android.widget.TextView id/no_id/27 Gestures Builder (400, 581)
android.widget.TextView id/no_id/28 HW Drawing Performance (560, 581)
android.widget.TextView id/no_id/29 Messaging (720, 581)
android.widget.TextView id/no_id/30 Music (80, 757)
android.widget.TextView id/no_id/31 People (240, 757)
android.widget.TextView id/no_id/32 Phone (400, 757)
android.widget.TextView id/no_id/33 ResourcesActivity (560, 757)
android.widget.TextView id/no_id/34 SampleActivity (720, 757)
android.widget.TextView id/no_id/35 Search (80, 933)
android.widget.TextView id/no_id/36 Settings (240, 933)
android.widget.TextView id/no_id/37 Speech Recorder (400, 933)
android.widget.TextView id/no_id/38 Trashcan2Activity (560, 933)
android.widget.TextView id/no_id/39 Widget Preview (720, 933)
The lines at the beginning are the verbose description of the connection. Because no serialno was specified on the command line the regular expression .* that matches any device or emulator is used. In this case the only device present is the emulator-5554.
It's not possible to determine the serial number for the emulator and thus the warning tells us that emulator-5554 was assumed.
Following we have the View tree for the emulator in that precise moment. The class for each View is printed as well as the assigned IDs, the text if any and center's coordinates.
dump now supports the addition of device art, shadows and glare to the screenshots taken.
$ dump --save-screenshot /tmp/beautiful.png --do-not-dump-views --device-art=nexus_5 --drop-shadow --glare
allows you to obtain a beautiful screenshot like this one
Yet another interesting feature is the ability of detecting the phone art model and orientation automatically selecting the correct image as shown in the following example.
$ dump --save-screenshot /tmp/beautiful.png --do-not-dump-views --device-art=auto --drop-shadow --glare
