Clone this wiki locally
an extension to monkeyrunner a 100% pure python library and tools that simplifies test script creation and android test automation, providing higher level operations and the ability of obtaining the tree of Views present at any given moment on the device or emulator screen and perform operations on it.
As it's 100% pure python it doesn't require
jython or any interpreter other than
Interaction with Views is completely device independent and you don't have to take into account different screen sizes, resolutions or densities as the operations can be specified by View attributes instead as by (x,y) coordinates. Attributes such as content description, text, id or autogenerated unique id can be used to select a View.
AndroidViewClient is commonly used to create tests scripts but can be in stand-alone scripts as well. Test script creation can be even further simplified and automated by using Culebra. Culebra is fully described in its own page.
There are a lot of ways of installing or upgrading AndroidViewClient but this is perhaps the easiest one, no wonder why the command name just mentions it.
INFORMATION: This is the preferred installation method
This method install the latest release version of AndroidViewClient.
If you don't have
easy_install installed install the package
$ sudo apt-get install python-setuptools
Alternatively, if you install packages via
pip you can use it to install
AndroidViewClient requires Python 2 and is not compatible with Python 3.
$ pip install -U setuptools # not needed on Ubuntu
$ sudo easy_install --upgrade androidviewclient
When installing the tool for the first time run the following commands respectively:
- sudo apt-get install python-pip
- sudo apt-get install git
- sudo pip install git+https://github.com/dtmilano/AndroidViewClient.git
Please note that, using pip method will install the development version on your machine. This cutting edge version includes the most up-to-date patches and it's usually not as stable as the release.
If you are using Microsoft Windows you may find this discussion about
setuptools helpful and interesting: how to use python's easy install on windows
However, as a quick hint:
You can refer to the following link: (https://pypi.python.org/pypi/setuptools) and follow the provided instructions under "Windows (simplified)".
Darpan Dodiya has written an excellent setup tutorial for Windows:
How To Install, Setup And Use AndroidViewClient On Windows
Strictly speaking, AndroidViewClient does not require installation to be used. Downloading the required components is all you need.
Download the zip or tag.gz from releases, expand it, set the environment
$ export ANDROID_VIEW_CLIENT_HOME=/path/to/androidviewclient/
and your ready to go.
adb to connect to the devices so it should be available.
INFORMATION: Problems has been reported with some
adbinstalled from unofficial packages or repositories, so to be sure install it from https://developer.android.com/studio/index.html
This distribution includes the following AndroidViewClient tools:
$ dump --help
$ culebra --help
Culebra GUI also provides an easy way of getting started.
Verifying environment setup
Before you begin, you can verify that your environment has been correctly setup after following the steps mentioned in Installation.
There is a simple script in examples that would help you do this verification.
$ cd /path/to/androidviewclient $ cd examples $ python check-import.py
if everything is fine, you will receive
however, if something went wrong you will receive the corresponding exception.
--debug command line option to help you find the problem.
You may receive an exception like
Traceback (most recent call last): File "check-import.py", line 35, in <module> import com ImportError: No module named com
this is due to the fact that
python was not able to find the requested modules. To solve the problem you must set
ANDROID_VIEW_CLIENT_HOME environment variable pointing to the directory containing the modules.
$ export ANDROID_VIEW_CLIENT_HOME=/path/to/androidviewclient/
Also, as a quick check of having the right directory set in
ANDROID_VIEW_CLIENT_HOME you can do
$ cd $ANDROID_VIEW_CLIENT_HOME $ ls -l
and the directories and files in the folder should be similar to
total 80 -rw-r--r-- 1 diego staff 11358 21 Jan 22:30 LICENSE -rw-r--r-- 1 diego staff 493 21 Jan 22:30 README.md -rwxr-xr-x 1 diego staff 1299 21 Jan 22:30 avc-version -rw-r--r-- 1 diego staff 2181 21 Jan 22:30 build.xml drwxr-xr-x 59 diego staff 2006 21 Jan 22:30 doc drwxr-xr-x 9 diego staff 306 21 Jan 22:32 docs drwxr-xr-x 32 diego staff 1088 21 Jan 22:30 examples -rw-r--r-- 1 diego staff 206 21 Jan 22:30 project.properties -rw-r--r-- 1 diego staff 962 21 Jan 22:30 setup.py drwxr-xr-x 4 diego staff 136 21 Jan 22:30 src drwxr-xr-x 5 diego staff 170 21 Jan 22:30 tests drwxr-xr-x 4 diego staff 136 21 Jan 22:30 tools drwxr-xr-x 3 diego staff 102 21 Jan 22:30 uml -rw-r--r-- 1 diego staff 4416 21 Jan 22:30 viewclient.epydoc
Alternatively, you can set
PYTHONPATH environment variable instead of
ANDROID_VIEW_CLIENT_HOME. The only advantage in using this is that Eclipse and PyDev set this variable automatically from your project configuration. so if you are running scripts from the IDE there are no extra steps.
However, if you are running scripts from the command line you can still use this variable.
$ export PYTHONPATH=/path/to/androidviewclient
See API Documentation.
Select the correct implementation
Depending on various conditions some implementation may be the correct for your case.
View full size image
This is just an illustrative quick example of AndoidViewClient capabilities. The complete set of examples can be found here.
The device shows several shortcuts, like Email, Camera, Settings, Gallery and the Clock widget.
dump.pyhas evolved from this simple script to a full fledged tool that has been moved to the
See the dump for details.
We call this script
#! /usr/bin/env python ''' Copyright (C) 2012 Diego Torres Milano Created on Feb 3, 2012 @author: diego ''' import sys import os try: sys.path.insert(0, os.path.join(os.environ['ANDROID_VIEW_CLIENT_HOME'], 'src')) except: pass from com.dtmilano.android.viewclient import ViewClient ViewClient(*ViewClient.connectToDeviceOrExit()).traverse()
Running the previous script as:
$ ./dump.py [serialno]
... com.android.launcher2.CellLayout id/cell3 None com.android.launcher2.ShortcutAndWidgetContainer NO_ID None com.android.launcher2.BubbleTextView NO_ID Email com.android.launcher2.LauncherAppWidgetHostView NO_ID None android.widget.AnalogClock id/0x7f0f0014 None com.android.launcher2.BubbleTextView NO_ID Camera com.android.launcher2.BubbleTextView NO_ID Settings com.android.launcher2.BubbleTextView NO_ID Gallery com.android.launcher2.LauncherAppWidgetHostView NO_ID None android.widget.LinearLayout id/0x7f080167 None ...
Copyright (C) 2012-2015 Diego Torres Milano
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.