pomcorn 0.6.0__tar.gz → 0.7.1__tar.gz

pomcorn-0.7.1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.1
+Name: pomcorn
+Version: 0.7.1
+Summary: Base implementation of Page Object Model
+Home-page: https://pypi.org/project/pomcorn/
+License: MIT
+Keywords: python,selenium,webdriver,autotests,page object model,page object pattern,page object,pom,parsing,browser
+Author: Saritasa
+Author-email: pypi@saritasa.com
+Maintainer: Anton Oboleninov
+Maintainer-email: anton.oboleninov@saritasa.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: selenium (>=4.12)
+Project-URL: Documentation, http://pomcorn.rtfd.io/
+Project-URL: Repository, https://github.com/saritasa-nest/pomcorn/
+Description-Content-Type: text/markdown
+
+# Pomcorn
+
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/saritasa-nest/pomcorn/pre-commit.yml) ![PyPI](https://img.shields.io/pypi/v/pomcorn) ![PyPI - Status](https://img.shields.io/pypi/status/pomcorn) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pomcorn) ![PyPI - License](https://img.shields.io/pypi/l/pomcorn) ![PyPI - Downloads](https://img.shields.io/pypi/dm/pomcorn) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+
+**Pomcorn**, or **Page Object Model corn**, is a Python package that contains base classes to create systems based on [Selenium](https://github.com/SeleniumHQ/selenium#selenium) framework and **Page Object Model** pattern. You can read more about this pattern [here](https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/). The package can be used to create autotesting systems, parsing scripts and anything that requires
+interaction with the browser.
+
+The package includes next base classes to create Page Object Model (``POM``) pages:
+
+```mermaid
+  classDiagram
+    WebView <|-- Component
+    WebView <|-- Page
+    Component <|-- ListComponent
+    Component .. Locator
+    Page .. Component
+
+    class WebView{
+        -webdriver: Webdriver
+    }
+    class Page{
+        +wait_until_loaded()
+        +open()
+    }
+    class Component{
+        -page: Page
+        -base_locator: Locator
+        + wait_until_visible()
+    }
+    class ListComponent{
+        -item_locator: Locator
+        +count()
+        +all()
+        +get_item_by_text()
+    }
+    class Locator{
+      -query: String
+    }
+
+```
+
+It also includes [classes to locate elements](https://pomcorn.readthedocs.io/en/latest/locators.html) on the web page and a number of additional [waiting conditions](https://pomcorn.readthedocs.io/en/latest/waits_conditions.html>).
+
+## Installation
+
+You can install it by **pip**:
+
+```bash
+  pip install pomcorn
+```
+
+Or **poetry**:
+
+```bash
+  poetry add pomcorn
+```
+
+## Documentation
+
+Link to the documentation: [http://pomcorn.rtfd.io/](http://pomcorn.rtfd.io/).
+
+## Usage
+
+You need to [install pomcorn](https://pomcorn.readthedocs.io/en/latest/installation.html) and [Chrome webdriver](https://pomcorn.readthedocs.io/en/latest/installation.html#chrome-driver).
+
+Below is the code that opens ``PyPI.org``, searches for packages by name and prints names of found packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**, **Component**, **ListComponent** and **Element**.
+
+```python
+
+  from typing import Self
+
+  from selenium.webdriver import Chrome
+  from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.remote.webdriver import WebDriver
+
+  from pomcorn import Component, Element, ListComponent, Page, locators
+
+
+  # Prepare base page
+  class PyPIPage(Page):
+
+      APP_ROOT = "https://pypi.org"
+
+      search = Element(locators.IdLocator("search"))
+
+      def check_page_is_loaded(self) -> bool:
+          return self.init_element(locators.TagNameLocator("main")).is_displayed
+
+
+  # Prepare components
+  Package = Component[PyPIPage]
+
+
+  class PackageList(ListComponent[Package, PyPIPage]):
+
+      item_class = Package
+      relative_item_locator = locators.ClassLocator("snippet__name")
+
+      @property
+      def names(self) -> list[str]:
+          return [package.body.get_text() for package in self.all]
+
+
+  # Prepare search page
+  class SearchPage(PyPIPage):
+
+      @classmethod
+      def open(cls, webdriver: WebDriver, **kwargs) -> Self:
+          pypi_page = super().open(webdriver, **kwargs)
+          # Specific logic for PyPI for an open search page
+          pypi_page.search.fill("")
+          pypi_page.search.send_keys(Keys.ENTER)
+          return cls(webdriver, **kwargs)
+
+      @property
+      def results(self) -> PackageList:
+          return PackageList(
+              page=self,
+              base_locator=locators.PropertyLocator(
+                  prop="aria-label",
+                  value="Search results",
+              ),
+          )
+
+      def find(self, query: str) -> PackageList:
+          self.search.fill(query)
+          self.search.send_keys(Keys.ENTER)
+          return self.results
+
+
+  search_page = SearchPage.open(webdriver=Chrome())
+  print(search_page.find("saritasa").names)
+  search_page.webdriver.close()
+```
+
+For more information about package classes, you can read in [Object Hierarchy](https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html) and [Developer Interface](https://pomcorn.readthedocs.io/en/latest/developer_interface.html).
+
+Also you can try our [demo autotests project](https://pomcorn.readthedocs.io/en/latest/demo.html).
+

pomcorn-0.7.1/README.md

@@ -0,0 +1,138 @@
+# Pomcorn
+
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/saritasa-nest/pomcorn/pre-commit.yml) ![PyPI](https://img.shields.io/pypi/v/pomcorn) ![PyPI - Status](https://img.shields.io/pypi/status/pomcorn) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pomcorn) ![PyPI - License](https://img.shields.io/pypi/l/pomcorn) ![PyPI - Downloads](https://img.shields.io/pypi/dm/pomcorn) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+
+**Pomcorn**, or **Page Object Model corn**, is a Python package that contains base classes to create systems based on [Selenium](https://github.com/SeleniumHQ/selenium#selenium) framework and **Page Object Model** pattern. You can read more about this pattern [here](https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/). The package can be used to create autotesting systems, parsing scripts and anything that requires
+interaction with the browser.
+
+The package includes next base classes to create Page Object Model (``POM``) pages:
+
+```mermaid
+  classDiagram
+    WebView <|-- Component
+    WebView <|-- Page
+    Component <|-- ListComponent
+    Component .. Locator
+    Page .. Component
+
+    class WebView{
+        -webdriver: Webdriver
+    }
+    class Page{
+        +wait_until_loaded()
+        +open()
+    }
+    class Component{
+        -page: Page
+        -base_locator: Locator
+        + wait_until_visible()
+    }
+    class ListComponent{
+        -item_locator: Locator
+        +count()
+        +all()
+        +get_item_by_text()
+    }
+    class Locator{
+      -query: String
+    }
+
+```
+
+It also includes [classes to locate elements](https://pomcorn.readthedocs.io/en/latest/locators.html) on the web page and a number of additional [waiting conditions](https://pomcorn.readthedocs.io/en/latest/waits_conditions.html>).
+
+## Installation
+
+You can install it by **pip**:
+
+```bash
+  pip install pomcorn
+```
+
+Or **poetry**:
+
+```bash
+  poetry add pomcorn
+```
+
+## Documentation
+
+Link to the documentation: [http://pomcorn.rtfd.io/](http://pomcorn.rtfd.io/).
+
+## Usage
+
+You need to [install pomcorn](https://pomcorn.readthedocs.io/en/latest/installation.html) and [Chrome webdriver](https://pomcorn.readthedocs.io/en/latest/installation.html#chrome-driver).
+
+Below is the code that opens ``PyPI.org``, searches for packages by name and prints names of found packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**, **Component**, **ListComponent** and **Element**.
+
+```python
+
+  from typing import Self
+
+  from selenium.webdriver import Chrome
+  from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.remote.webdriver import WebDriver
+
+  from pomcorn import Component, Element, ListComponent, Page, locators
+
+
+  # Prepare base page
+  class PyPIPage(Page):
+
+      APP_ROOT = "https://pypi.org"
+
+      search = Element(locators.IdLocator("search"))
+
+      def check_page_is_loaded(self) -> bool:
+          return self.init_element(locators.TagNameLocator("main")).is_displayed
+
+
+  # Prepare components
+  Package = Component[PyPIPage]
+
+
+  class PackageList(ListComponent[Package, PyPIPage]):
+
+      item_class = Package
+      relative_item_locator = locators.ClassLocator("snippet__name")
+
+      @property
+      def names(self) -> list[str]:
+          return [package.body.get_text() for package in self.all]
+
+
+  # Prepare search page
+  class SearchPage(PyPIPage):
+
+      @classmethod
+      def open(cls, webdriver: WebDriver, **kwargs) -> Self:
+          pypi_page = super().open(webdriver, **kwargs)
+          # Specific logic for PyPI for an open search page
+          pypi_page.search.fill("")
+          pypi_page.search.send_keys(Keys.ENTER)
+          return cls(webdriver, **kwargs)
+
+      @property
+      def results(self) -> PackageList:
+          return PackageList(
+              page=self,
+              base_locator=locators.PropertyLocator(
+                  prop="aria-label",
+                  value="Search results",
+              ),
+          )
+
+      def find(self, query: str) -> PackageList:
+          self.search.fill(query)
+          self.search.send_keys(Keys.ENTER)
+          return self.results
+
+
+  search_page = SearchPage.open(webdriver=Chrome())
+  print(search_page.find("saritasa").names)
+  search_page.webdriver.close()
+```
+
+For more information about package classes, you can read in [Object Hierarchy](https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html) and [Developer Interface](https://pomcorn.readthedocs.io/en/latest/developer_interface.html).
+
+Also you can try our [demo autotests project](https://pomcorn.readthedocs.io/en/latest/demo.html).

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/__init__.py

@@ -1,15 +1,11 @@
-from pomcorn.component import (
-    Component,
-    ComponentWithBaseLocator,
-    ListComponent,
-)
-from pomcorn.element import Element, XPathElement
+from pomcorn.component import Component, ListComponent
+from pomcorn.descriptors import Element
+from pomcorn.element import XPathElement
 from pomcorn.page import Page
 from pomcorn.web_view import WebView
 
 __all__ = (
     "Component",
-    "ComponentWithBaseLocator",
     "ListComponent",
     "Element",
     "XPathElement",

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/component.py

@@ -9,26 +9,12 @@ TPage = TypeVar("TPage", bound=Page)
 
 
 class Component(Generic[TPage], WebView):
-    """The class to represent a page component.
-
-    It contains page elements and utils methods for page manipulation, but as a
-    separate entity that can be reused for different pages with common
-    elements.
-
-    """
-
-    def __init__(self, page: TPage):
-        super().__init__(
-            page.webdriver,
-            app_root=page.app_root,
-            wait_timeout=page.wait_timeout,
-        )
-        self.page = page
-
-
-class ComponentWithBaseLocator(Generic[TPage], Component[TPage]):
     """The class to represent a page component that depends on base locator.
 
+    It contains page elements, components and utils methods for page
+    manipulation, but as a separate entity that can be reused for different
+    pages with common elements.
+
     Implement wait methods until the component becomes visible or invisible.
 
     """
@@ -45,14 +31,19 @@ class ComponentWithBaseLocator(Generic[TPage], Component[TPage]):
 
         Args:
             page: An instance of the page that uses this component.
-            base_locator: Instance of a class to locate the element in
-                the browser. Used in relative element initialization methods
-                and visibility waits. You also can specify it as attribute.
+            base_locator: Instance of a class to locate the component in the
+                browser. Used in relative element initialization methods and
+                visibility waits. You also can specify it as attribute.
             wait_until_visible: Whether to wait for the component to become
                 visible before completing initialization or not.
 
         """
-        super().__init__(page)
+        super().__init__(
+            page.webdriver,
+            app_root=page.app_root,
+            wait_timeout=page.wait_timeout,
+        )
+        self.page = page
         self.base_locator = base_locator or self.base_locator
         self.body = self.init_element(locator=self.base_locator)
 
@@ -171,18 +162,12 @@ class ComponentWithBaseLocator(Generic[TPage], Component[TPage]):
         self.body.wait_until_invisible()
 
 
-# Here type ignore added because we can't specify TPage as generic
-# for ComponentWithBaseLocator, but specifying Page is incorrect
-ListItemType = TypeVar(
-    "ListItemType",
-    bound=ComponentWithBaseLocator,  # type: ignore
-)
+# Here type ignore added because we can't specify TPage as generic for
+# Component, but specifying Page is incorrect
+ListItemType = TypeVar("ListItemType", bound=Component)  # type: ignore
 
 
-class ListComponent(
-    Generic[ListItemType, TPage],
-    ComponentWithBaseLocator[TPage],
-):
+class ListComponent(Generic[ListItemType, TPage], Component[TPage]):
     """Class to represent a list-like component.
 
     It contains standard properties and methods for working with list-like

pomcorn-0.7.1/pomcorn/descriptors/__init__.py

@@ -0,0 +1,3 @@
+from pomcorn.descriptors.element import Element
+
+__all__ = ("Element",)

pomcorn-0.7.1/pomcorn/descriptors/element.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NoReturn, overload
+
+from pomcorn import locators
+
+if TYPE_CHECKING:
+    from pomcorn import WebView, XPathElement
+
+
+class Element:
+    """Descriptor for init `PomcornElement` as attribute by locator.
+
+    .. code-block:: python
+
+        # Example
+        from pomcorn import Page, Element
+
+        class MainPage(Page):
+            title_element = Element(locators.ClassLocator("page-title"))
+
+    """
+
+    cache_attribute_name = "cached_elements"
+
+    @overload
+    def __init__(
+        self,
+        locator: locators.XPathLocator | None = None,
+    ) -> None:
+        ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        relative_locator: locators.XPathLocator | None = None,
+    ) -> None:
+        ...
+
+    def __init__(
+        self,
+        locator: locators.XPathLocator | None = None,
+        *,
+        relative_locator: locators.XPathLocator | None = None,
+    ) -> None:
+        """Initialize descriptor.
+
+        Use `relative_locator` if you need to include `base_locator` of
+        instance, otherwise use `locator`.
+
+        If descriptor is used for instance of ``Page``, then
+        ``relative_locator`` is not needed, since element will be searched
+        across the entire page, not within some component.
+
+        """
+        self.locator = locator
+        self.relative_locator = relative_locator
+
+    def __set_name__(self, _owner: type, name: str) -> None:
+        """Save attribute name for which descriptor is created."""
+        self.attribute_name = name
+
+    def __get__(
+        self,
+        instance: WebView | None,
+        _type: type[WebView],
+    ) -> XPathElement:
+        """Get element with stored locator."""
+        if not instance:
+            raise AttributeError("This descriptor is for instances only!")
+        return self.prepare_element(instance)
+
+    def prepare_element(self, instance: WebView) -> XPathElement:
+        """Init and cache element in instance.
+
+        Initiate element only once, and then store it in an instance and
+        return it each subsequent time. This is to avoid calling
+        `wait_until_visible` multiple times in the init of component.
+
+        If the instance doesn't already have an attribute to store cache, it
+        will be set.
+
+        If descriptor is used for ``Component`` and
+        ``self.is_relative_locator=True``, element will be found by sum of
+        ``base_locator`` of that component and passed locator of descriptor.
+
+        """
+        if not getattr(instance, self.cache_attribute_name, None):
+            setattr(instance, self.cache_attribute_name, {})
+
+        cache = getattr(instance, self.cache_attribute_name, {})
+        if cached_element := cache.get(self.attribute_name):
+            return cached_element
+
+        element = instance.init_element(
+            locator=self._prepare_locator(instance),
+        )
+        cache[self.attribute_name] = element
+
+        return element
+
+    def _prepare_locator(self, instance: WebView) -> locators.XPathLocator:
+        """Prepare a locator by arguments.
+
+        Check that only one locator argument is passed, or none.
+        If only `relative_locator` was passed, `base_locator` of instance will
+        be added to specified in descriptor arguments. If only `locator` was
+        passed, it will return only specified one.
+
+        Raises:
+            ValueError: If both arguments were passed or neither or
+                ``relative_locator`` used not in ``Component``.
+
+        """
+        if self.relative_locator and self.locator:
+            raise ValueError(
+                "You need to pass only one of the arguments: "
+                "`locator` or `relative_locator`.",
+            )
+
+        if not self.relative_locator:
+            if not self.locator:
+                raise ValueError(
+                    "You need to pass one of the arguments: "
+                    "`locator` or `relative_locator`.",
+                )
+            return self.locator
+
+        from pomcorn import Component
+
+        if self.relative_locator and isinstance(instance, Component):
+            return instance.base_locator // self.relative_locator
+
+        raise ValueError(
+            f"`relative_locator` should be used only if descriptor used in "
+            f"component. `{instance}` is not a component.",
+        )
+
+    def __set__(self, *args, **kwargs) -> NoReturn:
+        raise ValueError("You can't reset an element attribute value!")

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/element.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
     from pomcorn.web_view import WebView
 
 
-class Element(Generic[locators.TLocator]):
+class PomcornElement(Generic[locators.TLocator]):
     """The class to represent a simple element (tag) on the page.
 
     Contains methods for the interaction with an element on the browser page.
@@ -285,6 +285,7 @@ class Element(Generic[locators.TLocator]):
     def click(
         self,
         only_visible: bool = True,
+        scroll_to: bool = True,
         wait_until_clickable: bool = True,
     ):
         """Click on element.
@@ -292,17 +293,20 @@ class Element(Generic[locators.TLocator]):
         Args:
             only_visible: Flag for viewing visible elements. If this is `True`
                 (default), then this method will only get visible elements.
+            scroll_to: Whether to scroll to element before clicking or not.
             wait_until_clickable: Wait until the element is clickable before
                 clicking, or not (default `True`).
 
         """
+        if scroll_to:
+            self.scroll_to(only_visible=only_visible)
         if wait_until_clickable:
             self.wait_until_clickable()
         self.get_element(only_visible=only_visible).click()
 
     def drag_and_drop(
         self,
-        target: Element[locators.TLocator],
+        target: PomcornElement[locators.TLocator],
         only_visible: bool = True,
     ):
         """Drag and drop page object on target object.
@@ -376,4 +380,4 @@ class Element(Generic[locators.TLocator]):
         )
 
 
-XPathElement = Element[locators.XPathLocator]
+XPathElement = PomcornElement[locators.XPathLocator]

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/locators/base_locators.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterator
-from typing import TypeVar
+from typing import Literal, TypeVar
 
 from selenium.webdriver.common.by import By
 
@@ -120,12 +120,22 @@ class XPathLocator(Locator):
         super().__init__(by=By.XPATH, query=query)
 
     def __truediv__(self, other: XPathLocator) -> XPathLocator:
-        """Override `/` operator to implement following XPath locators."""
-        return XPathLocator(query=f"{self.query}/{other.related_query}")
+        """Override `/` operator to implement following XPath locators.
+
+        "/" used to select the nearest children of the current node.
+
+        """
+        return self.prepare_relative_locator(other=other, separator="/")
 
     def __floordiv__(self, other: XPathLocator) -> XPathLocator:
-        """Override `//` operator to implement nested XPath locators."""
-        return XPathLocator(query=f"{self.query}//{other.related_query}")
+        """Override `//` operator to implement nested XPath locators.
+
+        "//" used to select all descendants (children, grandchildren,
+        great-grandchildren, etc.) of current node, regardless of their level
+        in hierarchy.
+
+        """
+        return self.prepare_relative_locator(other=other, separator="//")
 
     def __or__(self, other: XPathLocator) -> XPathLocator:
         r"""Override `|` operator to implement variant XPath locators.
@@ -142,6 +152,72 @@ class XPathLocator(Locator):
         """
         return XPathLocator(query=f"({self.query} | {other.query})")
 
+    def __bool__(self) -> bool:
+        """Return whether query of current locator is empty or not."""
+        return bool(self.related_query)
+
     def extend_query(self, extra_query: str) -> XPathLocator:
         """Return new XPathLocator with extended query."""
         return XPathLocator(query=self.query + extra_query)
+
+    def contains(self, text: str, exact: bool = False) -> XPathLocator:
+        """Return new XPathLocator with search on contained text.
+
+        This is shortcut for the commonly used
+        `.extend_query(f"[contains(., '{text}')])`.
+
+        Args:
+            text: The text that should be inside the tag.
+            exact: Specify whether the text being searched must match exactly.
+                By default, the search is based on a partial match.
+
+        """
+        partial_query = f"[contains(., '{text}')]"
+        exact_query = f"[./text()='{text}']"
+        return self.extend_query(exact_query if exact else partial_query)
+
+    def prepare_relative_locator(
+        self,
+        other: XPathLocator,
+        separator: Literal["/", "//"] = "/",
+    ) -> XPathLocator:
+        """Prepare relative locator base on queries of two locators.
+
+        If one of parent and other locator queries is empty, the method will
+        return only the filled one.
+
+        Args:
+            other: Child locator object.
+            separator: Literal which will placed between locators queries - "/"
+                used to select nearest children of current node and "//" used
+                to select all descendants (children, grandchildren,
+                great-grandchildren, etc.) of current node, regardless of their
+                level in hierarchy.
+
+        Raises:
+            ValueError: If parent and child locators queries are empty.
+
+        """
+        related_query = self.related_query
+        if not related_query.startswith("("):
+            # Parent query can be bracketed, in which case we don't need to use
+            # `//`
+            # Example:
+            #   (//li)[3] -> valid
+            #   //(//li)[3] -> invalid
+            related_query = f"//{self.related_query}"
+
+        locator = XPathLocator(
+            query=f"{related_query}{separator}{other.related_query}",
+        )
+
+        if self and other:
+            return locator
+
+        if not (self or other):
+            raise ValueError(
+                f"Both of locators have empty query. The `{locator.query}` is "
+                "not a valid locator.",
+            )
+
+        return other if not self else self

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/locators/xpath_locators.py

@@ -207,7 +207,9 @@ class InputInLabelLocator(XPathLocator):
     ``//label[contains(., "label")]//input``, where ``label`` is the text of
     the input label.
 
-    Example:
+    .. code-block:: html
+
+        # Example
         <label>Title</label>
             <input value="Value">
         </label>
@@ -228,7 +230,9 @@ class InputByLabelLocator(XPathLocator):
     ``//label[contains(., "label")]/following-sibling::input``, where ``label``
     is the text of the input label.
 
-    Example:
+    .. code-block:: html
+
+        # Example
         <div>
             <label for="InputWithLabel">Title</label>
             <input id="InputWithLabel" value="Value">

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/page.py

@@ -122,8 +122,9 @@ class Page(WebView):
             self.wait.until(lambda _: self.check_page_is_loaded())
         except TimeoutException:
             raise PageDidNotLoadedError(
-                f"Page didn't loaded in {self.wait_timeout} seconds! "
-                "Didn't wait for `True` from `check_page_is_loaded` method.",
+                f"Page `{self.__class__}` didn't loaded in "
+                f"{self.wait_timeout} seconds! Didn't wait for `True` from "
+                "`check_page_is_loaded` method.",
             )
 
     def navigate(self, url: str) -> None:

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/waits_conditions.py

@@ -13,7 +13,7 @@ from selenium.webdriver.support.expected_conditions import (
 
 from pomcorn.locators.base_locators import TLocator
 
-from .element import Element
+from .element import PomcornElement
 
 
 def url_not_matches(pattern: str) -> Callable[[WebDriver], bool]:
@@ -26,7 +26,7 @@ def url_not_matches(pattern: str) -> Callable[[WebDriver], bool]:
 
 
 def text_in_element_changes(
-    element: Element[TLocator] | TLocator,
+    element: PomcornElement[TLocator] | TLocator,
     old_text: str,
 ) -> Callable[[WebDriver], bool]:
     """Represent `wait condition` to check that text doesn't match old text.
@@ -40,7 +40,7 @@ def text_in_element_changes(
     def check_the_match(driver: WebDriver) -> bool:
         target = element
 
-        if isinstance(target, Element):
+        if isinstance(target, PomcornElement):
             return old_text != target.get_text()
 
         return old_text != driver.find_element(*target).text
@@ -49,14 +49,14 @@ def text_in_element_changes(
 
 
 def element_not_exists_in_dom(
-    element: Element[TLocator] | TLocator,
+    element: PomcornElement[TLocator] | TLocator,
 ) -> Callable[[WebDriver], bool]:
     """Represent `wait condition` to check that element not exists in DOM."""
 
     def check_the_match(driver: WebDriver) -> bool:
         target = element
 
-        if isinstance(target, Element):
+        if isinstance(target, PomcornElement):
             return not target.exists_in_dom
 
         try:

{pomcorn-0.6.0 → pomcorn-0.7.1}/pomcorn/web_view.py

@@ -7,7 +7,7 @@ from selenium.webdriver.remote.webelement import WebElement
 from selenium.webdriver.support import expected_conditions
 from selenium.webdriver.support.wait import WebDriverWait
 
-from pomcorn.element import Element, XPathElement
+from pomcorn.element import PomcornElement, XPathElement
 
 from . import exceptions, locators, waits_conditions
 from .locators.base_locators import TInitLocator
@@ -44,18 +44,21 @@ class WebView:
             poll_frequency=poll_frequency,
         )
 
-    def init_element(self, locator: TInitLocator) -> Element[TInitLocator]:
+    def init_element(
+        self,
+        locator: TInitLocator,
+    ) -> PomcornElement[TInitLocator]:
         """Shortcut for initializing Element instances.
 
         Note: To be consistent with the method of the same name in
-        ``ComponentWithBaseLocator``, try to use keyword when specifying
-        the ``locator`` argument whenever possible.
+        ``Component``, try to use keyword when specifying the ``locator``
+        argument whenever possible.
 
         Args:
             locator: Instance of a class to locate the element in the browser.
 
         """
-        return Element(self, locator=locator)
+        return PomcornElement(web_view=self, locator=locator)
 
     def init_elements(
         self,
@@ -66,8 +69,8 @@ class WebView:
         Note: Only supports Xpath locators.
 
         Note: To be consistent with the method of the same name in
-        ``ComponentWithBaseLocator``, try to use keyword when specifying the
-        ``locator`` argument whenever possible.
+        ``Component``, try to use keyword when specifying the ``locator``
+        argument whenever possible.
 
         Args:
             locator: Instance of a class to locate the element in the browser.
@@ -317,7 +320,7 @@ class WebView:
 
     def wait_until_not_exists_in_dom(
         self,
-        element: Element[locators.TLocator] | locators.TLocator,
+        element: PomcornElement[locators.TLocator] | locators.TLocator,
     ):
         """Wait until element ceases to exist in DOM.
 

{pomcorn-0.6.0 → pomcorn-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pomcorn"
-version = "0.6.0"
+version = "0.7.1"
 description = "Base implementation of Page Object Model"
 authors = [
   "Saritasa <pypi@saritasa.com>",
@@ -24,7 +24,7 @@ keywords = [
   "browser",
 ]
 license = "MIT"
-readme = "README.rst"
+readme = "README.md"
 packages = [
   { include = "pomcorn" }
 ]
@@ -62,6 +62,9 @@ sphinx = ">= 7.2.6"
 # The Sphinx theme for docs
 # https://sphinx-rtd-theme.readthedocs.io/en/stable/
 sphinx-rtd-theme = ">= 1.3.0rc1"
+# Support mermaid diagrams
+# https://github.com/mgaitan/sphinxcontrib-mermaid/tree/master
+sphinxcontrib-mermaid = "^0.9.2"
 
 [tool.poetry.group.demo.dependencies]
 pytest = ">= 7.4.2"

pomcorn-0.6.0/PKG-INFO

@@ -1,190 +0,0 @@
-Metadata-Version: 2.1
-Name: pomcorn
-Version: 0.6.0
-Summary: Base implementation of Page Object Model
-Home-page: https://pypi.org/project/pomcorn/
-License: MIT
-Keywords: python,selenium,webdriver,autotests,page object model,page object pattern,page object,pom,parsing,browser
-Author: Saritasa
-Author-email: pypi@saritasa.com
-Maintainer: Anton Oboleninov
-Maintainer-email: anton.oboleninov@saritasa.com
-Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: selenium (>=4.12)
-Project-URL: Documentation, http://pomcorn.rtfd.io/
-Project-URL: Repository, https://github.com/saritasa-nest/pomcorn/
-Description-Content-Type: text/x-rst
-
-===============================================================================
-Pomcorn
-===============================================================================
-
-.. image:: https://img.shields.io/github/actions/workflow/status/saritasa-nest/pomcorn/pre-commit.yml
-	:target: https://img.shields.io/
-	:alt: GitHub Workflow Status (with event)
-
-.. image:: https://img.shields.io/pypi/v/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI
-
-.. image:: https://img.shields.io/pypi/status/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Status
-
-.. image:: https://img.shields.io/pypi/pyversions/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Python Version
-
-.. image:: https://img.shields.io/pypi/l/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - License
-
-.. image:: https://img.shields.io/pypi/dm/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Downloads
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-	:target: https://github.com/psf/black
-	:alt: Code style: black
-
-.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
-	:target: https://pycqa.github.io/isort/
-	:alt: Imports: isort
-
-
-**Pomcorn**, or **Page Object Model corn**, is a Python package that contains base classes to create
-systems based on `Selenium <https://github.com/SeleniumHQ/selenium#selenium>`_ framework and
-**Page Object Model** pattern. You can read more about this pattern
-`here <https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/>`_.
-The package can be used to create autotesting systems, parsing scripts and anything that requires
-interaction with the browser.
-
-The package includes next base classes to create Page Object Model (``POM``) pages:
-
-.. image:: docs/_static/images/class_diagram.png
-    :alt: Class diagram
-
-It also includes
-`classes to locate elements <https://pomcorn.readthedocs.io/en/latest/locators.html>`_
-on the web page and a number of additional
-`waiting conditions  <https://pomcorn.readthedocs.io/en/latest/waits_conditions.html>`_.
-
-*******************************************************************************
-Installation
-*******************************************************************************
-
-You can install it by **pip**:
-
-.. code-block:: console
-
-    $ pip install pomcorn
-
-Or **poetry**:
-
-.. code-block:: console
-
-    $ poetry add pomcorn
-
-*******************************************************************************
-Documentation
-*******************************************************************************
-
-Link to the documentation: http://pomcorn.rtfd.io/.
-
-*******************************************************************************
-Usage
-*******************************************************************************
-
-You need to
-`install pomcorn <https://pomcorn.readthedocs.io/en/latest/installation.html>`_ and
-`Chrome webdriver <https://pomcorn.readthedocs.io/en/latest/installation.html#chrome-driver>`_.
-
-Below is the code that opens ``PyPI.org``, searches for packages by name and prints names of found
-packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**,
-**ComponentWithBaseLocator**, **ListComponent** and **Element**.
-
-.. code-block:: python
-
-  from typing import Self
-
-  from selenium.webdriver import Chrome
-  from selenium.webdriver.common.keys import Keys
-  from selenium.webdriver.remote.webdriver import WebDriver
-
-  from pomcorn import ComponentWithBaseLocator, Element, ListComponent, Page, locators
-
-
-  # Prepare base page
-  class PyPIPage(Page):
-
-      APP_ROOT = "https://pypi.org"
-
-      def check_page_is_loaded(self) -> bool:
-          return self.init_element(locators.TagNameLocator("main")).is_displayed
-
-      @property
-      def search(self) -> Element[locators.XPathLocator]:
-          return self.init_element(locators.IdLocator("search"))
-
-
-  # Prepare components
-  Package = ComponentWithBaseLocator[PyPIPage]
-
-
-  class PackageList(ListComponent[Package, PyPIPage]):
-
-      item_class = Package
-
-      @property
-      def base_item_locator(self) -> locators.XPathLocator:
-          return self.base_locator // locators.ClassLocator("snippet__name")
-
-      @property
-      def names(self) -> list[str]:
-          return [package.body.get_text() for package in self.all]
-
-
-  # Prepare search page
-  class SearchPage(PyPIPage):
-
-      @classmethod
-      def open(cls, webdriver: WebDriver, **kwargs) -> Self:
-          pypi_page = super().open(webdriver, **kwargs)
-          # Specific logic for PyPI for an open search page
-          pypi_page.search.fill("")
-          pypi_page.search.send_keys(Keys.ENTER)
-          return cls(webdriver, **kwargs)
-
-      @property
-      def results(self) -> PackageList:
-          return PackageList(
-              page=self,
-              base_locator=locators.PropertyLocator(
-                  prop="aria-label",
-                  value="Search results",
-              ),
-          )
-
-      def find(self, query: str) -> PackageList:
-          self.search.fill(query)
-          self.search.send_keys(Keys.ENTER)
-          return self.results
-
-
-  search_page = SearchPage.open(webdriver=Chrome())
-  print(search_page.find("saritasa").names)
-
-For more information about package classes, you can read in `Object Hierarchy <https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html>`_
-and `Developer Interface <https://pomcorn.readthedocs.io/en/latest/developer_interface.html>`_.
-
-Also you can try our `demo autotests project <https://pomcorn.readthedocs.io/en/latest/demo.html>`_.
-

pomcorn-0.6.0/README.rst

@@ -1,163 +0,0 @@
-===============================================================================
-Pomcorn
-===============================================================================
-
-.. image:: https://img.shields.io/github/actions/workflow/status/saritasa-nest/pomcorn/pre-commit.yml
-	:target: https://img.shields.io/
-	:alt: GitHub Workflow Status (with event)
-
-.. image:: https://img.shields.io/pypi/v/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI
-
-.. image:: https://img.shields.io/pypi/status/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Status
-
-.. image:: https://img.shields.io/pypi/pyversions/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Python Version
-
-.. image:: https://img.shields.io/pypi/l/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - License
-
-.. image:: https://img.shields.io/pypi/dm/pomcorn
-	:target: https://img.shields.io/
-	:alt: PyPI - Downloads
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-	:target: https://github.com/psf/black
-	:alt: Code style: black
-
-.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
-	:target: https://pycqa.github.io/isort/
-	:alt: Imports: isort
-
-
-**Pomcorn**, or **Page Object Model corn**, is a Python package that contains base classes to create
-systems based on `Selenium <https://github.com/SeleniumHQ/selenium#selenium>`_ framework and
-**Page Object Model** pattern. You can read more about this pattern
-`here <https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/>`_.
-The package can be used to create autotesting systems, parsing scripts and anything that requires
-interaction with the browser.
-
-The package includes next base classes to create Page Object Model (``POM``) pages:
-
-.. image:: docs/_static/images/class_diagram.png
-    :alt: Class diagram
-
-It also includes
-`classes to locate elements <https://pomcorn.readthedocs.io/en/latest/locators.html>`_
-on the web page and a number of additional
-`waiting conditions  <https://pomcorn.readthedocs.io/en/latest/waits_conditions.html>`_.
-
-*******************************************************************************
-Installation
-*******************************************************************************
-
-You can install it by **pip**:
-
-.. code-block:: console
-
-    $ pip install pomcorn
-
-Or **poetry**:
-
-.. code-block:: console
-
-    $ poetry add pomcorn
-
-*******************************************************************************
-Documentation
-*******************************************************************************
-
-Link to the documentation: http://pomcorn.rtfd.io/.
-
-*******************************************************************************
-Usage
-*******************************************************************************
-
-You need to
-`install pomcorn <https://pomcorn.readthedocs.io/en/latest/installation.html>`_ and
-`Chrome webdriver <https://pomcorn.readthedocs.io/en/latest/installation.html#chrome-driver>`_.
-
-Below is the code that opens ``PyPI.org``, searches for packages by name and prints names of found
-packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**,
-**ComponentWithBaseLocator**, **ListComponent** and **Element**.
-
-.. code-block:: python
-
-  from typing import Self
-
-  from selenium.webdriver import Chrome
-  from selenium.webdriver.common.keys import Keys
-  from selenium.webdriver.remote.webdriver import WebDriver
-
-  from pomcorn import ComponentWithBaseLocator, Element, ListComponent, Page, locators
-
-
-  # Prepare base page
-  class PyPIPage(Page):
-
-      APP_ROOT = "https://pypi.org"
-
-      def check_page_is_loaded(self) -> bool:
-          return self.init_element(locators.TagNameLocator("main")).is_displayed
-
-      @property
-      def search(self) -> Element[locators.XPathLocator]:
-          return self.init_element(locators.IdLocator("search"))
-
-
-  # Prepare components
-  Package = ComponentWithBaseLocator[PyPIPage]
-
-
-  class PackageList(ListComponent[Package, PyPIPage]):
-
-      item_class = Package
-
-      @property
-      def base_item_locator(self) -> locators.XPathLocator:
-          return self.base_locator // locators.ClassLocator("snippet__name")
-
-      @property
-      def names(self) -> list[str]:
-          return [package.body.get_text() for package in self.all]
-
-
-  # Prepare search page
-  class SearchPage(PyPIPage):
-
-      @classmethod
-      def open(cls, webdriver: WebDriver, **kwargs) -> Self:
-          pypi_page = super().open(webdriver, **kwargs)
-          # Specific logic for PyPI for an open search page
-          pypi_page.search.fill("")
-          pypi_page.search.send_keys(Keys.ENTER)
-          return cls(webdriver, **kwargs)
-
-      @property
-      def results(self) -> PackageList:
-          return PackageList(
-              page=self,
-              base_locator=locators.PropertyLocator(
-                  prop="aria-label",
-                  value="Search results",
-              ),
-          )
-
-      def find(self, query: str) -> PackageList:
-          self.search.fill(query)
-          self.search.send_keys(Keys.ENTER)
-          return self.results
-
-
-  search_page = SearchPage.open(webdriver=Chrome())
-  print(search_page.find("saritasa").names)
-
-For more information about package classes, you can read in `Object Hierarchy <https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html>`_
-and `Developer Interface <https://pomcorn.readthedocs.io/en/latest/developer_interface.html>`_.
-
-Also you can try our `demo autotests project <https://pomcorn.readthedocs.io/en/latest/demo.html>`_.