Saleem Rashid edited this page Dec 19, 2016 · 80 revisions


AndroidViewClient is 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 monkeyrunner, jython or any interpreter other than python.

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.


Using easy_install

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 python-setuptools

$ sudo apt-get install python-setuptools

Alternatively, if you install packages via pip you can use it to install setuptools too. AndroidViewClient requires Python 2 and is not compatible with Python 3.

$ pip install -U setuptools  # not needed on Ubuntu


$ sudo easy_install --upgrade androidviewclient

Using PIP

When installing the tool for the first time run the following commands respectively:

  1. sudo apt-get install python-pip
  2. sudo apt-get install git
  3. 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.

Microsoft Windows

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

Alternative methods

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.


AndroidViewClient uses adb to connect to the devices so it should be available.

INFORMATION: Problems has been reported with some adb installed 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.

Use the --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

$ 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

Select the correct implementation

Depending on various conditions some implementation may be the correct for your case.

View full size image

See also:


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.py has evolved from this simple script to a full fledged tool that has been moved to the tools directory.

See the dump for details.

We call this script dump.py

#! /usr/bin/env python
Copyright (C) 2012  Diego Torres Milano
Created on Feb 3, 2012

@author: diego

import sys
import os

    sys.path.insert(0, os.path.join(os.environ['ANDROID_VIEW_CLIENT_HOME'], 'src'))

from com.dtmilano.android.viewclient import ViewClient



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.