pyseext 0.1.0__tar.gz

pyseext-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Martyn West
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyseext-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE

pyseext-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: pyseext
+Version: 0.1.0
+Summary: A short description
+Home-page: https://github.com/westy/pyseext
+Author: Martyn West
+Author-email: 657393+westy@users.noreply.github.com
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: selenium
+Dynamic: author
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license-file
+
+# PySeExt Module Repository
+
+This project contains a package to aid the testing of ExtJS applications from Python using Selenium.
+
+---
+## Naming Standards
+
+Full details [here](https://namingconvention.org/python/).
+
+### TL;DR
+**Type** | **Public** | **Internal**
+--- | --- | ---
+Packages | `lower_with_under` |
+Modules | `lower_with_under` | `_lower_with_under`
+Classes | `CapWords` | `_CapWords`
+Exceptions | `CapWords` |
+Functions | `lower_with_under()` | `_lower_with_under()`
+Global/Class Constants | `CAPS_WITH_UNDER` | `_CAPS_WITH_UNDER`
+Global/Class Variables | `lower_with_under` | `_lower_with_under`
+Instance Variables | `lower_with_under` | `_lower_with_under`
+Method Names | `lower_with_under()` | `_lower_with_under()`
+Function/Method Parameters | `lower_with_under` |
+Local Variables | `lower_with_under` |
+
+### Additional Notes
+I have also settled on a standard of having a single class per source file (that I now understand are called modules), although inner classes are allowed.
+This is pretty much standard practice in other languages, and makes source control and managing conflicts far easier.

pyseext-0.1.0/README.md

@@ -0,0 +1,27 @@
+# PySeExt Module Repository
+
+This project contains a package to aid the testing of ExtJS applications from Python using Selenium.
+
+---
+## Naming Standards
+
+Full details [here](https://namingconvention.org/python/).
+
+### TL;DR
+**Type** | **Public** | **Internal**
+--- | --- | ---
+Packages | `lower_with_under` |
+Modules | `lower_with_under` | `_lower_with_under`
+Classes | `CapWords` | `_CapWords`
+Exceptions | `CapWords` |
+Functions | `lower_with_under()` | `_lower_with_under()`
+Global/Class Constants | `CAPS_WITH_UNDER` | `_CAPS_WITH_UNDER`
+Global/Class Variables | `lower_with_under` | `_lower_with_under`
+Instance Variables | `lower_with_under` | `_lower_with_under`
+Method Names | `lower_with_under()` | `_lower_with_under()`
+Function/Method Parameters | `lower_with_under` |
+Local Variables | `lower_with_under` |
+
+### Additional Notes
+I have also settled on a standard of having a single class per source file (that I now understand are called modules), although inner classes are allowed.
+This is pretty much standard practice in other languages, and makes source control and managing conflicts far easier.

pyseext-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyseext"
+version = "0.1.0"
+description = "A short description"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "selenium",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyseext-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyseext-0.1.0/setup.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+# Learn more: https://github.com/kennethreitz/setup.py
+
+from setuptools import setup, find_packages
+
+
+with open('README.md', encoding = 'utf-8') as f:
+    readme = f.read()
+
+with open('LICENSE', encoding = 'utf-8') as f:
+    license_text = f.read()
+
+setup(
+    name='pyseext',
+    version='1.4.1',
+    description='Python Selenium ExtJS - package for helping interact with an ExtJS application from Python using Selenium',
+    long_description=readme,
+    author='Martyn West',
+    author_email='657393+westy@users.noreply.github.com',
+    url='https://github.com/westy/pyseext',
+    license=license_text,
+    packages=find_packages(exclude=('tests', 'docs')),
+    package_data={'pyseext': ['js/*.js']}
+)

pyseext-0.1.0/src/pseext/__init__.py

@@ -0,0 +1,9 @@
+"""
+A package to aid the testing of ExtJS applications from Python using Selenium.
+
+See: https://github.com/westy/pyseext
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("Imported package '%s' from %s",__name__, __path__)

pyseext-0.1.0/src/pseext/button_helper.py

@@ -0,0 +1,115 @@
+"""
+Module that contains our ButtonHelper class.
+"""
+
+import logging
+from typing import Union
+
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from pyseext.component_query import ComponentQuery
+
+class ButtonHelper:
+    """A class to help with interacting with Ext buttons"""
+
+    # Class variables
+    _ENABLED_BUTTON_TEMPLATE: str = 'button[text="{text}"][disabled=false]'
+    """The component query template to use to find an enabled button.
+    Requires the inserts: {text}"""
+
+    _DISABLED_BUTTON_TEMPLATE: str = 'button[text="{text}"][disabled=true]'
+    """The component query template to use to find a disabled button.
+    Requires the inserts: {text}"""
+
+    _MESSAGEBOX_BUTTON_TEMPLATE: str = 'messagebox{{isVisible(true)}} button[text="{text}"]'
+    """The component query template to use to find a button on a visible message box.
+    Requires the inserts: {text}"""
+
+    def __init__(self, driver: WebDriver):
+        """Initialises an instance of this class
+
+        Args:
+            driver (WebDriver): The webdriver to use
+        """
+        # Instance variables
+        self._logger = logging.getLogger(__name__)
+        """The Logger instance for this class instance"""
+
+        self._cq = ComponentQuery(driver)
+        """The `ComponentQuery` instance for this class instance"""
+
+        self._action_chains = ActionChains(driver)
+        """The ActionChains instance for this class instance"""
+
+    def click_button(self, cq: str, root_id: Union[str, None] = None):
+        """Finds a button using the supplied component query and clicks it.
+
+        Args:
+            cq (str): The component query to find the button.
+            root_id (str, optional): The id of the container within which to perform the query.
+                If omitted, all components within the document are included in the search.
+        """
+        button = self._cq.wait_for_single_query_visible(cq, root_id)
+
+        # Rather than call click, move mouse to button and click...
+        self._logger.info("Clicking button with CQ '%s'", cq)
+
+        self._action_chains.move_to_element(button)
+        self._action_chains.click()
+        self._action_chains.perform()
+
+    def click_button_by_text(self, text: str, root_id: Union[str, None] = None):
+        """Finds a visible, enabled button with the specified text and clicks it.
+
+        Args:
+            text (str): The text on the button
+            root_id (str, optional): The id of the container within which to perform the query.
+                If omitted, all components within the document are included in the search.
+        """
+        self.click_button(self._ENABLED_BUTTON_TEMPLATE.format(text=text), root_id)
+
+    def check_button_enabled(self, text: str, root_id: Union[str, None] = None):
+        """Checks that we can find an enabled button with the specified text.
+
+        Args:
+            text (str): The text on the button
+            root_id (str, optional): The id of the container within which to perform the query.
+                If omitted, all components within the document are included in the search.
+        """
+        self._cq.wait_for_single_query(self._ENABLED_BUTTON_TEMPLATE.format(text=text), root_id)
+
+    def check_button_disabled(self, text: str, root_id: Union[str, None] = None):
+        """Checks that we can find a disabled button with the specified text.
+
+        Args:
+            text (str): The text on the button
+            root_id (str, optional): The id of the container within which to perform the query.
+                If omitted, all components within the document are included in the search.
+        """
+        self._cq.wait_for_single_query(self._DISABLED_BUTTON_TEMPLATE.format(text=text), root_id)
+
+    def click_button_on_messagebox(self, text: str = 'OK'):
+        """Clicks a button on a messagebox.
+
+        The messagebox must be visible.
+
+        Args:
+            text (str, optional): The text of the button to click. Defaults to 'OK'.
+        """
+        self.click_button(self._MESSAGEBOX_BUTTON_TEMPLATE.format(text=text))
+
+    def click_button_arrow(self, button_text: str, root_id: Union[str, None] = None, css_selector: str = ".x-btn-arrow-el"):
+        """Clicks the dropdown arrow of a split button to open its menu.
+        
+        Args:
+            button_text (str): The text on the button
+            root_id (str, optional): The id of the container within which to perform the query.
+            css_selector (str, optional): The CSS selector to find the arrow element within the button. Defaults to ".x-btn-arrow-el".
+        """
+        arrow = self._cq.wait_for_single_query_visible(cq = button_text, root_id = root_id, css_selector = css_selector)
+
+        # Move to the button and click on the arrow area
+        self._action_chains.move_to_element(arrow)
+        self._action_chains.click()
+        self._action_chains.perform()

pyseext-0.1.0/src/pseext/component_query.py

@@ -0,0 +1,259 @@
+"""
+Module that contains our ComponentQuery class.
+"""
+import logging
+from typing import Union
+
+from selenium.common.exceptions import TimeoutException
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support.wait import WebDriverWait
+
+from pyseext.has_referenced_javascript import HasReferencedJavaScript
+
+
+class ComponentQuery(HasReferencedJavaScript):
+    """A class to help with using Ext.ComponentQuery"""
+
+    # Class variables
+    _QUERY_TEMPLATE: str = "return globalThis.PySeExt.ComponentQuery.query('{cq}')"
+    """The script template to use to execute a component query.
+    Requires the inserts: {cq}"""
+
+    _QUERY_TEMPLATE_WITH_ROOT: str = "return globalThis.PySeExt.ComponentQuery.query('{cq}', '{root_id}')"
+    """The script template to use to execute a component query under a specified root.
+    Requires the inserts: {cq}, {root_id}"""
+
+    _QUERY_TEMPLATE_WITH_CSS_SELECTOR: str = "return globalThis.PySeExt.ComponentQuery.query('{cq}', undefined, '{css_selector}')"
+    """The script template to use to execute a component query, and then execute a CSS selector query against each matched element.
+    Requires the inserts: {cq}, {css_selector}"""
+
+    _QUERY_TEMPLATE_WITH_ROOT_AND_CSS_SELECTOR: str = "return globalThis.PySeExt.ComponentQuery.query('{cq}', '{root_id}', '{css_selector}')"
+    """The script template to use to execute a component query under a specified root, and then execute a CSS selector query against each matched element.
+    Requires the inserts: {cq}, {root_id}, {css_selector}"""
+
+    _IS_COMPONENT_INSTANCE_OF_CLASS_TEMPLATE: str = "return globalThis.PySeExt.ComponentQuery.isComponentInstanceOf('{class_name}', '{cq}')"
+    """The script template to use to determine whether a component query matches a component of the specified class.
+    Requires the inserts: {class_name}, {cq}"""
+
+    _IS_COMPONENT_INSTANCE_OF_CLASS_TEMPLATE_WITH_ROOT: str = "return globalThis.PySeExt.ComponentQuery.isComponentInstanceOf('{class_name}', '{cq}', '{root_id}')"
+    """The script template to use to determine whether a component query matches a component of the specified class.
+    Requires the inserts: {class_name}, {cq}, {root_id}"""
+
+    def __init__(self, driver: WebDriver):
+        """Initialises an instance of this class
+
+        Args:
+            driver (WebDriver): The webdriver to use
+        """
+        # Instance variables
+        self._logger = logging.getLogger(__name__)
+        """The logger instance for this class instance"""
+
+        self._driver = driver
+        """The WebDriver instance for this class instance"""
+
+        # Initialise our base class
+        super().__init__(driver, self._logger)
+
+    def query(self, cq: str, root_id: Union[str, None] = None, css_selector: Union[str, None] = None) -> list[WebElement]:
+        """Executes a ComponentQuery and returns the result
+
+        Args:
+            cq (str): The query to execute
+            root_id (str, optional): The id of the container within which to perform the query.
+                                     If omitted, all components within the document are included in the search.
+            css_selector (str, optional): An optional CSS selector that can be used to get child elements of a found component,
+                                          e.g. a clear trigger on a field would be '.x-form-clear-trigger'.
+        Returns:
+            list[WebElement]: An array of DOM elements that match the query or an empty array if not found
+        """
+        if root_id is None and css_selector is None:
+            self._logger.debug("Executing CQ '%s'", cq)
+            script = self._QUERY_TEMPLATE.format(cq=cq)
+        elif css_selector is None:
+            self._logger.debug("Executing CQ '%s' under root '%s'", cq, root_id)
+            script = self._QUERY_TEMPLATE_WITH_ROOT.format(cq=cq, root_id=root_id)
+        elif root_id is None:
+            self._logger.debug("Executing CQ '%s' with CSS selector '%s'", cq, css_selector)
+            script = self._QUERY_TEMPLATE_WITH_CSS_SELECTOR.format(cq=cq, css_selector=css_selector)
+        else:
+            self._logger.debug("Executing CQ '%s' under root '%s' with CSS selector '%s'", cq, root_id, css_selector)
+            script = self._QUERY_TEMPLATE_WITH_ROOT_AND_CSS_SELECTOR.format(cq=cq, root_id=root_id, css_selector=css_selector)
+
+        self.ensure_javascript_loaded()
+        query_result = self._driver.execute_script(script)
+
+        self._logger.debug("CQ '%s' gave results: %s", cq, query_result)
+
+        return query_result
+
+    def wait_for_query(self, cq: str, root_id: Union[str, None] = None, timeout: float = 10, throw_if_not_found: bool = True, css_selector: Union[str, None] = None) -> list[WebElement]:
+        """Method that waits for the specified CQ to match something
+
+        Args:
+            cq (str): The query to execute
+            root_id (str, optional): The id of the container within which to perform the query.
+                                     If omitted, all components within the document are included in the search.
+            timeout (float): Number of seconds before timing out (default 10)
+            throw_if_not_found (bool): Indicates whether to throw an exception if not found (default True).
+            css_selector (str, optional): An optional CSS selector that can be used to get child elements of a found component,
+                                          e.g. a clear trigger on a field would be '.x-form-clear-trigger'.
+
+        Returns:
+            list[WebElement]: An array of DOM elements that match the query or an empty array if not found (and not configured to throw)
+        """
+        try:
+            WebDriverWait(self._driver, timeout).until(ComponentQuery.ComponentQueryFoundExpectation(cq))
+            return self.query(cq, root_id, css_selector)
+        except TimeoutException as exc:
+            if throw_if_not_found:
+                raise ComponentQuery.QueryNotFoundException(cq, timeout, root_id) from exc
+
+            return []
+
+    def wait_for_single_query(self, cq: str, root_id: Union[str, None] = None, timeout: float = 10, css_selector: Union[str, None] = None) -> WebElement:
+        """Method that waits for the specified CQ to match a single result.
+        If there are multiple matches then an error is thrown.
+
+        Args:
+            cq (str): The query to execute
+            root_id (str, optional): The id of the container within which to perform the query.
+                                     If omitted, all components within the document are included in the search.
+            timeout (float): Number of seconds before timing out (default 10)
+            css_selector (str, optional): An optional CSS selector that can be used to get child elements of a found component,
+                                          e.g. a clear trigger on a field would be '.x-form-clear-trigger'.
+
+        Returns:
+            WebElement: The DOM element that matches the query
+        """
+        results = self.wait_for_query(cq, root_id, timeout, True, css_selector)
+        if len(results) > 1:
+            raise ComponentQuery.QueryMatchedMultipleElementsException(cq, len(results))
+
+        return results[0]
+
+    def wait_for_single_query_visible(self, cq: str, root_id: Union[str, None] = None, timeout: float = 10, css_selector: Union[str, None] = None) -> WebElement:
+        """Method that waits for the specified CQ to match a single visible result.
+        If there are multiple matches then an error is thrown.
+
+        Args:
+            cq (str): The query to execute
+            root_id (str, optional): The id of the container within which to perform the query.
+                                     If omitted, all components within the document are included in the search.
+            timeout (float): Number of seconds before timing out (default 10)
+            css_selector (str, optional): An optional CSS selector that can be used to get child elements of a found component,
+                                          e.g. a clear trigger on a field would be '.x-form-clear-trigger'.
+
+        Returns:
+            WebElement: The DOM element that matches the query
+        """
+        if not cq.endswith('{isVisible(true)}'):
+            cq = cq + '{isVisible(true)}'
+
+        return self.wait_for_single_query(cq, root_id, timeout, css_selector)
+
+    def is_component_instance_of_class(self, class_name: str, cq: str, root_id: Union[str, None] = None, timeout: float = 1) -> bool:
+        """Determines whether the component for the specified CQ is an instance of the specified class name.
+
+        Note, will return True if the component is a subclass of the type too.
+
+        If the component is not found then an error is thrown.
+
+        Args:
+            class_name (str): The class name to test for, e.g. 'Ext.container.Container'.
+            cq (str): The query to find the component.
+            root_id (str, optional): The id of the container within which to perform the query.
+                                     If omitted, all components within the document are included in the search.
+            timeout (float): Number of seconds before timing out (default 1)
+
+        Returns:
+            bool: True if the component is an instance of the specified class (including a subclass). False otherwise.
+        """
+        if root_id is None:
+            script = self._IS_COMPONENT_INSTANCE_OF_CLASS_TEMPLATE.format(class_name=class_name, cq=cq)
+        else:
+            script = self._IS_COMPONENT_INSTANCE_OF_CLASS_TEMPLATE_WITH_ROOT.format(class_name=class_name, cq=cq, root_id=root_id)
+
+        self.ensure_javascript_loaded()
+        result = self._driver.execute_script(script)
+
+        if result is None:
+            raise ComponentQuery.QueryNotFoundException(cq, timeout, root_id)
+
+        return result
+
+    class ComponentQueryFoundExpectation:
+        """ An expectation for checking that an Ext.ComponentQuery is found"""
+
+        def __init__(self, cq: str):
+            """Initialises an instance of this class.
+            """
+            self._cq = cq
+
+        def __call__(self, driver):
+            """Method that determines whether a CQ is found
+            """
+            results = ComponentQuery(driver).query(self._cq)
+            return results is not None and len(results) > 0
+
+    class QueryMatchedMultipleElementsException(Exception):
+        """Exception class thrown when expecting a single component query match and get multiple"""
+
+        def __init__(self, cq: str, count: int, message: str = "Expected a single match from ComponentQuery '{cq}' but got {count}."):
+            """Initialises an instance of this exception
+
+            Args:
+                cq (str): The component query that has been executed
+                timeout (float): Number of seconds before timing out
+                count (int): The number of results that we got
+                message (str, optional): The message for the exception. Must contain a 'cq' and 'count' format inserts.
+                                         Defaults to "Expected a single match from ComponentQuery '{cq}' but got '{count}'".
+            """
+            self.message = message
+            self._cq = cq
+            self._count = count
+
+            super().__init__(self.message)
+
+        def __str__(self):
+            """Returns a string representation of this exception"""
+            return self.message.format(cq=self._cq, count=self._count)
+
+    class QueryNotFoundException(Exception):
+        """Exception class thrown when a component query could not be found"""
+
+        def __init__(self,
+                     cq: str,
+                     timeout: float,
+                     root_id: Union[str, None] = None,
+                     message_without_root: str = "Waiting for component query '{cq}' timed out after {timeout} seconds",
+                     message_with_root: str = "Waiting for component query '{cq}' under root '{root_id}' timed out after {timeout} seconds"):
+            """Initialises an instance of this exception
+
+            Args:
+                cq (str): The component query that has been executed
+                timeout (float): Number of seconds waited
+                root_id (str, optional): The id of the container within which the query was performed.
+                message_without_root (str, optional): The message for the exception when there is no root. Must contain a 'cq' and 'timeout' format inserts.
+                                                      Defaults to "Waiting for component query '{cq}' timed out after {timeout} seconds".
+                message_with_root (str, optional): The message for the exception when there is a root. Must contain a 'cq', 'root_id' and 'timeout' format inserts.
+                                                   Defaults to "Waiting for component query '{cq}' under root '{root_id}' timed out after {timeout} seconds".
+            """
+            self._cq = cq
+            self._timeout = timeout
+            self._root_id = root_id
+
+            if root_id is None:
+                self.message = message_without_root
+            else:
+                self.message = message_with_root
+
+            super().__init__(self.message)
+
+        def __str__(self):
+            """Returns a string representation of this exception"""
+            if self._root_id is None:
+                return self.message.format(cq=self._cq, timeout=self._timeout)
+            else:
+                return self.message.format(cq=self._cq, timeout=self._timeout, root_id=self._root_id)