Hi Craig,
I am glad that you've become interested in Dogtail. Let me try to answer in steps :)
1. Using dogtail really isn't hard, which is likely why the examples don't go very deep. Hopefully seeing the general flow of either object-oriented or procedural script together with browsing the API docs[1] online (tree or procedural modules) can help one to get started writing automation for his/her application. The tricky part sometimes isn't the scripting really but rather knowing what to use for scripting. That is using sniff or 'dump' to search the application UI nodes that you subsequently work with and learning how to identify nodes uniquely using i.e. child method with name and roleName params. Another great tool to look through the accessibility tree is also the accerciser. But I understand that some tutorial that would help speed things up is lacking, I might just put it in my todo-list to make one.
A good tip to get started is to look at the Node class in the tree module. Basically in your scripts the best way is to search for particular UI elements using the .child() method that you can subsequently apply methods on, might it be clicking, setting text, executing some actions etc. You should always start by getting the root node for your application using "app = root.application('appname')" Following that, you just apply the .child() method until you get to the particular element(node) you want to work with. All nodes have a good number of methods that should cover the testing needs of your applications.
2. That was indeed the OO way of doing things that seems to do the job best. Dogtail also allows for procedural way of programming (using the procedural module) where you do not work with the tree of UI elements but instead use functions like focus to bring forward the element of choice and than apply other non-class functions. This is the kind of the code that the dogtail-recorder would help produce. The dogtail-recorder is currently only available on releases up to 0.7.x. We've dropped it from the newer (GNOME3 compatible) releases actually, as after some time it didn't seem quite as useful as hoped for before to write tests. It really just records the actions that you as a user do, (click this menu item, type this text, click at this location) and the output is then somewhat more susceptible to changes in the app as well as particular desktop configuration.
3. 'Greping' the output of .dump() is sometimes a good way of making sure that a particular Node is unique in the app, so you know you can safely get it using .child() right from the top Node. I am using this super-simple script to produce dumps off applications onto stdout that I can either store in files for examination as well 'grep' directly.
#!/usr/bin/python
from dogtail.tree import *
import sys
app = root.application(sys.argv[1])
app.dump()
Still, I am only using dump after I've already found the node with Sniff. The highlight function of Sniff is very useful in getting to some node fast.
4. Sum-up:
- look at the examples for the basics of how the script structure looks like (best the Tree ones); (best look for examples in the newest tarball (0.8.x) as they got updated)
- look at the UI tree of your app to find nodes you want with sniff(or accerciser, or just .dump)
- see what methods you can apply on these nodes in the API docs for tree.Node
- see also what else you can use from utils and rawinput when you need to work outside of only the tree scope
Please don't hesitate to contact us with any specific issue in your script on dogtail-list or you can find me at #dogtail channel on freenode (I am UTC+1).
Vita
