Squape Report (#3)

Adakar · pawtom · web-flow · commit 7043378370a3 · 2023-04-16T15:53:16.000+02:00
* Add squape-report package

The package containing reporting utilities for Squish GUI Tester

- vps module with vph_property() that highlights the given object and checks its property
- logging functions that support different log levels
- new debug log message sub-type
- sections as context managers

---------

Co-authored-by: Tomasz Pawlowski &lt;tomasz.pawlowski@gmail.com&gt;
diff --git 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
@@ -2,20 +2,26 @@
 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/)  
 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
@@ -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.
diff --git a/squape-report/README.md 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
@@ -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"
diff --git a/squape-report/squape/report.py 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
@@ -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
