💁‍♀️ Participate in Discussions where you can see Announcements, Polls, Q&A, etc.

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.

🚀 Check Examples and Screencasts and videos page to see it in action.

It is usually convenient to use a virtual environment to easily switch between multiple versions of Python if the one installed in your system or the one required by other tools is different.

AndroidViewClient supports Python 3 and Python 2.7.x and a virtual environment would isolate your system from this dependency.

i️ : This is the preferred installation method

For example, install pyenv as indicated by its documentation.

$ mkdir avc-workdir
$ cd avc-workdir
$ pyenv install 3.x
$ pyenv local 3.x
$ pip3 install androidviewclient --upgrade

and if everything went well

$ culebra --version
culebra 20.0.0b4

That's it! You have a working installation of AndroidViewClient that you can upgrade it later using pip too. 🙌

$ mkdir avc-workdir
$ cd avc-workdir
$ pyenv install 2.7.15
$ pyenv local 2.7.15
$ pip install androidviewclient

and if everything went well

$ culebra --version
culebra 15.5.1

That's it! You have a working installation of AndroidViewClient that you can upgrade using pip. 🙌

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.

This method installs 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

Then

$ sudo easy_install --upgrade androidviewclient

Run

pip install androidviewclient

Latest versions use matplotlib as a dependency and its installation may require you have python development environment installed. So if you are receiving an error like this

 error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
 
 ----------------------------------------
 Failed building wheel for subprocess32
 Running setup.py clean for subprocess32
Failed to build subprocess32
Installing collected packages: subprocess32, pytz, six, python-dateutil, cycler, numpy, matplotlib

you should install python-dev

sudo apt install python-dev

and retry the pip command.

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.

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.

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
• culebra

$ dump --help

Check culebra wiki page or run

$ culebra --help

to see the available command line options.

Culebra GUI also provides an easy way of getting started.

Before you begin, you can verify that your environment has been correctly setup after following the steps mentioned in Installation.

💁‍♀️ If you installed via pip you can skip this step as everything will be fine already

There is a simple script in examples that would help you do this verification.

$ cd /path/to/androidviewclient
$ cd examples
$ python3 check-import.py

if everything is fine, you will receive

OK

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

$ 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.

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

See also:

• Secure mode
• System ViewServer
• LocalViewServer
• CulebraTester2-public

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 Phone, Messages, Play Store, Chrome, etc.

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 simple-dump.py

#! /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:

$ ./simple-dump.py [serialno]

produces:

android.widget.FrameLayout 
 com.android.launcher3.Workspace com.google.android.apps.nexuslauncher:id/workspace 
 android.widget.FrameLayout com.google.android.apps.nexuslauncher:id/search_container_workspace 
 android.widget.TextView com.google.android.apps.nexuslauncher:id/clock Wednesday, May 29
 android.widget.LinearLayout com.google.android.apps.nexuslauncher:id/title_weather_content 
 android.widget.TextView com.google.android.apps.nexuslauncher:id/title_weather_text 57°F
 android.widget.ImageView com.google.android.apps.nexuslauncher:id/all_apps_handle 
 android.view.ViewGroup com.google.android.apps.nexuslauncher:id/layout 
 android.widget.TextView Phone
 android.widget.TextView Messages
 android.widget.TextView Play Store
 android.widget.TextView Chrome
 android.widget.TextView Culebra Tester
 android.widget.FrameLayout com.google.android.apps.nexuslauncher:id/search_container_hotseat 

To complete our simple example let's say we want to touch Chrome shortcut to open the application. We can name this script simple-interaction.py

#! /usr/bin/env python
# -*- coding: utf-8 -*-
"""
Copyright (C) 2019 Diego Torres Milano
Created on Jun 7, 2019

@author: diego
"""
from com.dtmilano.android.viewclient import ViewClient
vc = ViewClient(*ViewClient.connectToDeviceOrExit())
vc.dump(window=-1)
vc.findViewWithContentDescriptionOrRaise(u'''Chrome''').touch()

Running the previous script as:

$ ./simple-interaction.py [serialno]

produces:

Copyright (C) 2012-2023 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

 http://www.apache.org/licenses/LICENSE-2.0

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.