Friday, May 30, 2014

culebra: new unit tests facilities added

AndroidViewClient/culebra 7.0.2 was released recently. Besides a number of bug fixes it includes some new command line options mainly to help in the creation of unit tests.

$ culebra --help
usage: culebra [OPTION]... [serialno]

  -H, --help                       prints this help                             
  -V, --verbose                    verbose comments                             
  -v, --version
  -I, --ignore-secure-device
  -F, --force-view-server-use
  -S, --do-not-start-view-server
  -k, --do-not-ignore-uiautomator-killed don't ignore UiAutomator killed              
  -w, --window=WINDOW              use WINDOW content (default: -1, all windows)
  -i, --find-views-by-id=BOOL      whether to use findViewById() in script      
  -t, --find-views-with-text=BOOL  whether to use findViewWithText() in script  
  -d, --find-views-with-content-description=BOOL whether to use findViewWithContentDescription
  -r, --use-regexps                use regexps in matches                       
  -C, --verbose-comments
  -U, --unit-test-class            generates unit test class and script         
  -M, --unit-test-method=NAME      generates unit test method. Can be used with or without -U
  -j, --use-jar=BOOL               use jar and appropriate shebang to run script (deprecated)
  -D, --use-dictionary=BOOL        use a dictionary to store the Views found    
  -K, --dictionary-keys-from=VALUE dictionary keys from: id, text, content-description
  -R, --auto-regexps=LIST          auto regexps (i.e. clock), implies -r. help list options
  -a, --start-activity=COMPONENT   starts Activity before dump                  
  -o, --output=FILENAME            output filename                              
  -A, --interactive                interactive                                  
  -p, --append-to-sys-path         append environment variables values to sys.path
  -s, --save-screenshot=FILENAME   save screenshot to file                      

  -W, --save-view-screenshots=DIR  save View screenshots to files in directory  

These new options are:

-U, --unit-test-class this tells culebra to generate a script containing a unit test. If you just save the script and run it, the test containing in it will verify that the same Views are in the screen. This test case is a kind of logical screenshot where no bitmaps are involved.

-M, --unit-test-method=NAME this option has two different uses. If it's specified when --unit-test-case was also specified then the unit test case generated will have a test method called NAME. It's advisable to name the method testSomething, where Something should describe what you are testing. On the other hand, if --unit-test-case is not specified then only the test method is generated. This option is useful if you are generating test methods that you are planning to add to an existing class.

Saturday, March 29, 2014

adbclient: under the hood of AndroidViewClient/culebra

Some of the reasons that made me think about replacing chimpchat, a library that facilitates the use of monkey from Java, used by monkeyrunner, which in turn is the bridge between monkey and Jython to be able to write python language scripts, is its instability and lack of concurrency support.

Long running tests, some lasting more than a day, had the serious problem of failing not because the test failed but because monkeyrunner connection with the device via chimpchat was frozen.

AndroidViewClient/culebra prior to version 4.0 relied on this same connection method as they were using monkeyrunner as the interpreter. This lead to a lot of problems reported against them.

adbclient is the answer to these problems. It's a 100% pure python implementation of an adb client that not only stabilizes the situation but also frees AndroidViewClient/culebra from monkeyrunner and Jython. Furthermore, even though it was not created as a standalone client and its only purpose was to satisfy AndroidViewClient/culebra needs in terms of Android device connections, there's nothing preventing you from using it in python scripts. There are some circumstances where you can even do something which is not even planned for its originator.

Here, I'm introducing an example that I hope spurs your imagination to use adbclient in many other cases. Sometimes, higher level methods supplied by AndroidViewClient/culebra are too high for the case at hands. Let's say you want to do some low-level processing on the screenshots taken and you desire is to do it from inside the same script, perhaps a python unittest, instead of saving the image using viewclient's View.writeImageToFile() or ViewClient.writeImageToFile() depending on your intentions of saving a single View versus a the entire device screen.
Having access to the Python Image Library (PIL) object before it's saved to a file entitles us to use vast PIL set of features, in this example we are calculating the image redness by using PIL's ImageStat.
In such case you can resort to adbclient's AdbClient.takeSnapshot(), as shown here.

#! /usr/bin/env python
# -*- coding: utf-8 -*-

import re
import sys
import os
import time
import math
from PIL import Image, ImageStat

from import AdbClient

def redness(image):
    stat = ImageStat.Stat(image)
    return stat.mean[0]/255.0

if len(sys.argv) >= 2:
    serialno = sys.argv[1]
    serialno = '.*'

device = AdbClient(serialno=serialno)
print redness(device.takeSnapshot())

Hope this helps you start using adbclient.

Tuesday, March 18, 2014

culebra's less known features: auto-regexp

This post starts a new series illustrating AndroidViewClient/culebra's less know features. The first instalment is dedicated to an extremely useful feature: auto-regexp.

But before going deeper into this option let's analyze a bit the general use case.
Very often, in the process of writing functional test cases you find yourself having to verify the result of some previous actions on the UI by recognizing some aspects of the device screen.

Traditionally this is done obtaining the screenshot and then applying some computational method to identify elements in the image and being able to determine if it is exactly what we were waiting for or in some cases up to what degree, allowing some parts of the image to vary.
This subject has been treated here before, for example in monkeyrunner: visual image comparison. However, we will be aiming a much simpler method in this post. Instead of using the image representing the screen we will be using the logical representation of it, that is the tree of Views visible at any given time.

Let's also consider the our device or emulator is showing the lock screen and that is the condition we want to detect.

culebra helps us creating the script to achieve this.

$ culebra --find-views-with-text=on

then we can verify that the device or emulator is showing the lock screen simply by running the script

$ ./

Nevertheless, when we run the script later, it will miserably fail with a message similar to this one

Traceback (most recent call last):
  File "./", line 44, in
    com_android_keyguard___id_clock_view = vc.findViewWithTextOrRaise(u'5:47')
  File "/usr/local/lib/python2.7/dist-packages/androidviewclient-5.4.2-py2.7.egg/com/dtmilano/android/", line 2220, in findViewWithTextOrRaise
    raise ViewNotFoundException("text", text, root) Couldn't find View with text='5:47' in tree with root=ROOT

I'm sure you have already guessed the reason. When we generated the script, the text in the View was used to generate the line

com_android_keyguard___id_clock_view = vc.findViewWithTextOrRaise(u'5:47')

We need a regular expression. We could add it manually but culebra can also help us generating this scripts by identifying some constructions and replacing them by their regular expressions counterpart. The option, as we mentioned before is auto-regexp. This option also has a help sub-option to clarify the possible values

$ culebra --auto-regexp=help
Available auto-regexps options:
    help: prints this help
    all: includes all the available regexps
    date: (Mon|Tue|Wed|Thu|Fri|Sat|Sun), (January|February|March|April|May|June|July|August|September|October|November|December) [0123]\d
    battery: Charging, \d\d%
    clock: [012]?\d:[0-5]\d

Adding this option to the original command line we will have

$ culebra --find-views-with-text=on \
    --auto-regexp=all \

and as a result our generated script contains lines like

com_android_keyguard___id_clock_view = vc.findViewWithTextOrRaise(re.compile(u'[012]?\d:[0-5]\d'))

and the screen identification will succeed even if date and time change.
Hope this helps you with your culebra scripts.

Friday, January 31, 2014

Installing AndroidViewClient using easy_install

There are a lof of ways of installing or upgrading AndroidViewClient but this is perhaps the easiest one, no wonder why the command name just mentions it.

If you don't have easy_install installed install the package python-setuptools.

$ sudo easy_install --upgrade androidviewclient
Searching for androidviewclient
Best match: androidviewclient 4.10.1
Processing androidviewclient-4.10.1-py2.7.egg
creating /usr/local/lib/python2.7/dist-packages/androidviewclient-4.10.1-py2.7.egg
Extracting androidviewclient-4.10.1-py2.7.egg to /usr/local/lib/python2.7/dist-packages
Removing androidviewclient 4.10.0 from easy-install.pth file
Adding androidviewclient 4.10.1 to easy-install.pth file

Installed /usr/local/lib/python2.7/dist-packages/androidviewclient-4.10.1-py2.7.egg
Processing dependencies for androidviewclient

Finished processing dependencies for androidviewclient

Monday, November 25, 2013

Android Continuous Integration Guides: Ebook I

 This book helps you explored Continuous Integration in practice providing valuable information to start applying it soon to your Android projects.

Employs Ant to automate the building process, git to create a simple version control system repository to store our source code and manage the changes, and finally installs and configures Jenkins as the Continuous Integration of choice. In this journey we detail the creation of jobs for automating the building process of TemperatureConverter, its dependency library LocalViewServer and its tests and we emphasized on the relationship between the projects.

Finally, we analyze a way of getting XML results from Android tests and implement this to obtain an attractive interface to monitor the running of tests, their results, and the existing trends and using and showing EMMA code coverage reports.

This will save you precious time and experimentation leading you through a step-by-step guide.

Visit Google Play Books to find more.

Thursday, October 10, 2013

AndroidViewClient/culebra version 4.6.0: now 100% pure python

AndroidViewClient/culebra v4.6.0 has been released bringing major improvements closing the gap with the existing APIs. This is demonstrated by the example scripts migrated to use AdbClient now, instead of MonkeyDevice.
monkeyrunner seems much farther in the rearview mirror.


  • AdbClient: Added isLocked() method to check if screen is locked
  • Fixed #55: drag doesn't work for old Android versions
  • Removed sys.path manipulation not needed for python
  • Read ANDROID_ADB_SERVER_PORT environment variable to set adb PORT. This variable is set by Jenkins Android Emulator plugin.
  • Merge pull request #56 from knorrium/clean-whitespaces
  • Check for sys.executable that may be not available on Windows
  • Examples modified to use python
  • Marked jar file creation as deprecated
  • Improved UTF-8 treatment in messages
  • AdbClient.startActivity() raises exception on errors
  • Warns if modules are imported using 'monkeyrunner'
  • Added image comparison
  • Decode used only on python's 8-bit strings
  • Restored obtainAdbPath() used for android API <= 16
  • Trap exception generated by integer division by zero in takeSnapshot()
  • Fixed famebuffer exception

Monday, September 09, 2013

AndroidViewClient/culebra takeSnapshot() improvements

The latest release of AndroidViewClient/culebra v.4.2.1 includes now the implementation of AdbClient.takeSnapshot(), replacing MonkeyDevice.takeSnapshot() used in previous releases.

Starting from AndroidViewClient v4.0.0, monkeyrunner was ditched in favor of plain good old python. This change brought massive speed improvements in running tests as it was described in AndroidViewClient/culebra version 4.0.0: now 100% pure python, and takeSnapshot() is not an exception.

In order to measure the improvement, 2 scripts were added to the examples, one taking a screenshot using MonkeyDevice.takeSnapshot() and the orher using the alternative AdbClient.takeSnapshot(). As with other functionality, the API is maintained so changes to existing scripts are unnecessary or just minimum.

The script taking the screenshot of the device or emulator using monkeyrunner.

#! /usr/bin/env monkeyrunner
Copyright (C) 2012  Diego Torres Milano
Created on Set 5, 2013

@author: diego

import sys
import os

from import MonkeyRunner, MonkeyDevice

if len(sys.argv) < 2:
    print >> sys.stderr, "usage: %s filename.png" % sys.argv[0]

filename = sys.argv.pop(1)
device = MonkeyRunner.waitForConnection()
device.takeSnapshot().writeToFile(filename, 'PNG')

The script taking the screenshot of the device or emulator using python.

#! /usr/bin/env python
Copyright (C) 2012  Diego Torres Milano
Created on Aug 31, 2013

@author: diego

import sys
import os

from import ViewClient

if len(sys.argv) < 2:
    sys.exit("usage: %s filename.png [serialno]" % sys.argv[0])

filename = sys.argv.pop(1)
device, serialno = ViewClient.connectToDeviceOrExit(verbose=False)
device.takeSnapshot().save(filename, 'PNG')


Both scripts were run to take the screenshot of a Nexus 4 (android api-18) home screen.

As you may have been anticipating, the python script run much faster and this is illustrated in the following chart.

Something to take into account is that both script are almost the same, except for some improvements that are supported only by AndroidViewClient, like the possibility of requesting a verbose connection or specifying the device serial number in the command line.
Also, notice that instead of writeToFile() like MonkeyImage does, save() is used. This is because AdbClient.takeSnapshot() returns a real PIL Image and not a wrapper.

Hope you enjoyed the changes.
If you have any question or comments just post it on Google+ or Stackoverflow.