Repr/selector tests and docs

Author: VladimirPodolian

docs/source/kitchen_sink/index.md

@@ -5,11 +5,12 @@
 hidden:
 ---
 
-size
-location
+locator
+locator_type
 driver_container
+size
 box
-locator
+location
 scrolls
 ```
 
@@ -22,9 +23,10 @@ blocks for common operations, data structures, and utilities.
 
 ### Available Components
 
-- {doc}`Size Dataclass <./size>`
-- {doc}`Location Dataclass <./location>`
+- {doc}`Locator Dataclass <./locator>`
+- {doc}`Locator Type Constants <./locator_type>`
 - {doc}`Driver Dataclass <./driver_container>`
+- {doc}`Size Dataclass <./size>`
 - {doc}`Box Dataclass <./box>`
-- {doc}`Locator Dataclass <./locator>`
+- {doc}`Location Dataclass <./location>`
 - {doc}`Scrolls Constants <./scrolls>`

docs/source/kitchen_sink/locator_type.md

@@ -0,0 +1,7 @@
+# Locator Type Constants
+
+```{eval-rst}  
+.. autoclass:: mops.mixins.objects.locator_type.LocatorType
+   :undoc-members:
+   :inherited-members:
+```

mops/base/element.py

@@ -90,7 +90,7 @@ def __init__(
 
         If no driver is available, initialization is skipped and will be handled later in a Page or Group.
 
-        :param locator: The element's locator
+        :param locator: The element's locator. `.LocatorType` is optional.
         :type locator: typing.Union[Locator, str]
         :param name: The name of the element, used for logging and identification purposes.
         :type name: str

mops/base/group.py

@@ -50,7 +50,7 @@ def __init__(
          with specific methods to manage child elements, locator handling, and initialization
          with respect to the driver.
 
-        :param locator: The anchor locator for the group
+        :param locator: The anchor locator for the group. `.LocatorType` is optional.
         :type locator: typing.Union[Locator, str]
         :param name: The name of the group, used for logging and identification purposes.
         :type name: str

mops/base/page.py

@@ -62,7 +62,7 @@ def __init__(
         """
         Initializes a Page based on the current driver.
 
-        :param locator: The anchor locator of the page
+        :param locator: The anchor locator of the page. `.LocatorType` is optional.
         :type locator: typing.Union[Locator, str]
         :param name: The name of the page, used for logging and identification purposes.
         :type name: str

mops/mixins/objects/locator_type.py

@@ -0,0 +1,28 @@
+class LocatorType:
+    """
+    A container for locator types.
+
+    This class standardizes the locator types used in the Mops framework, ensuring
+    consistency and clarity when locating elements within web pages.
+
+    .. note::
+        You can specify a locator type along with your locator using the following syntax:
+
+        - :obj:`Element('xpath=//*[@class="class-attribute"]')`
+        - :obj:`Element('css=//*[@class="class-attribute"]')`
+        - :obj:`Element('text=some text')`
+        - :obj:`Element('id=id-without-spaces')`
+
+        The same applies to the :class:`.Locator` object:
+
+        - :obj:`Element(Locator(ios='xpath=//*[@class, "ios-specific"]'))`
+
+    .. note::
+        For better readability, you can use this class with the following syntax:
+
+        - :obj:`Element(f'{LocatorType.XPATH}=//*[@class="class-attribute"]')`
+    """
+    CSS: str = 'css'
+    XPATH: str = 'xpath'
+    ID: str = 'id'
+    TEXT: str = 'text'

mops/utils/selector_synchronizer.py

@@ -1,16 +1,17 @@
 from __future__ import annotations
 
 import re
-from dataclasses import dataclass
 from typing import Any, Union
 
 from selenium.webdriver.common.by import By
 
 from mops.exceptions import InvalidLocatorException
 from mops.mixins.objects.locator import Locator
+from mops.mixins.objects.locator_type import LocatorType
 from mops.utils.internal_utils import all_tags
 
 
+DEFAULT_MATCH = (f"{LocatorType.XPATH}=", f"{LocatorType.ID}=", f"{LocatorType.CSS}=", f"{LocatorType.TEXT}=")
 XPATH_MATCH = ("/", "./", "(/")
 CSS_MATCH = ("#", ".")
 CSS_REGEXP = r"[#.\[\]=]"
@@ -47,14 +48,6 @@ def get_platform_locator(obj: Any):
     return locator
 
 
-@dataclass
-class LocatorType:
-    CSS = 'css'
-    XPATH = 'xpath'
-    ID = 'id'
-    TEXT = 'text'
-
-
 def set_selenium_selector(obj: Any):
     """
     Sets selenium locator & locator type
@@ -110,9 +103,6 @@ def set_selenium_selector(obj: Any):
         obj.log_locator = f'{LocatorType.ID}={locator}'
 
 
-DEFAULT_MATCH = (f"{LocatorType.XPATH}=", f"{LocatorType.ID}=", f"{LocatorType.CSS}=", f"{LocatorType.TEXT}=")
-
-
 def set_playwright_locator(obj: Any):
     """
     Sets playwright locator & locator type

tests/static_tests/unit/test_selector_synchronizer.py

@@ -0,0 +1,53 @@
+from types import SimpleNamespace
+
+import pytest
+from selenium.webdriver.common.by import By
+
+from mops.utils.selector_synchronizer import set_selenium_selector, set_playwright_locator
+
+
+@pytest.mark.parametrize(
+    "locator_input, expected_locator, expected_locator_type, expected_log_locator",
+    [
+        ("xpath=//div", "//div", By.XPATH, "xpath=//div"),
+        ("text=Hello", '//*[contains(text(), "Hello")]', By.XPATH, "text=Hello"),
+        ("css=.class", ".class", By.CSS_SELECTOR, "css=.class"),
+        ("id=my_id", '[id="my_id"]', By.CSS_SELECTOR, "id=my_id"),
+        ("/html/body/div", "/html/body/div", By.XPATH, "xpath=/html/body/div"),
+        ("#my_element", "#my_element", By.CSS_SELECTOR, "css=#my_element"),
+        ("button", "button", By.CSS_SELECTOR, "css=button"),
+        ("div span", "div span", By.CSS_SELECTOR, "css=div span"),
+        ("Some text", '//*[contains(text(), "Some text")]', By.XPATH, "xpath=Some text"),
+        ("[href='/some/url']", "[href='/some/url']", By.CSS_SELECTOR, "css=[href='/some/url']"),
+    ],
+)
+def test_set_selenium_selector(locator_input, expected_locator, expected_locator_type, expected_log_locator):
+    mock_obj = SimpleNamespace()
+    mock_obj.locator = locator_input
+    set_selenium_selector(mock_obj)
+    assert mock_obj.locator == expected_locator
+    assert mock_obj.log_locator == expected_log_locator
+
+
+@pytest.mark.parametrize(
+    "locator_input, expected_locator, expected_log_locator",
+    [
+        ("xpath=//div", "xpath=//div", "xpath=//div"),
+        ("text=Hello", "text=Hello", "text=Hello"),
+        ("css=.class", "css=.class", "css=.class"),
+        ("id=my_id", "id=my_id", "id=my_id"),
+        ("/html/body/div", "xpath=/html/body/div", "xpath=/html/body/div"),
+        ("#my_element", "css=#my_element", "css=#my_element"),
+        ("button", "css=button", "css=button"),
+        ("div span", "text=div span", "text=div span"),
+        ("Some text", "text=Some text", "text=Some text"),
+        ("[href='/some/url']", "css=[href='/some/url']", "css=[href='/some/url']"),
+        ("", "id=", "id="),
+    ],
+)
+def test_set_playwright_locator(locator_input, expected_locator, expected_log_locator):
+    mock_obj = SimpleNamespace()
+    mock_obj.locator = locator_input
+    set_playwright_locator(mock_obj)
+    assert mock_obj.locator == expected_locator
+    assert mock_obj.log_locator == expected_log_locator