wiki:WikiStart
Last modified 4 days ago Last modified on 04/16/14 14:28:44

dogtail

News

Dogtail 0.9.0 is out!

Apr-16-2014

Over the last year we've made a good number of fixes, added some new features and got overall stability to the point where we can make a new 'major minor' release. With 0.9 we're finally getting only a step away from what we'd like to get done with 1.0. Also thanks to you all who helped us out by sending patches. For details on what's new, check the NEWS.

Also, if looking for offline api docs, you can download the latest here

Dogtail 0.8.2 is out!

Second update to the 0.8 series containing several fixes and improvements (notably new dogtail-run-headless-next) is out. Check NEWS

Dogtail 0.8.1 is out

A first update to the 0.8.x branch is out, containing several fixes as well as some sniff improvements.

Dogtail 0.8.0 Final is out!

See what's new: NEWS!

  • Dogtail 0.8.0 Release Candidate is out!
  • After more then two years a 0.7.x branch update containing several fixes, version 0.7.1, is now out!
  • Thanks to qt-at-spi project, QT can now be used with dogtail!

What is it?

dogtail is a GUI test tool and automation framework written in Python. It uses Accessibility (a11y) technologies to communicate with desktop applications. dogtail scripts are written in Python and executed like any other Python program.

Features

  • It's Just Python™: If you can do it in Python, you can do it with dogtail.
  • Object-Oriented API: With the object oriented API, you are under control of the UI tree and its elements, allowing you to write sophisticated scripts utilizing benefits of OO right deep from dogtail.
  • Procedural API: However ace programmer credentials are not necessary to write useful automated scripts with procedural API.
  • Easily Extensible: dogtail is object oriented "under the covers" so more advanced users can write custom classes and helper libraries easily.
  • Results and debug reporting: Separate logs for test case comparisons and debug information mean less messing around for you.
  • AT-SPI browser: Digging through the often-cluttered hierarchy of AT-SPI objects can be tedious. Our browser, Sniff, makes it easier.

How do I get it?

With the release of Gnome 3, at-spi a11y has been rewritten as well as Gtk2 moved on to Gtk3. This called for porting dogtail to use the updated technologies currently unsupported by the 0.7.1 version. Thus we worked on a new 0.8 branch which is fully compatible with the new systems. More than that - thanks to qt-at-spi - from 0.8.0 onward dogtail doesn't limit itself only to GNOME/GTK applications and can be used with KDE/QT apps as well! So, for your distribution what release to get? It's simple:

Dogtail 0.8.x forward - for "GNOME 3 systems" or "KDE4.8+ systems"

For Fedora 15+, Ubuntu 11.04+ or simply all systems with Gnome 3 - get dogtail 0.9.0.

If you use Fedora you can simply do:

yum install dogtail

If you use RHEL7/Centos or some other Red Hat based system, you can try the latest distribution-less rpm from over here or, you can use the EL7 epel.

If you don't use Fedora, just grab the latest tarball from: https://fedorahosted.org/released/dogtail/

Dogtail 0.7.x - for "Gnome 2 systems"

For all Fedora releases until 14, RHEL6, CentOS6, pre-Unity Ubuntu or simply all systems still having Gnome 2 - get version 0.7.1.1:

If you use Fedora, have RHEL Epel etc., you can simply do:

yum install dogtail

Or you can download the latest released tarball: dogtail-0.7.1.1.tar.gz

Git repository

If you want to check out our source code repository, do:

git clone git://git.fedorahosted.org/git/dogtail.git

How do I use it?

dogtail exposes elements on your desktop in a hierarchical interface. That is, you'll be working with a tree of objects like this:

  • main
    • gnome-panel
      • Top Panel
      • Bottom Panel
    • xchat-gnome
      • Freenode: #dogtail

A useful tool for writing dogtail scripts is Sniff (/usr/bin/sniff or "AT-SPI Browser" in your menu), a graphical browser of that hierarchy written using dogtail. You may also want to look at the dogtail recorder (/usr/bin/dogtail-recorder or "Dogtail Script Recorder" in your menu; only in 0.7.x for now), which can actually do much of the work of script writing for you.

If you're familiar with Python, you may want to start with the dogtail.tree module - specifically, dogtail.tree.root.

If you are new to Python and/or programming in general, you may want to look at The Python Tutorial and the dogtail.procedural module.

And then, there's always the example scripts.

API Documentation

dogtail's API tries to be self-documented, but also uses docstrings whenever possible. If you prefer to read your documentation in a web browser, head over to the HTML API docs (tarball) for 0.8.x forward and here for 0.7.x branch.

NOTE: We try to keep compatible, thus so far the only change between GNOME2-ish and GNOME3-ish branches on the side of API provided is that tree.doAction has been renamed to tree.doActionNamed