Ed Rousseau <rousseau@redhat.com>,
David Malcolm <dmalcolm@redhat.com>,
Vitezslav Humpa <vhumpa@redhat.com>,
Michal Odehnal <modehnal@redhat.com>
Author-email: Zack Cerza <zcerza@redhat.com>, Ed Rousseau <rousseau@redhat.com>, David Malcolm <dmalcolm@redhat.com>, Vitezslav Humpa <vhumpa@redhat.com>, Michal Odehnal <modehnal@redhat.com>
Project-URL: Homepage, https://gitlab.com/dogtail/dogtail
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: COPYING
dogtail
=======
dogtail is a GUI test tool and UI 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.
Dogtail works great in combination with behave and qecore (based on behave and dogtail), especially if you're interested in using it with modern Wayland-based GNOME. Please see this article for more details on how we mainly use it:
`Automation through accessibility <https://fedoramagazine.org/automation-through-accessibility/>`_.
Other than that, dogtail should work with any desktop environment that still runs atspi with Xorg.
News
====
dogtail 1.0
-----------
After more than five years of continuous experimentation and development, we are excited to finally release Dogtail 1.0—a Wayland-enabled version of Dogtail! How did we achieve this? It was made possible by the `gnome-ponytail-daemon <https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon>`_, originally crafted by Olivier Fourdan. This tool allows us to perform actions in a Wayland GNOME session in a similar way to how we have been doing so with X functions.
dogtail 1.0.5 - Contains several fixes to unittests and adding support for / Dec 12 2024
Arch Linux from Steffen Rehberg (thanks!)
dogtail 1.0.4 - Minor release again containing two updates! / Dec 4 2024
- sniff: Fixes in About dialog and getting rid of GObject deprecations MR #43
- tree: Moving all matches of "push button" to check also "button" - Fixes issue #35
dogtail 1.0.3 - Minor release again containing two updates / Nov 13 2024
- utils: get_current_x_window_position: Support running without a wm
- tree : Improve center property calculation in Node class
Thanks Samuel Thibault and mikigo for the MR and discussion!
dogtail 1.0.2 - Cummulated two updates - bugfixes - and releasing as minor release. / Oct 24 2024
Update for sniff: Switched using XPM icons to PNG as the most recent gdk pixbug no longer supports them
(fixes no icons in most recent system) - thanks to Jiri Prajzner
Using specific configuration for the debug logger to prevent duplicit logging - MR#39 - thanks to Jiri Kortus
dogtail 1.0.1 - Rebased with a number of contributions that were done to the master branch while we were / Sep 6 2024
working on Wayland and we have accidentaly not included them in 1.0.
See https://gitlab.com/dogtail/dogtail/-/issues/31
Also returned couple of modules we thought were of no use (tc, wrapped) but were proved otherwise to keep 1.0 fully compatible with 0.x.
How does it work in brief?
--------------------------
The core functionality relies on the Screen Cast and Remote Desktop API, enabling us to "connect" to either a specific window or the entire screen to simulate user input actions like key presses, typing, and—most importantly—mouse actions on specific coordinates. Ponytail uses the window list from ``org.gnome.Shell.Introspect`` to identify windows. Dogtail then ensures the correct window is connected via the Remote Desktop API, allowing input actions to be accurately executed within it.
On the AT-SPI tree and accessibility's "introspection" side, not much has changed—input has primarily been the challenge on Wayland. The main difference is that only "local" window coordinates are known for UI items. To address this, we always connect to the specific window we're working with, and Ponytail's ``connectWindow`` ensures these local coordinates are translated to global ones internally.
What does this mean for users?
------------------------------
Dogtail handles all of this logic seamlessly, so in practical use, the user doesn't need to worry about coordinate types or window connections. In fact, the vast majority of our tests work identically in both X and Wayland sessions using the Dogtail API. When running on an X session, Dogtail will use the traditional X functions to handle input and operate as it always has.
A long journey to 1.0
---------------------
We began working on the Wayland-enabled version over five years ago (originally available in the ``devel/wayland`` branch). It has taken all this time to ensure the solution is robust and reliable enough to warrant a 1.0 release. This version includes all the Wayland-related developments and other changes (like the GTK4 support tweaks mentioned below) and has been extensively tested. Importantly, it is backward compatible with the entire Dogtail API that has been available so far. This release includes all modules from the 0.9.x series, most notably the "procedural" module, which we plan to deprecate in favor of a completely "tree-based" approach in Dogtail 2.0.
That release will also involve significant cleanup, major code refactoring, and a transition from ``pyatspi`` to directly introspected ``atspi``. It will also contain updated code examples and Dogtail's unittests should pass with GitLab pipelines re-enabled.
For more details on these upcoming changes, see issue #29.
1.0+ Important: Handling GTK4 Application Windows in Dogtail
------------------------------------------------------------
For GTK4 applications, disabling window shadows is essential to ensure accurate positioning by Dogtail. With shadows disabled, we encounter a consistent coordinate offset, which we've preconfigured as ``dogtail.config.gtk4Offset``. In the case of working with fullscreen windows, the offset is 0, and we manage to detect that on-the-fly both in X11 and Wayland sessions. However, this process requires ``python-xlib``, even for Wayland sessions, leveraging Xwayland to ascertain resolution information, as no more direct method we've found is currently available for Wayland.
When window shadows are active, the perceived offset can vary significantly, influenced by factors such as the specific application, window size, and scaling settings. To ensure consistent behavior across applications, disabling shadows is recommended.
Disabling Shadows in GTK4:
To disable window shadows, add the following CSS to your GTK4 configuration (``~/.config/gtk-4.0/gtk.css``):
.. code-block:: css
window, .popover, .tooltip {
box-shadow: none;
}
Installation
============
Dogtail is available with PIP! (1.0 inclusion pending). If you'd like to use it with Wayland GNOME, you also need to get the ``dogtail-ponytail-daemon``: https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon. We do not have that as a dependency in PIP as it compiles C code.
Check your distro for packages! If not at the latest version, we also have released tarballs for download: https://gitlab.com/dogtail/dogtail/tree/released
For details see the INSTALL file.
Dependencies
============
Python bindings for your distribution, e.g. python-apt or rpm-python
PyGObject and GNOME-Python
Applications to test, e.g. from the GNOME desktop: http://gnome.org/
Using
=====
Currently, GNOME and GTK+ applications are supported, in both Xorg and Wayland sessions.
See examples for direct dogtail use or check the following article for more information:
`Automation through accessibility <https://fedoramagazine.org/automation-through-accessibility/>`_.
If you are using KDE instead, set the environment variable ``QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1`` when launching the respective program.
You can add this line to your profile file:
.. code-block:: bash
export QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1
Depending on the version, ``QT_ACCESSIBILITY=1`` may be needed instead.
For very old KDE/QT versions (approximately 4.8.3 to 5.0), you have to install the ``qt-at-spi`` QT plugin and set the environment variable ``QT_ACCESSIBILITY`` to 1.
First, enable accessibility support in your GNOME session with the following command:
.. code-block:: bash
gsettings set org.gnome.desktop.interface toolkit-accessibility true
This only affects newly-started applications, so you may want to log out and log back in again.
Should you run ``sniff`` first, or be using ``dogtail-run-headless-next`` or ``qecore-headless`` scripts to handle your sessions, the accessibility will be auto-enabled for you.
Bugs
====
Please report any bugs at:
https://gitlab.com/dogtail/dogtail/issues
Contact
=======
Website:
https://gitlab.com/dogtail/dogtail/
Issue tracker:
https://gitlab.com/dogtail/dogtail/issues
API Documentation:
http://fedorapeople.org/~vhumpa/dogtail/epydoc/
We have deprecated our mailing lists as well as the IRC channel. Please use our GITLAB for issues and merge requests! (Or possibly https://github.com/vhumpa/dogtail for your pull requests should you prefer to use GitHub, but gitlab.com is preferred)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/dogtail/dogtail",
"name": "dogtail",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Zack Cerza <zcerza@redhat.com>,",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fe/2b/64b258ac826a59df567876879976361726e4b2a49e6fc6a985ecd74b6af7/dogtail-1.0.5.tar.gz",
"platform": null,
"description": "Ed Rousseau <rousseau@redhat.com>,\nDavid Malcolm <dmalcolm@redhat.com>,\nVitezslav Humpa <vhumpa@redhat.com>,\nMichal Odehnal <modehnal@redhat.com>\nAuthor-email: Zack Cerza <zcerza@redhat.com>, Ed Rousseau <rousseau@redhat.com>, David Malcolm <dmalcolm@redhat.com>, Vitezslav Humpa <vhumpa@redhat.com>, Michal Odehnal <modehnal@redhat.com>\nProject-URL: Homepage, https://gitlab.com/dogtail/dogtail\nRequires-Python: >=3.6\nDescription-Content-Type: text/x-rst\nLicense-File: COPYING\n\ndogtail\n=======\n\ndogtail is a GUI test tool and UI 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.\n\nDogtail works great in combination with behave and qecore (based on behave and dogtail), especially if you're interested in using it with modern Wayland-based GNOME. Please see this article for more details on how we mainly use it:\n`Automation through accessibility <https://fedoramagazine.org/automation-through-accessibility/>`_.\n\nOther than that, dogtail should work with any desktop environment that still runs atspi with Xorg.\n\nNews\n====\n\ndogtail 1.0\n-----------\n\nAfter more than five years of continuous experimentation and development, we are excited to finally release Dogtail 1.0\u2014a Wayland-enabled version of Dogtail! How did we achieve this? It was made possible by the `gnome-ponytail-daemon <https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon>`_, originally crafted by Olivier Fourdan. This tool allows us to perform actions in a Wayland GNOME session in a similar way to how we have been doing so with X functions.\n\ndogtail 1.0.5 - Contains several fixes to unittests and adding support for / Dec 12 2024\nArch Linux from Steffen Rehberg (thanks!)\n\ndogtail 1.0.4 - Minor release again containing two updates! / Dec 4 2024\n- sniff: Fixes in About dialog and getting rid of GObject deprecations MR #43\n- tree: Moving all matches of \"push button\" to check also \"button\" - Fixes issue #35\n\ndogtail 1.0.3 - Minor release again containing two updates / Nov 13 2024\n- utils: get_current_x_window_position: Support running without a wm\n- tree : Improve center property calculation in Node class\nThanks Samuel Thibault and mikigo for the MR and discussion!\n\ndogtail 1.0.2 - Cummulated two updates - bugfixes - and releasing as minor release. / Oct 24 2024\nUpdate for sniff: Switched using XPM icons to PNG as the most recent gdk pixbug no longer supports them\n(fixes no icons in most recent system) - thanks to Jiri Prajzner\nUsing specific configuration for the debug logger to prevent duplicit logging - MR#39 - thanks to Jiri Kortus\n\n\ndogtail 1.0.1 - Rebased with a number of contributions that were done to the master branch while we were / Sep 6 2024\nworking on Wayland and we have accidentaly not included them in 1.0.\nSee https://gitlab.com/dogtail/dogtail/-/issues/31\n\nAlso returned couple of modules we thought were of no use (tc, wrapped) but were proved otherwise to keep 1.0 fully compatible with 0.x.\n\nHow does it work in brief?\n--------------------------\n\nThe core functionality relies on the Screen Cast and Remote Desktop API, enabling us to \"connect\" to either a specific window or the entire screen to simulate user input actions like key presses, typing, and\u2014most importantly\u2014mouse actions on specific coordinates. Ponytail uses the window list from ``org.gnome.Shell.Introspect`` to identify windows. Dogtail then ensures the correct window is connected via the Remote Desktop API, allowing input actions to be accurately executed within it.\n\nOn the AT-SPI tree and accessibility's \"introspection\" side, not much has changed\u2014input has primarily been the challenge on Wayland. The main difference is that only \"local\" window coordinates are known for UI items. To address this, we always connect to the specific window we're working with, and Ponytail's ``connectWindow`` ensures these local coordinates are translated to global ones internally.\n\nWhat does this mean for users?\n------------------------------\n\nDogtail handles all of this logic seamlessly, so in practical use, the user doesn't need to worry about coordinate types or window connections. In fact, the vast majority of our tests work identically in both X and Wayland sessions using the Dogtail API. When running on an X session, Dogtail will use the traditional X functions to handle input and operate as it always has.\n\nA long journey to 1.0\n---------------------\n\nWe began working on the Wayland-enabled version over five years ago (originally available in the ``devel/wayland`` branch). It has taken all this time to ensure the solution is robust and reliable enough to warrant a 1.0 release. This version includes all the Wayland-related developments and other changes (like the GTK4 support tweaks mentioned below) and has been extensively tested. Importantly, it is backward compatible with the entire Dogtail API that has been available so far. This release includes all modules from the 0.9.x series, most notably the \"procedural\" module, which we plan to deprecate in favor of a completely \"tree-based\" approach in Dogtail 2.0.\n\nThat release will also involve significant cleanup, major code refactoring, and a transition from ``pyatspi`` to directly introspected ``atspi``. It will also contain updated code examples and Dogtail's unittests should pass with GitLab pipelines re-enabled.\n\nFor more details on these upcoming changes, see issue #29.\n\n1.0+ Important: Handling GTK4 Application Windows in Dogtail\n------------------------------------------------------------\n\nFor GTK4 applications, disabling window shadows is essential to ensure accurate positioning by Dogtail. With shadows disabled, we encounter a consistent coordinate offset, which we've preconfigured as ``dogtail.config.gtk4Offset``. In the case of working with fullscreen windows, the offset is 0, and we manage to detect that on-the-fly both in X11 and Wayland sessions. However, this process requires ``python-xlib``, even for Wayland sessions, leveraging Xwayland to ascertain resolution information, as no more direct method we've found is currently available for Wayland.\n\nWhen window shadows are active, the perceived offset can vary significantly, influenced by factors such as the specific application, window size, and scaling settings. To ensure consistent behavior across applications, disabling shadows is recommended.\n\nDisabling Shadows in GTK4:\n\nTo disable window shadows, add the following CSS to your GTK4 configuration (``~/.config/gtk-4.0/gtk.css``):\n\n.. code-block:: css\n\n window, .popover, .tooltip {\n box-shadow: none;\n }\n\nInstallation\n============\n\nDogtail is available with PIP! (1.0 inclusion pending). If you'd like to use it with Wayland GNOME, you also need to get the ``dogtail-ponytail-daemon``: https://gitlab.gnome.org/ofourdan/gnome-ponytail-daemon. We do not have that as a dependency in PIP as it compiles C code.\n\nCheck your distro for packages! If not at the latest version, we also have released tarballs for download: https://gitlab.com/dogtail/dogtail/tree/released\n\nFor details see the INSTALL file.\n\nDependencies\n============\n\nPython bindings for your distribution, e.g. python-apt or rpm-python\n\nPyGObject and GNOME-Python\n\nApplications to test, e.g. from the GNOME desktop: http://gnome.org/\n\nUsing\n=====\n\nCurrently, GNOME and GTK+ applications are supported, in both Xorg and Wayland sessions.\nSee examples for direct dogtail use or check the following article for more information: \n`Automation through accessibility <https://fedoramagazine.org/automation-through-accessibility/>`_.\n\nIf you are using KDE instead, set the environment variable ``QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1`` when launching the respective program. \nYou can add this line to your profile file:\n\n.. code-block:: bash\n\n export QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1\n\nDepending on the version, ``QT_ACCESSIBILITY=1`` may be needed instead.\n\nFor very old KDE/QT versions (approximately 4.8.3 to 5.0), you have to install the ``qt-at-spi`` QT plugin and set the environment variable ``QT_ACCESSIBILITY`` to 1.\n\nFirst, enable accessibility support in your GNOME session with the following command:\n\n.. code-block:: bash\n\n gsettings set org.gnome.desktop.interface toolkit-accessibility true\n\nThis only affects newly-started applications, so you may want to log out and log back in again.\n\nShould you run ``sniff`` first, or be using ``dogtail-run-headless-next`` or ``qecore-headless`` scripts to handle your sessions, the accessibility will be auto-enabled for you.\n\nBugs\n====\n\nPlease report any bugs at:\n https://gitlab.com/dogtail/dogtail/issues\n\nContact\n=======\n\nWebsite:\n https://gitlab.com/dogtail/dogtail/\n\nIssue tracker:\n https://gitlab.com/dogtail/dogtail/issues\n\nAPI Documentation:\n http://fedorapeople.org/~vhumpa/dogtail/epydoc/\n\nWe have deprecated our mailing lists as well as the IRC channel. Please use our GITLAB for issues and merge requests! (Or possibly https://github.com/vhumpa/dogtail for your pull requests should you prefer to use GitHub, but gitlab.com is preferred)\n",
"bugtrack_url": null,
"license": null,
"summary": "GUI test tool and automation framework that uses Accessibility (a11y) technologies to communicate with desktop applications.",
"version": "1.0.5",
"project_urls": {
"Homepage": "https://gitlab.com/dogtail/dogtail"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5bdd2ee5c443e2c750993d5be9f201e27c0e26a794c335e47e3199a5d9fe1b3f",
"md5": "947ffe33eecdf3f22f81dec8f28300b5",
"sha256": "f585f45a68d8b4d07bd7c7095f85d04b385c04eb705eaf5f2d8bf5473d38222a"
},
"downloads": -1,
"filename": "dogtail-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "947ffe33eecdf3f22f81dec8f28300b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 143453,
"upload_time": "2024-12-12T12:34:59",
"upload_time_iso_8601": "2024-12-12T12:34:59.547823Z",
"url": "https://files.pythonhosted.org/packages/5b/dd/2ee5c443e2c750993d5be9f201e27c0e26a794c335e47e3199a5d9fe1b3f/dogtail-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fe2b64b258ac826a59df567876879976361726e4b2a49e6fc6a985ecd74b6af7",
"md5": "a8046d347768651d8a3d54da6fd3d7ef",
"sha256": "ae66611697277dcab1ea9d2e9fcfdcd325d6222b555f60dc20fd9550baa138b3"
},
"downloads": -1,
"filename": "dogtail-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "a8046d347768651d8a3d54da6fd3d7ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 145645,
"upload_time": "2024-12-12T12:35:02",
"upload_time_iso_8601": "2024-12-12T12:35:02.399585Z",
"url": "https://files.pythonhosted.org/packages/fe/2b/64b258ac826a59df567876879976361726e4b2a49e6fc6a985ecd74b6af7/dogtail-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 12:35:02",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "dogtail",
"gitlab_project": "dogtail",
"lcname": "dogtail"
}
JSON