selenium-query 0.1.0__tar.gz

selenium_query-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.3
+Name: selenium-query
+Version: 0.1.0
+Summary: Python equivalent of jQuery, to write selenium tests.
+License: GPL-3.0-or-later
+Author: Frédéric Zinelli
+Author-email: frederic.zinelli@gmail.com
+Requires-Python: >=3.9, <4.0
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: selenium (>=4.36)
+Description-Content-Type: text/markdown
+
+

selenium_query-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "selenium-query"
+version = "0.1.0"
+description = "Python equivalent of jQuery, to write selenium tests."
+license = { text = "GPL-3.0-or-later" }
+authors = [
+    {name = "Frédéric Zinelli",email = "frederic.zinelli@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.9, <4.0"
+dependencies = [
+    "selenium (>=4.36)"
+]
+
+
+[tool.setuptools]
+packages = ["selenium_query"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "<9.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

selenium_query-0.1.0/selenium_query/__init__.py

@@ -0,0 +1,10 @@
+
+from ._types_and_tools import center_of
+from .getter import Getter
+from ._any_all_getters import BoolAnyGetter, BoolAllGetter
+from ._values_getter import ValuesGetter
+from ._asserter_getter import AsserterGetter
+from ._filter_getter import FilterGetter
+from ._order_getter import OrderGetter
+from ._mapper_getter import MapperGetter
+from ._negation_transmitter import NotTransmitter

selenium_query-0.1.0/selenium_query/_any_all_getters.py

@@ -0,0 +1,17 @@
+
+from typing import Callable, ClassVar
+
+from .getter import Getter
+
+
+
+# Explicite redeclaration, to register properly the accessor:
+class BoolAllGetter(Getter, accessor="all"):
+    pass
+
+
+
+class BoolAnyGetter(BoolAllGetter, accessor="any"):
+
+    COMBINER: ClassVar[Callable] = any
+

selenium_query-0.1.0/selenium_query/_asserter_getter.py

@@ -0,0 +1,90 @@
+from textwrap import dedent
+from typing import Any, Callable
+
+from selenium.webdriver.remote.webelement import WebElement
+
+from ._basics.generic_value_getter import should_be
+from .getter import Getter
+
+
+
+
+
+
+class AsserterGetter(Getter, accessor="check"):
+    """
+    Asserter version of the Getter (css, data, props, id, has_class, ...), raising
+    AssertionError if ever something doesn't match.
+    * Assertions are chainable.
+    * An extra assertion message (head of default message) can be set using `getter.check(msg)`.
+
+    The expected values can be given as a unique value all the elements must match, or as a list.
+    In the latter,
+
+    Accessible through `Getter.check`.
+    """
+
+    _msg:str = None
+
+    def __call__(self, msg:str):
+        self._msg = dedent(msg).rstrip().lstrip('\n')
+        return self
+
+    def _with_msg(self, msg:str):
+        if not self._msg:
+            return msg
+        return f"\n\n{ self._msg or '' }\n\n{ msg }"
+
+    def _check_elements(
+        self,
+        ref_items,
+        value_getter: Callable[[WebElement,str],Any],
+        *,
+        is_ok:        Callable[[Any,Any],bool] = None,
+        feedback:     Callable[[Any,Any],bool] = None,
+    ) -> 'AsserterGetter' :
+
+        is_ok = self._default_is_ok(is_ok)
+        feedback = feedback or should_be
+
+        bads = [] if self.elements else ('no such element',)
+        bads.extend(
+            f"Wrong number of expected values for {prop!r}: {len(exp)} should be {len(self.elements)}"
+            for prop, exp in ref_items
+            if isinstance(exp, (list,tuple)) and len(self.elements) != len(exp)
+        )
+        for i_elt,element in enumerate(self.elements):
+            bads.extend(
+                f"{prop}: { feedback(expected, actual, self._negate) }"
+                    for prop, exp in ref_items
+                    if not is_ok(
+                        (expected := exp[i_elt] if isinstance(exp, (tuple, list)) else exp),
+                        (actual   := value_getter(element, prop))
+                    )
+            )
+
+        if bads:
+            data = ',\n  '.join(bads)
+            msg = self._with_msg(f"  { data }\n\nOn: { self }")
+            assert False, msg
+
+        self._msg = None
+        return self
+
+
+    def exists(self, exp=True):
+        """ Usable for non existing list of elements """
+        actual = super().exists()   # Already handle the negation!
+        msg = self._with_msg(f"  {actual} should { ' not'*self._negate }be {exp}\n\nOn: {self}")
+        assert actual == exp, msg
+        return self
+
+
+    def count(self, n:int):
+        """ Usable for non existing list of elements """
+        actual = super().count()    # Already handle the negation!
+        msg = self._with_msg(
+            f"  {actual} should { ' not'*self._negate }be {n}\n\nWrong number of children on: {self}"
+        )
+        assert actual == n, msg
+        return self

selenium_query-0.1.0/selenium_query/_basics/action_getter.py

@@ -0,0 +1,362 @@
+
+from contextlib import contextmanager, nullcontext
+from typing import Any, ClassVar, List, Optional, Union, TYPE_CHECKING
+
+from selenium.webdriver import Keys
+from selenium.webdriver.common.action_chains import ActionChains
+
+from .._types_and_tools import GetterOrCss, WaitingContext
+from .base_getter import BaseGetter
+
+if TYPE_CHECKING:
+    from ..getter import Getter
+
+
+
+
+class ActionGetter(BaseGetter):
+    """
+    Relay class, applying automatically the action which are normally `on_element` (or equivalent)
+    to all the self.elements. The chain of actions must then be triggered by accessing the `go`
+    property (triggers Action.perform() on all elements).
+
+    Methods which take another target as argument may take a css selector string instead
+    of a WebElement: the original method will be called with the equivalent element.
+    Note that the cardinality of the elements in the current object and those in the
+    targeted ones must be identical.
+
+    (see: https://github.com/SeleniumHQ/selenium/blob/trunk/py/selenium/webdriver/common/action_chains.py)
+    """
+
+    _context_action: ClassVar[Optional[ActionChains]] = None
+    """
+    Global ActionChains instance used when the `ActionGetter.context_chain_and_go` context
+    manager is used.
+    """
+
+
+    DURATION: ClassVar[int] = 40
+    """
+    Base duration (in milliseconds value for selenium actions (mouse move, in between clicks, ...)
+    Warning about consecutive clicks/actions: short values might end up in different behaviors.
+    Selenium default is 250 ms.
+    """
+
+
+    @staticmethod
+    @contextmanager
+    def swap_duration(duration:int):
+        """
+        Temporarily change the default duration for all actions. Restore it at the end of the tests.
+        """
+        old = ActionGetter.DURATION
+        ActionGetter.DURATION = duration
+        try:
+            yield
+        finally:
+            ActionGetter.DURATION = old
+
+
+    @contextmanager
+    def context_chain_and_go(self, duration:int=None):
+        """
+        With this context manager, the very same ActionChain object is used for every single
+        element/Getter object. When resuming executions, the ActionChain is automatically
+        triggered.
+
+        WARNING:
+        - `scroll_to` is not usable this way: scroll to an element must be done before, and all
+        subsequent moves should be done through other methods.
+        - there are no specific checks about other actions performed when several elements exist
+        on the same Getter object, so everything will be applied in order, even if it actually
+        does not make sense at `perform` time.
+        """
+        ActionGetter._context_action = ActionChains(
+            self.driver,
+            duration=self.DURATION if duration is None else duration
+        )
+        try:
+            yield None
+            ActionGetter._context_action.perform()
+        finally:
+            ActionGetter._context_action = None
+
+
+    def __getitem__(self, idx:int):
+        """
+        Returns a new instance of the current class, with only the element at index @idx.
+        If the current instance has actions, the corresponding action object is shared with the
+        returned object.
+        """
+        sub_getter = super().__getitem__(idx)
+        if self._actions:
+            sub_getter._actions = [self._actions[idx]]
+        return sub_getter
+
+    @property
+    def go(self):
+        """ Alias for `perform()`. """
+        return self.perform()
+
+    def perform(self) -> 'Getter':
+        """
+        Apply all the registered actions, then return a fresh Getter holding the very same
+        elements, but with a find method usable and no actions registered.
+        """
+        for action in self._actions:
+            action.perform()
+        return self
+
+
+    #------------------------------------------------------------------
+
+    def _this_or_that(self, other:Optional[GetterOrCss], current:bool=False):
+        """
+        By default apply the actions on the elements of the current instance.
+        If `@other` is provided, use the corresponding elements instead.
+        If @current=True, this means the current mouse position will be used to perform the
+        action, instead of moving to any element before.
+        """
+        if current and other is not None:
+            raise ValueError(
+                f"Cannot use the `current` mouse location when another element is targeted ({other=!r})."
+            )
+        return (
+            (None,) * len(self.elements) if current else
+            self.elements if not other else
+            self._getter_or_css(other).elements
+        )
+
+    def _getter_or_css(self, thing:Optional[GetterOrCss]) -> 'Getter' :
+        return thing and (self.find(thing, in_page=True) if isinstance(thing, str) else thing)
+
+    def _duplicate_value(self, value:Any):
+        return (value,) * len(self.elements)
+
+    def _apply(self, name:str, *args_values:List[Any]):
+        """
+        @args_values: list of all values to use for each element.
+        The lists are provided in the order matching the original method arguments.
+        Inside the lists, the values must match the self.elements order.
+
+        @returns a new ActionGetter instance, holding the new actions.
+        THIS INSTANCE MUST BE KEPT/STORED/USED to actually trigger all the registered actions.
+        """
+        if not self.elements:
+            raise ValueError(
+                f"Cannot initiate actions on a Getter without known elements.\n{ self }"
+            )
+
+        sizes = [*map(len,args_values)]
+        if len(set(sizes)) != 1:
+            raise ValueError(f"Mismatched arguments data lengths for {name}: {sizes}.\n{ self }")
+
+        zipped_args = tuple(zip(*args_values))
+        if len(zipped_args) != len(self.elements):
+            raise ValueError(
+                f"Mismatched arguments lengths for {name}: {len(self.elements)} elements, but found "
+                f"{len(zipped_args)} sets of arguments.\n{ self }"
+            )
+
+        if ActionGetter._context_action is not None:
+            for args in zipped_args:
+                ActionGetter._context_action = getattr(ActionGetter._context_action, name)(*args)
+            return self # No need to return a new instance, since no instance states are mutated, here.
+
+        else:
+            actions = self._actions or [
+                ActionChains(self.driver, duration=self.DURATION) for _ in self.elements
+            ]
+            built_actions = [
+                getattr(action, name)(*args) for args,action in zip(zipped_args, actions)
+            ]
+            out = ActionGetter.from_(self)
+            out._actions = built_actions
+            return out
+
+
+    #-----------------------------------------------------------------------
+
+
+    def reset_actions(self):
+        return self._apply("reset_actions")
+
+    def click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("click", self._this_or_that(other, current))
+
+    def click_and_hold(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("click_and_hold", self._this_or_that(other, current))
+
+    def context_click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("context_click", self._this_or_that(other, current))
+
+    def double_click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("double_click", self._this_or_that(other, current))
+
+    def drag_and_drop(
+        self,
+        target: GetterOrCss,
+        get_target: bool=False,
+        other_src: Optional[GetterOrCss]=None,
+        *,
+        current=False,
+    ):
+        """
+        If @get_target is True, returns the Getter of the targeted elements instead of the current
+        instance.
+        The actions are transferred to the target object (shared object => CAREFUL WITH THAT!!!!)
+        """
+        targets = self._getter_or_css(target)
+        self._apply("drag_and_drop", self._this_or_that(other_src, current), targets.elements)
+        if get_target:
+            targets._actions = self._actions
+            return targets
+        return self
+
+    def drag_and_drop_by_offset(self, xoffset: int, yoffset: int, other_src:Optional[GetterOrCss]=None):
+        return self._apply(
+            "drag_and_drop_by_offset",
+            self._this_or_that(other_src),
+            self._duplicate_value(xoffset),
+            self._duplicate_value(yoffset),
+        )
+
+    def key_down(self, value: str, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("key_down", self._duplicate_value(value), self._this_or_that(other, current))
+
+    def key_up(self, value: str, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("key_up", self._duplicate_value(value), self._this_or_that(other, current))
+
+    def move_by_offset(self, xoffset: int, yoffset: int, release=False):
+        out = self._apply(
+            "move_by_offset",
+            self._duplicate_value(xoffset), self._duplicate_value(yoffset)
+        )
+        if release:
+            self.release(current=True)
+        return out
+
+    def move_to_element(self, other:Optional[GetterOrCss]=None):
+        return self._apply("move_to_element", self._this_or_that(other))
+
+    move_to = move_to_element
+    """ Alias for move_to_element """
+
+    def move_to_element_with_offset(self, xoffset: int, yoffset: int, other:Optional[GetterOrCss]=None):
+        return self._apply(
+            "move_to_element_with_offset", self._this_or_that(other),
+            self._duplicate_value(xoffset), self._duplicate_value(yoffset)
+        )
+
+    def pause(self, seconds: Union[float, int, None]=None):
+        return self._apply("pause", self._duplicate_value(seconds or self.DURATION))
+
+    def release(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("release", self._this_or_that(other, current))
+
+    def send_keys_to_element(self, *keys_to_send: str, other:Optional[GetterOrCss]=None, current=False):
+        return self._apply(
+            "send_keys_to_element", self._this_or_that(other, current),
+            *map(self._duplicate_value, keys_to_send)
+        )
+
+    send_keys = send_keys_to_element
+    """
+    Alias for send_keys_to_element (because the Getter setup generalize the thing...)
+    """
+
+
+    # /!\ Selenium's base Scroll stuff just DOES NOT WORK!???
+    #
+    # def scroll_to_element(self, other:Optional[GetterOrCss]=None):
+    #     return self._apply("scroll_to_element", self._this_or_that(other))
+
+    # def scroll_by_amount(self, delta_x: int, delta_y: int):
+    #     return self._apply(
+    #         "scroll_by_amount",
+    #         self._duplicate_value(delta_x), self._duplicate_value(delta_y)
+    #     )
+
+    # def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y: int):
+    #     raise NotImplementedError("Getting lazy...")
+
+    def scroll_to(self, other:Optional[GetterOrCss]=None, *, shift:float=0, target_location:str='3/4'):
+        """
+        Scroll the current/given element into view. @shift may be used to tweak the final scroll
+        position, to avoid some targets to go out of the viewport.
+
+        @shift: Apply a vertical shift to the point considered as the point to center in the page.
+        @target_location: Ratio of innerHeight where to place the "center+shift" of the target.
+
+        WARNING: this action CANNOT be chained with others, because it is applied directly with JS.
+        """
+        elt = self if other is None else self._getter_or_css(other)
+        # Cannot scroll to different elements, considering how the actions are handled, so forbid it:
+        elt.check("Getters.scroll_to usage requires instances with exactly one element").count(1)
+
+        assert not self._actions and not ActionGetter._context_action, (
+            "scroll_to(...) cannot be chained with other actions, because it interacts directly with "
+            "the page, through the JS executor."
+        )
+
+        rect = elt.get.rect
+        center_y = rect['y'] + rect['height']/2 + shift
+
+        self.run_js(f"""
+            var centerY={ center_y }, H=innerHeight, Y=scrollY
+            var inBound = Y + H/6 <= centerY && centerY <= Y + H * 5/6
+            if(!inBound){{
+                scrollTo(0, centerY - H * { target_location } );
+            }}
+        """)
+        return elt
+
+
+    def send_shortcut(
+        self,
+        keys:str,
+        *,
+        waiting_context:WaitingContext=None,
+    ):
+        """
+        Takes a string representing a combination of keys "+" separated (spaces are ignored), like:
+            "Ctrl+S"
+            "Ctrl + Alt + Shift + Enter"
+            ...
+        The string is split, converted to the related selenium Keys and the combination is
+        automatically applied to the element.
+
+        @waiting_context: If given, must be a context manager function (ALREADY CALLED) to control
+        any delay/logic that should ba applied around the shortcut application.
+        """
+        *modifiers,key = map(to_keys, keys.replace(' ','').split("+"))
+        self.scroll_to()
+        with waiting_context or nullcontext():
+            with self.context_chain_and_go():
+                for mod in modifiers:
+                    self.key_down(mod)
+                self.send_keys(key)
+                for mod in modifiers:
+                    self.key_up(mod, current=True)
+                        # `current` because the shortcut could cause a move in the page.
+
+
+
+
+def to_keys(name:str) -> Keys:
+    """
+    Automatically convert a `Keys` name string to the corresponding value, or return the
+    original string.
+
+    * The input is case insensitive.
+    * 'CTRL' is automatically converted to 'CONTROL'
+    * 'PLUS' is automatically converted to 'Keys.ADD' (-> numpad +)
+    """
+    upper = name.upper()
+    if name.upper() == 'PLUS':
+        return Keys.ADD
+    if upper == 'CTRL':
+        upper = 'CONTROL'
+    return getattr(Keys, upper, name)
+
+