diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 738465b..41cb119 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,4 +1,4 @@ -default_languages_version: +default_language_version: python: python3.8 repos: - repo: https://github.com/pre-commit/pre-commit-hooks @@ -11,9 +11,13 @@ repos: - id: fix-encoding-pragma - repo: https://github.com/asottile/reorder_python_imports - rev: v3.8.1 + rev: v3.9.0 hooks: - id: reorder-python-imports + args: [ + --unclassifiable-application-module, squish, + --unclassifiable-application-module, test, + ] - repo: https://github.com/psf/black rev: 22.6.0 diff --git a/README.md b/README.md index 165a508..9e7d925 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,16 @@ Python package that extends Squish Python API. It provides tools for everyday automated test cases development. ### Requirements -To enjoy all the features of the SQUAPE package, you have to use it with Squish version X.X.X or newer. +To enjoy all the features of the SQUAPE package, you have to use it with Squish version 6.7.0 or newer. ### Installation -TBD +The packages are available on the Python Package Index (PyPI). +- The `squape-report` package includes methods that enrich Squish reporting and verifying capabilities -### Documentation -TBD +You can install them via `pip` with the following commands: +```sh +pip install squape-report +``` ## Contribution The package is created and maintained by [Cyber Alpaca](https://cyberalpaca.com/) @@ -16,6 +19,9 @@ Pull requests for any issues are welcome. In case where you would like to introduce a new feature or a major change, please open an issue first and discuss it with our team. ## License -The packages are available under the BSD license +The packages are available under The 3-Clause BSD License + +## References +- [Squish by the Qt Group](https://www.qt.io/product/quality-assurance/squish) [![Cyber Alpaca](https://cyberalpaca.com/static/media/cyberalpaca-logo.60f51a65.svg)](https://cyberalpaca.com) diff --git a/squape-report/LICENSE b/squape-report/LICENSE new file mode 100644 index 0000000..06486e3 --- /dev/null +++ b/squape-report/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2023, Cyber Alpaca Pawłowski Topolski sp.j. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/squape-report/README.md b/squape-report/README.md new file mode 100644 index 0000000..ea4ec83 --- /dev/null +++ b/squape-report/README.md @@ -0,0 +1,16 @@ +# SQUAPE - Report +Python package with features that enrich Squish reporting and verifying capabilities + +### Installation +```sh +pip install squape-report +``` + +## License +The packages are available under The 3-Clause BSD License + +## References +- [SQUAPE - Squish API Python Extension](https://github.com/CyberAlpaca/squish-api-python-extension) +- [Squish by the Qt Group](https://www.qt.io/product/quality-assurance/squish) + +[![Cyber Alpaca](https://cyberalpaca.com/static/media/cyberalpaca-logo.60f51a65.svg)](https://cyberalpaca.com) diff --git a/squape-report/pyproject.toml b/squape-report/pyproject.toml new file mode 100644 index 0000000..53a581f --- /dev/null +++ b/squape-report/pyproject.toml @@ -0,0 +1,29 @@ +# squape-report/pyproject.toml + +[build-system] +requires = ["setuptools", "setuptools-scm"] +build-backend = "setuptools.build_meta" + +[tool.setuptools.packages.find] +where = ["."] +include = ["squape"] +namespaces = true + +[project] +name = "squape-report" +version = "0.1.0" +authors = [ + { name="Cyber Alpaca", email="contact@cyberalpaca.com" }, +] +requires-python = ">=3.8" +readme = "README.md" +description = "Reporting Utilities for the Squish GUI Tester" +classifiers = [ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", +] + +[project.urls] +"Homepage" = "https://github.com/CyberAlpaca/squish-api-python-extension" +"Cyber Alpaca" = "https://cyberalpaca.com" \ No newline at end of file diff --git a/squape-report/squape/report.py b/squape-report/squape/report.py new file mode 100644 index 0000000..b27e892 --- /dev/null +++ b/squape-report/squape/report.py @@ -0,0 +1,222 @@ +# -*- coding: utf-8 -*- +# +# Copyright (c) 2023, Cyber Alpaca +# All rights reserved. +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. +from contextlib import contextmanager + +import squish +import test + + +class LogLevel: + DEBUG = 10 + LOG = 20 + WARNING = 30 + FAIL = 40 + FATAL = 50 + + +LOGLEVEL = LogLevel.LOG + + +def __is_level_enabled(level: LogLevel) -> bool: + """Checks the given log level against the currently set LOGLEVEL + + Args: + level (LogLevel): log level to check + + Returns: + bool: True if level is higher then LOGLEVEL, False otherwise + """ + return LOGLEVEL <= level + + +def debug(msg: str, details: str = "") -> None: + """Adds a DEBUG-level log entry with the given message and details to a test report. + + This function adds a log message to Squish's test report at the DEBUG log level, + which allows for detailed debugging information to be recorded. + The log message will include the given message and details provided as arguments. + The message will be prefixed with the string 'DEBUG: ' to indicate its log level. + + The log message will only be visible if the LOGLEVEL is set to DEBUG. + Otherwise, it will be ignored and not included in the test report. + + Args: + - msg (str): The message to include in the log entry. + - details (str): Optional additional details to include in the log entry. + + Returns: + None + """ + if __is_level_enabled(LogLevel.DEBUG): + test.fixateResultContext(1) + try: + test.log(f"[DEBUG] {msg}", details) + finally: + test.restoreResultContext() + + +def log(msg: str, details: str = "") -> None: + """Adds a log entry with the given message and details to a test report. + + This function adds a log message to Squish's test report at the LOG log level + or lower, depending on the current log level setting. + The log message will include the given message and details provided as arguments. + + The log message will only be visible if the LOGLEVEL is set to LOG or lower. + Otherwise, it will be ignored and not included in the test report. + + Args: + - msg (str): The message to include in the log entry. + - details (str): Optional additional details to include in the log entry. + + Returns: + None + """ + if __is_level_enabled(LogLevel.LOG): + test.fixateResultContext(1) + try: + test.log(msg, details) + finally: + test.restoreResultContext() + + +def warning(msg: str, details: str = "") -> None: + """Adds a warning entry with the given message and details to a test report. + + This function adds a warning message to Squish's test report at the WARNING + log level or lower, depending on the current log level setting. + The warning message will include the given message and details provided + as arguments. + + The warning message will only be visible if the LOGLEVEL is set to WARNING or lower. + Otherwise, it will be ignored and not included in the test report. + + Args: + - msg (str): The message to include in the warning entry. + - details (str): Optional additional details to include in the warning entry. + + Returns: + None + """ + if __is_level_enabled(LogLevel.WARNING): + test.fixateResultContext(1) + try: + test.warning(msg, details) + finally: + test.restoreResultContext() + + +def fail(msg: str, details: str = "") -> None: + """Adds a fail entry with the given message and details to a test report. + + This function adds a fail message to Squish's test report at the FAIL log level + or lower, depending on the current log level setting. + The fail message will include the given message and details provided as arguments. + + The fail message will only be visible if the LOGLEVEL is set to FAIL or lower. + Otherwise, it will be ignored and not included in the test report. + + Args: + - msg (str): The message to include in the fail entry. + - details (str): Optional additional details to include in the fail entry. + + Returns: + None + """ + if __is_level_enabled(LogLevel.FAIL): + test.fixateResultContext(1) + try: + test.fail(msg, details) + finally: + test.restoreResultContext() + + +def fatal(msg: str, details: str = "") -> None: + """Adds a fatal entry with the given message and details to a test report, + then aborts the test case execution. + + This function adds a fatal message to Squish's test report at the FATAL log level + or lower, depending on the current log level setting. + The fatal message will include the given message and details provided as arguments. + + The fatal message will only be visible if the LOGLEVEL is set to FATAL or lower. + Otherwise, it will be ignored and not included in the test report. + + After adding the fatal message, the function aborts the test case execution. + + Args: + - msg (str): The message to include in the fatal entry. + - details (str): Optional additional details to include in the fatal entry. + + Returns: + None + """ + if __is_level_enabled(LogLevel.FATAL): + test.fixateResultContext(1) + try: + squish.testSettings.throwOnFailure = True + test.fatal(msg, details) + finally: + test.restoreResultContext() + + +def enable_loglevel_in_test_module(): + """Adds support for log levels to the Squish 'test' module. + + DISCLAIMER: This function uses monkeypathching + https://en.wikipedia.org/wiki/Monkey_patch + + This function overwrites some of the existing functions in the 'test' module + to support logging at different log levels. + Furthermore, it enhances the functionality of the 'test' module by adding + a new test.debug(...) function. + + By default, the 'test' module does not support LOGLEVEL at all. + However, this function adds support for setting the log level to a higher + or lower level, depending on the needs of the developer. + + After calling this function, the following 'test' module's functions will support + LOGLEVEL report setting: + - test.debug(...) + - test.log(...) + - test.warning(...) + - test.fail(...) + - test.fatal(...) + + Returns: + None + """ + test.debug = debug + test.log = log + test.warning = warning + test.fail = fail + test.fatal = fatal + + +@contextmanager +def section(title: str, description: str = "") -> None: + """Allows using Squish's sections as context managers + + https://doc.qt.io/squish/squish-api.html#test-startsection-function + Args: + title (str): Section title + description (str): Optional additional description of the section + Examples: + with section("Add new person"): + squish.type(squish.waitForObject(names.forename_edit), "Bob") + squish.mouseClick(squish.waitForObject(names.ok_button)) + """ + + test.fixateResultContext(1) + test.startSection(title, description) + test.restoreResultContext() + try: + yield + except Exception: + raise + finally: + test.endSection() diff --git a/squape-report/squape/vps.py b/squape-report/squape/vps.py new file mode 100644 index 0000000..c71bd47 --- /dev/null +++ b/squape-report/squape/vps.py @@ -0,0 +1,32 @@ +# -*- coding: utf-8 -*- +# +# Copyright (c) 2023, Cyber Alpaca +# All rights reserved. +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. +import squish +import test + + +def vph_property( + object_name: any, property_name: str, expected_value: any, msg: str +) -> bool: + """ "Highlights the object then verifies its property. + The object remains highlighted during verification to make it easier to identify + on potential screenshots. + + Args: + object_name (any): symbolic name, real name, or object reference + property_name (str): name of the property to verify + expected_value (any): expected value of the verified property + msg (str): verification message + Returns: + bool: True if verification is positive, False otherwise + """ + + obj = squish.waitForObjectExists(object_name) + property_value = getattr(obj, property_name) + squish.highlightObject(obj, 200, False) + result = test.compare(property_value, expected_value, msg) + squish.snooze(0.2) + return result