Dogtail Recipes

No, this entry has nothing to do with strange food.  I am doing some experimenting today with the Dogtail GUI test tool in order to evaluate its capablities for testing apps on Linux.  First off, documentation on dogtail is very hard to come by.  The API docs on the dogtail site are very old so avoid using them if you can.  I recommend the following series of articles instead:
 
Automated GUI testing with Dogtail
Dogtail's Python Modules (and how to use them)
Dogtail’s object oriented tree API (and how to use it)
 
This article on the Ubuntu wiki has some very helpful information too.
 
Recipe 1 : Figuring out what you can do with a Node
 
When first using dogtail's procedural API, the Node objects that you get are a little hard to figure out.  Python's "dir" function can help you determine what functions are available.
 

from dogtail.procedural import *
from dogtail.utils import *
from dogtail import tree
run("oowriter",5)
focus.frame('Untitled1 - OpenOffice.org Writer')
oowriter = tree.root.application('soffice')
menuFile = oowriter.menu('File')
dir(menuFile)

['_Node__accessible', '_Node__action', '_Node__component', '_Node__editableText', '_Node__hideChildren', '_Node__hypertext', '_Node__nodeIsIdentifiable', '_Node__selection', '_Node__text', '__doc__', '__getattr__', '__init__', '__module__', '__setattr__', '__str__', 'addSelection', 'blink', 'button', 'child', 'childLabelled', 'childNamed', 'click', 'contained', 'debugName', 'deselect', 'deselectAll', 'doAction', 'dump', 'findAncestor', 'findChild', 'findChildren', 'getAbsoluteSearchPath', 'getLogString', 'getNSelections', 'getRelativeSearch', 'getUserVisibleStrings', 'grabFocus', 'keyCombo', 'menu', 'menuItem', 'rawClick', 'removeSelection', 'satisfies', 'select', 'selectAll', 'setSelection', 'tab', 'textentry', 'typeText']

 
You should also take a look in the "actions" attribute to
 

menuFile.actions.keys()
['']

 
Unfortunately for me "click", "press" or "release" are not present in the actions list, so I cannot use dogtail to click this particular item.
 
Recipe 2 - Clicking things that do not want to be clicked
 
In the example above, I get this error message whenever I try calling the click() method on the File menu.
 

fileMenu.click()
ActionNotSupported: Cannot do 'click' action on {"File" menu}

 
There are two options here.  The first is to try the rawClick() function.
 

fileMenu.rawClick()

 
You could also use the Node's postion (and size) along with the xte command.
 

import os
os.system ("xte 'mousemove " + str(fileMenu.position[0]) + " " + str(fileMenu.position[1]) + "'")
os.system ("xte 'mouseclick 1'")

 
Using xte in conjunction with dogtail brings up some very interesting possibilities.  I have recently been experimenting with a test automation model that involves two core pieces: an agent and a user.  The agent is responsible for helping the user locate objects within the application as well as inspect the state of objects for verification points.  The user component takes object location and state information from the agent and uses it to interact directly with the desktop like a real user would - clicking or moving the mouse and pressing keys on the keyboard.  Because dogtail Node objects have both position and size data as well as some state information like an object's text value, dogtail would make a very good agent in this testing model.
 
Recipe 3 - Running more than one line of code at once in the python iterpreter
 
In the example above, I insisted on being able to click a particular GUI component.  That is a little hardheaded of me when using help from the keyboard might have been a simpler approach.  Here I select the "File" menu and then the "Exit" item without using the mouse.
 

#Quit the app
menuItemExit = menuFile.menuItem('Exit')
menuFile.select()
keyCombo('Return')
menuItemExit.select()
keyCombo('Return')

 
Finally note that while using the interpreter you would need to run all the statements above on one line using a semicolon to seperate each statement:
 
>>> menuFile.select(); keyCombo('Return'); menuItemExit.select(); keyCombo('Return')