dogtail

dogtail is a GUI testing and UI automation framework written in Python. It uses Accessibility (AT-SPI) technologies to interact with desktop applications, allowing you to automate real user workflows reliably.

Dogtail scripts are standard Python programs and can be run like any other Python code.

It works especially well with:

• behave (BDD testing)
• qecore (extends behave + dogtail)

Dogtail supports both Xorg and Wayland GNOME environments.

For Wayland usage details, see: https://fedoramagazine.org/automation-through-accessibility/

Table of Contents

• News
• FAQ
• Installation
• Dependencies
• Wayland Support
• Hermetic Sessions
• GTK4 Notes
• Usage
• API References
• Bugs & Support
• Contributing

News

dogtail 2.x.y

Details: https://gitlab.com/dogtail/dogtail/-/issues/29

The project was fully refactored to:

• Clean up years of technical debt
• Improve maintainability and readability
• Prepare for future accessibility backends (e.g., AccessKit/Newton)

Rather than continuing to patch dogtail 1.x, the codebase was rebuilt to make future evolution easier and safer.

dogtail 1.x.y

The legacy branch is still maintained as needed:

https://gitlab.com/dogtail/dogtail/-/tree/dogtail-1.x

FAQ

https://gitlab.com/dogtail/dogtail/-/blob/master/FAQ.md

Installation

From GitLab (build locally)

git clone https://gitlab.com/dogtail/dogtail.git
cd dogtail
python3 -m build
sudo pip3 install dist/dogtail-2.*-py3-none-any.whl

From GitLab (pip)

sudo dnf install python3-pip
sudo python3 -m pip install git+https://gitlab.com/dogtail/dogtail@master

From PyPI

sudo python3 -m pip install dogtail

From GitLab Package Registry

Packages are built automatically by CI:

https://gitlab.com/dogtail/dogtail/-/packages/

Dependencies

Core requirements:

• Python bindings for your distro (e.g., python-apt, rpm-python)
• GNOME Python libraries

Test targets typically include GNOME applications:

https://www.gnome.org/

Wayland-specific dependency

To run on Wayland GNOME, install gnome-ponytail-daemon:

https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon

The gnome-ponytail-daemon is packaged in Fedora distribution:

dnf install -y gnome-ponytail-daemon
dnf install -y python3-gnome-ponytail-daemon

Building from source:

sudo dnf install meson gcc glib2-devel
git clone https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon.git
cd gnome-ponytail-daemon
sudo meson setup build
sudo ninja -C build
sudo ninja -C build install

Wayland Support

Wayland input automation is enabled through gnome-ponytail-daemon, which uses:

• Screen Cast API
• Remote Desktop API
• GNOME Shell Introspection

This allows Dogtail to:

• Connect to specific windows
• Translate local UI coordinates to global screen positions
• Simulate keyboard and mouse input reliably

What this means in practice

Dogtail handles the complexity internally. Most test scripts run identically on:

• Xorg sessions
• Wayland GNOME sessions

On Xorg, traditional X input APIs are used automatically.

Hermetic Sessions

The above needs a logged-in GNOME session. dogtail.hermetic does not. It boots a private D-Bus, a private a11y bus and a bare mutter with a virtual monitor, runs the test against those, and throws them away. Input injection goes over the Mutter RemoteDesktop D-Bus API instead of gnome-ponytail-daemon, so a CI container with no graphics session is enough.

dogtail-headless logs a real desktop in through gdm. HermeticSession boots a compositor instead.

session = HermeticSession()
session.boot()
session.launch(["myapp"])
application = session.wait_for_app("myapp")
application.child("click me").do_action_named("click")
session.teardown()

One limitation is worth knowing up front: a Wayland client is never told where it was placed, so AT-SPI coordinates are window-local while injection is screen-global. They only agree on a fullscreen window, and node.click() raises CoordinatesUnavailable anywhere else rather than clicking the wrong thing.

Requirements, a pytest fixture, and the rest: HERMETIC.md.

GTK4 Notes

For GTK4 applications, window shadows must be disabled for accurate coordinate handling.

Add the following to:

~/.config/gtk-4.0/gtk.css

window, .popover, .tooltip {
    box-shadow: none;
}

Why this is necessary

• Shadows introduce variable coordinate offsets
• Offsets differ per application, size, and scaling
• Disabling shadows ensures consistent automation behavior

Dogtail automatically manages known offsets using dogtail.config.gtk4_offset.

Usage

Currently supported:

• GNOME and GTK applications
• Xorg and Wayland sessions
• Limited Qt support via qt-at-spi (not officially maintained)

Enable accessibility

gsettings set org.gnome.desktop.interface toolkit-accessibility true

Restart applications (or log out/in) after enabling.

Headless environments using dogtail-headless or qecore-headless enable this automatically.

API References

• https://lazka.github.io/pgi-docs/#Atspi-2.0
• https://docs.gtk.org/atspi2/index.html

Bugs & Support

Report issues here:

https://gitlab.com/dogtail/dogtail/issues

Project home:

https://gitlab.com/dogtail/dogtail/

API docs (incomplete for both versions, in progress for 2.x):

http://fedorapeople.org/~vhumpa/dogtail/epydoc/

Mailing lists and IRC are deprecated — please use GitLab.

Contributing

Bug reports

• Search existing issues first
• Include steps to reproduce and environment details

Feature ideas

• Open an issue to discuss before coding

Code style guidelines

• Use docstrings for all public functions and methods
• Follow snake_case naming
• Prefer descriptive variable names
• Write full-sentence comments with proper punctuation

Your contributions are welcome! 🚀