# Qat (Qt Application Tester)
## Description
Qat is a testing framework for Qt-based applications.
Qat provides a Python API to interact with any existing Qt application by accessing QML/QtQuick/QWidget elements and simulating user manipulations.
It is also integrated to [behave](https://github.com/behave/behave) to support Behavior-Driven Development (BDD) with the [Gherkin language](https://cucumber.io/docs/gherkin/).
Although Qat uses the GUI to interact with the tested application, it is oriented towards BDD and functional testing rather than UI or non-regression testing.
The main objective of Qat is to provide quick feedback to developers and easy integration to build systems.
## Requirements
Qat requires Python >= 3.9.
Qat supports C++ applications as well as Python bindings such as PySide and PyQt.
Tested applications don't need to be modified but they must be compiled in release mode with a compatible compiler and a dynamically-linked Qt version:
| Qt | Linux (gcc) | Windows (MSVC) | Mac OS (Arm & Intel) |
|----|-------------|----------------|----------------------|
| __5.15 (LTS)__ | __yes__ | __yes__ | __yes<sup>1</sup>__ |
| __6.0__ | _no_ | _no_ | _no_ |
| __6.1__ | _no_ | _no_ | _no_ |
| __6.2 (LTS)__ | __yes__ | __yes__ | __yes__ |
| __6.3__ | __yes__ | __yes__ | __yes__ |
| __6.4__ | __yes__ | __yes__ | __yes__ |
| __6.5 (LTS)__ | __yes__ | __yes__ | __yes__ |
| __6.6__ | __yes__ | __yes__ | __yes__ |
| __6.7__ | __yes__ | __yes__ | __yes__ |
| __6.8 (LTS)__ | __yes__ | __yes__ | __yes__ |
---
<sup>1</sup> Qt 5 requires [Rosetta](https://support.apple.com/en-ca/102527) to run on Silicon machines
## Installation
Qat can be installed with Pip:
```bash
pip install qat
```
This will also install the following dependencies:
- behave (for BDD testing)
- customtkinter and pillow (for GUI)
- tkinter-tooltip (for GUI)
- xmlschema (for test report)
### Tkinter
If [`tkinter`](https://docs.python.org/3/library/tkinter.html) did not come pre-packaged with your python installation, you may need to install it manually.
#### Arch / Manjaro / Other derivatives
To install [`tkinter`](https://archlinux.org/packages/extra/x86_64/tk/), run the following command as root:
```bash
pacman -S tk
```
#### Debian / Other derivatives
To install [`tkinter`](https://packages.debian.org/bookworm/python3-tk/), run the following command as root:
```bash
apt-get install python3-tk
```
#### Fedora
To install [`tkinter`](https://pkgs.org/download/python3-tkinter/), run the following command as root:
```bash
dnf install python3-tkinter
```
#### MacOS
To install [`tkinter`](https://formulae.brew.sh/formula/python-tk@3.12), run the following command as root:
```bash
brew install python-tk
```
## Setup
The recommended approach is to install [VSCode](https://code.visualstudio.com/download) with the following extensions:
- Python
- Pylance
- Test Explorer UI
- Behave VSC (for BDD)
Any Python (+ Gherkin) environment can be used (PyCharm, Eclipse/Pydev, VSCode, ...) but the present documentation will use VSCode as a tutorial.
## Usage
### Creating a test
Once Qat is installed and setup is completed, navigate to the folder where you want to store your tests. From there, open a command prompt and run:
```bash
qat-create-suite
```
That will generate all the files to run a demo BDD test.
If you prefer using a pure Python test, run:
```bash
qat-create-suite script
```
Then you need to register the application you want to test. The easiest way is to use the Qat GUI, but you can also use the [Python API](https://qat.readthedocs.io/en/1.4.0/doc/Python%20API%20reference.html).
In the current test folder, run the following command:
```bash
qat-gui
```
This will open the _Application Manager_ window:
Enter an application name in the _Name_ field, then the application path and arguments in the fields below.
> Note: When using PySide or PyQt, enter the path to the main script of the application.
Click on the _Save_ button to register the application.
Now you can close the window and launch VSCode:
```bash
code .
```
### Running a test
The Python demo can be run like any other script: open _demo.py_ in VSCode then click on _Run Python file_. For real tests, it is recommended to use a test framework such as __Pytest__ or __Unittest__.
The BDD demo can be launched from the _Test Explorer_:
In both cases, the demo will verify that an application has been registered (see previous steps), start it and verify that the main window is opened. An XML report will also be generated.
When the demo is successful, it confirms that Qat is properly working on your machine. Otherwise, please refer to the test itself for indications on how to solve the issue.
### Configuring test execution
Test settings are available in _testSettings.py_.
The easiest way to change these values is to add a _testSettings.json_ file to the root of your test suite.
This file can contain the following parameters:
```json
{
"waitForObjectTimeout": 3000,
"waitForAppStartTimeout": 60000,
"waitForAppStopTimeout": 30000,
"waitForAppAttachTimeout": 3000,
"longOperationTimeout": 10000,
"screenshotOnFail": true,
"continueAfterFail": false,
"lockUI": "auto"
}
```
If a key is missing, the default value will be used.
During execution, values are available in the _Settings_ class.
If you need to access those values from a script, you can add the following import to your script:
```python
from qat import Settings
# Increase timeout value when finding objects
Settings.wait_for_object_timeout = 5000
```
All timeouts are in milliseconds.
__screenshotOnFail__ determines whether a screenshot of the application is taken and added to the report after each failure. Default is __True__.
__continueAfterFail__ determines whether the test execution should continue after a step has failed (BDD only). Default is __False__
__lockUI__ determines when Qat will lock the application's interface so that it ignores user inputs. Can be one of "always", "never" or "auto" (default, application will not be locked when debugging a test script).
Locking the UI allows users to continue working when a test is running, without affecting the test execution.
For more details on API functions please refer to the [Python API reference](https://qat.readthedocs.io/en/1.4.0/doc/Python%20API%20reference.html).
You can also explore the [tutorials](https://qat.readthedocs.io/en/1.4.0/doc/Tutorials.html).
## Support
You can report any bug, question or feature request by creating a Gitlab issue from [this page](https://gitlab.com/testing-tool/qat/-/issues).
For details, see [the issues workflow](https://qat.readthedocs.io/en/1.4.0/doc/contributing/Issues_Workflow.html).
## Contributing
Contributions are welcome and accepted through Merge Requests.
Please refer to [Contributing](https://qat.readthedocs.io/en/1.4.0/doc/Contributing.html) for detailed instructions.
## Authors and acknowledgment
The complete list of authors and contributors is available [here](doc/AUTHORS.md).
Qat is built on Gitlab using [Docker images](https://bugfreeblog.duckdns.org/docker-qt-tags) provided by [Luca Carlon](https://bugfreeblog.duckdns.org/about-me)
## License
Qat is licensed under the [MIT License](https://opensource.org/license/mit/).
Qat contains a copy of Niels Lohmann's [json library](https://github.com/nlohmann/json) which is licensed under the [MIT License](https://opensource.org/license/mit/).
Qat uses components from the [Qt framework](https://www.qt.io/) which is licensed under the [LGPLv3 License](https://www.gnu.org/licenses/lgpl-3.0.html).
Please note that Qat does not distribute any Qt binary: it uses DLL injection to dynamically link to the Qt binaries used by the target application.
The User Interface of Qat uses [_CustomTkinter_](https://customtkinter.tomschimansky.com/) and [_tkinter-tooltip_](https://github.com/gnikit/tkinter-tooltip) both under the [MIT License](https://opensource.org/license/mit/).
Raw data
{
"_id": null,
"home_page": null,
"name": "qat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Quentin Derouault <qat.authors@gmail.com>",
"keywords": "BDD, Behaviour Driven Development, PyQt, PySide, qt, test, testing",
"author": null,
"author_email": "Quentin Derouault <qat.authors@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/45/72/bc34e251ea8aef8533fbfd99f03750554a03c61fd038e5447a54b570bc82/qat-1.4.0.tar.gz",
"platform": null,
"description": "\n# Qat (Qt Application Tester)\n\n## Description\nQat is a testing framework for Qt-based applications.\n\nQat provides a Python API to interact with any existing Qt application by accessing QML/QtQuick/QWidget elements and simulating user manipulations.\n\nIt is also integrated to [behave](https://github.com/behave/behave) to support Behavior-Driven Development (BDD) with the [Gherkin language](https://cucumber.io/docs/gherkin/).\n\nAlthough Qat uses the GUI to interact with the tested application, it is oriented towards BDD and functional testing rather than UI or non-regression testing.\n\nThe main objective of Qat is to provide quick feedback to developers and easy integration to build systems.\n\n## Requirements\nQat requires Python >= 3.9.\n\nQat supports C++ applications as well as Python bindings such as PySide and PyQt.\n\nTested applications don't need to be modified but they must be compiled in release mode with a compatible compiler and a dynamically-linked Qt version:\n\n| Qt | Linux (gcc) | Windows (MSVC) | Mac OS (Arm & Intel) |\n|----|-------------|----------------|----------------------|\n| __5.15 (LTS)__ | __yes__ | __yes__ | __yes<sup>1</sup>__ |\n| __6.0__ | _no_ | _no_ | _no_ |\n| __6.1__ | _no_ | _no_ | _no_ |\n| __6.2 (LTS)__ | __yes__ | __yes__ | __yes__ |\n| __6.3__ | __yes__ | __yes__ | __yes__ |\n| __6.4__ | __yes__ | __yes__ | __yes__ |\n| __6.5 (LTS)__ | __yes__ | __yes__ | __yes__ |\n| __6.6__ | __yes__ | __yes__ | __yes__ |\n| __6.7__ | __yes__ | __yes__ | __yes__ |\n| __6.8 (LTS)__ | __yes__ | __yes__ | __yes__ |\n\n---\n<sup>1</sup> Qt 5 requires [Rosetta](https://support.apple.com/en-ca/102527) to run on Silicon machines\n\n## Installation\n\nQat can be installed with Pip:\n```bash\npip install qat\n```\nThis will also install the following dependencies:\n- behave (for BDD testing)\n- customtkinter and pillow (for GUI)\n- tkinter-tooltip (for GUI)\n- xmlschema (for test report)\n\n### Tkinter\n\nIf [`tkinter`](https://docs.python.org/3/library/tkinter.html) did not come pre-packaged with your python installation, you may need to install it manually.\n\n#### Arch / Manjaro / Other derivatives\n\nTo install [`tkinter`](https://archlinux.org/packages/extra/x86_64/tk/), run the following command as root:\n\n```bash\npacman -S tk\n```\n\n#### Debian / Other derivatives\n\nTo install [`tkinter`](https://packages.debian.org/bookworm/python3-tk/), run the following command as root:\n\n```bash\napt-get install python3-tk \n```\n\n#### Fedora\n\nTo install [`tkinter`](https://pkgs.org/download/python3-tkinter/), run the following command as root:\n\n```bash\ndnf install python3-tkinter\n```\n\n#### MacOS\n\nTo install [`tkinter`](https://formulae.brew.sh/formula/python-tk@3.12), run the following command as root:\n\n```bash\nbrew install python-tk\n```\n\n## Setup\n\nThe recommended approach is to install [VSCode](https://code.visualstudio.com/download) with the following extensions:\n- Python\n- Pylance\n- Test Explorer UI\n- Behave VSC (for BDD)\n\nAny Python (+ Gherkin) environment can be used (PyCharm, Eclipse/Pydev, VSCode, ...) but the present documentation will use VSCode as a tutorial.\n\n## Usage\n\n### Creating a test\nOnce Qat is installed and setup is completed, navigate to the folder where you want to store your tests. From there, open a command prompt and run:\n```bash\nqat-create-suite\n```\n\nThat will generate all the files to run a demo BDD test.\n\nIf you prefer using a pure Python test, run:\n```bash\nqat-create-suite script\n```\n\nThen you need to register the application you want to test. The easiest way is to use the Qat GUI, but you can also use the [Python API](https://qat.readthedocs.io/en/1.4.0/doc/Python%20API%20reference.html).\nIn the current test folder, run the following command:\n```bash\nqat-gui\n```\n\nThis will open the _Application Manager_ window:\n\n\nEnter an application name in the _Name_ field, then the application path and arguments in the fields below.\n> Note: When using PySide or PyQt, enter the path to the main script of the application.\n\n\n\nClick on the _Save_ button to register the application.\n\n\nNow you can close the window and launch VSCode:\n```bash\ncode .\n```\n\n### Running a test\n\nThe Python demo can be run like any other script: open _demo.py_ in VSCode then click on _Run Python file_. For real tests, it is recommended to use a test framework such as __Pytest__ or __Unittest__.\n\nThe BDD demo can be launched from the _Test Explorer_:\n![\"VSCode BDD demo\"](https://qat.readthedocs.io/en/1.4.0/_images/vscode_demo.png \"VSCode BDD demo\")\n\nIn both cases, the demo will verify that an application has been registered (see previous steps), start it and verify that the main window is opened. An XML report will also be generated.\n\nWhen the demo is successful, it confirms that Qat is properly working on your machine. Otherwise, please refer to the test itself for indications on how to solve the issue.\n\n\n### Configuring test execution\nTest settings are available in _testSettings.py_.\nThe easiest way to change these values is to add a _testSettings.json_ file to the root of your test suite.\n\nThis file can contain the following parameters:\n```json\n{\n \"waitForObjectTimeout\": 3000,\n \"waitForAppStartTimeout\": 60000,\n \"waitForAppStopTimeout\": 30000,\n \"waitForAppAttachTimeout\": 3000,\n \"longOperationTimeout\": 10000,\n \"screenshotOnFail\": true,\n \"continueAfterFail\": false,\n \"lockUI\": \"auto\"\n}\n```\nIf a key is missing, the default value will be used.\nDuring execution, values are available in the _Settings_ class.\n\nIf you need to access those values from a script, you can add the following import to your script:\n\n```python\nfrom qat import Settings\n\n# Increase timeout value when finding objects\nSettings.wait_for_object_timeout = 5000\n```\n\nAll timeouts are in milliseconds.\n\n__screenshotOnFail__ determines whether a screenshot of the application is taken and added to the report after each failure. Default is __True__.\n\n__continueAfterFail__ determines whether the test execution should continue after a step has failed (BDD only). Default is __False__\n\n__lockUI__ determines when Qat will lock the application's interface so that it ignores user inputs. Can be one of \"always\", \"never\" or \"auto\" (default, application will not be locked when debugging a test script).\nLocking the UI allows users to continue working when a test is running, without affecting the test execution.\n\nFor more details on API functions please refer to the [Python API reference](https://qat.readthedocs.io/en/1.4.0/doc/Python%20API%20reference.html).\n\nYou can also explore the [tutorials](https://qat.readthedocs.io/en/1.4.0/doc/Tutorials.html).\n\n## Support\nYou can report any bug, question or feature request by creating a Gitlab issue from [this page](https://gitlab.com/testing-tool/qat/-/issues).\n\nFor details, see [the issues workflow](https://qat.readthedocs.io/en/1.4.0/doc/contributing/Issues_Workflow.html).\n\n## Contributing\nContributions are welcome and accepted through Merge Requests.\nPlease refer to [Contributing](https://qat.readthedocs.io/en/1.4.0/doc/Contributing.html) for detailed instructions.\n\n## Authors and acknowledgment\nThe complete list of authors and contributors is available [here](doc/AUTHORS.md).\n\nQat is built on Gitlab using [Docker images](https://bugfreeblog.duckdns.org/docker-qt-tags) provided by [Luca Carlon](https://bugfreeblog.duckdns.org/about-me)\n\n## License\nQat is licensed under the [MIT License](https://opensource.org/license/mit/).\n\nQat contains a copy of Niels Lohmann's [json library](https://github.com/nlohmann/json) which is licensed under the [MIT License](https://opensource.org/license/mit/).\n\nQat uses components from the [Qt framework](https://www.qt.io/) which is licensed under the [LGPLv3 License](https://www.gnu.org/licenses/lgpl-3.0.html).\nPlease note that Qat does not distribute any Qt binary: it uses DLL injection to dynamically link to the Qt binaries used by the target application.\n\nThe User Interface of Qat uses [_CustomTkinter_](https://customtkinter.tomschimansky.com/) and [_tkinter-tooltip_](https://github.com/gnikit/tkinter-tooltip) both under the [MIT License](https://opensource.org/license/mit/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Qt Application Tester, a BDD-oriented framework to test Qt-based applications",
"version": "1.4.0",
"project_urls": {
"Changelog": "https://qat.readthedocs.io/en/stable/CHANGELOG.html",
"Documentation": "https://qat.readthedocs.io/en/stable/",
"Homepage": "https://gitlab.com/testing-tool/qat",
"Issues": "https://gitlab.com/testing-tool/qat/-/issues",
"Repository": "https://gitlab.com/testing-tool/qat.git"
},
"split_keywords": [
"bdd",
" behaviour driven development",
" pyqt",
" pyside",
" qt",
" test",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c55e17eb3424775afdcea565b88ec3ac61a6684d22d220c1b39253a67f46be4",
"md5": "3cb5f345f1c3d794f783b6d42e7b3a42",
"sha256": "4020062ca833cf1634ab2f13992b4dbcc666a46a9e49ab785f21e23e0a6da67a"
},
"downloads": -1,
"filename": "qat-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3cb5f345f1c3d794f783b6d42e7b3a42",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13853626,
"upload_time": "2024-12-07T16:55:25",
"upload_time_iso_8601": "2024-12-07T16:55:25.956600Z",
"url": "https://files.pythonhosted.org/packages/4c/55/e17eb3424775afdcea565b88ec3ac61a6684d22d220c1b39253a67f46be4/qat-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4572bc34e251ea8aef8533fbfd99f03750554a03c61fd038e5447a54b570bc82",
"md5": "55f436939f97d5c98fe3595fb3112557",
"sha256": "45fdade0fa265a7e8f0aedc3fa07f76540a2da93fca4b75a1fa9bfb88bf53999"
},
"downloads": -1,
"filename": "qat-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "55f436939f97d5c98fe3595fb3112557",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13757879,
"upload_time": "2024-12-07T16:55:28",
"upload_time_iso_8601": "2024-12-07T16:55:28.328662Z",
"url": "https://files.pythonhosted.org/packages/45/72/bc34e251ea8aef8533fbfd99f03750554a03c61fd038e5447a54b570bc82/qat-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-07 16:55:28",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "testing-tool",
"gitlab_project": "qat",
"lcname": "qat"
}
JSON