Merge remote-tracking branch 'origin/master' into performance-improvements-version

# Conflicts:
#	mops/__init__.py
#	mops/base/element.py

Author: VladimirPodolian

.github/workflows/appium_android_tests.yml

@@ -3,14 +3,15 @@ name: Appium Android Chrome Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'tests/static_tests/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
 
 jobs:
   android-tests:

.github/workflows/appium_ios_tests.yml

@@ -3,14 +3,15 @@ name: Appium iOS Safari Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'tests/static_tests/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
 
 jobs:
   ios-tests:

.github/workflows/playwright_tests.yml

@@ -3,14 +3,15 @@ name: Playwright Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'tests/static_tests/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
 
 jobs:
   playwright-docker:

.github/workflows/selenium_safari_tests.yml

@@ -3,14 +3,16 @@ name: Selenium Safari Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'tests/static_tests/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
+
 jobs:
   selenium-safari:
     runs-on: macos-26

.github/workflows/selenium_tests.yml

@@ -3,14 +3,16 @@ name: Selenium Selenoid Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'tests/static_tests/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
+
 
 jobs:
   selenium-selenoid:

.github/workflows/static_tests.yml

@@ -3,13 +3,15 @@ name: Static Tests
 on:
   push:
     branches:
-      - '**'
+      - 'master'
     paths-ignore:
       - 'docs/**'
       - 'README.md'
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '.gitignore'
+  pull_request:
+
 
 jobs:
   static:

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <br>
 
+## v3.3.2
+*Release date: 2026-03-24*
+
+### Added
+- `Element.source_locator` attribute that preserves the original locator before platform-specific transformations
+
+---
+
 ## v3.3.1
 *Release date: 2026-01-05*
 

docs/source/element_object/key_features.md

@@ -39,3 +39,56 @@ particularly for negative checks (i.e., when an element is not present on the pa
 ## 3. Built-in waits
 Most methods automatically wait for specific element states.
 For example, the framework will wait until a web element becomes clickable before executing `click` method on it.
+
+---
+
+<br>
+
+
+## 4. Original locator preservation
+The `source_locator` attribute stores the original locator exactly as it was provided to `Element.__init__`,
+before any platform-specific resolution or framework-specific transformations.
+
+```{note}
+For **static** sub-elements, consider using the built-in parent mechanism instead —
+`Element` objects defined as class attributes of a `Group` automatically search within
+the Group locator (see {doc}`Group documentation <../group_object/index>`).
+
+`source_locator` is designed for cases where you need the **raw locator string** for
+dynamic XPath construction at runtime — something the parent mechanism cannot do.
+```
+
+**Example — dynamic table parsing:**
+
+```python
+from mops.base.group import Group
+from mops.base.element import Element
+
+
+class DataTable(Group):
+
+    def load(self):
+        row_locator = f'{self.source_locator}//tr'
+        row_elements = Element(row_locator, f'{self.name}: Rows').all_elements
+
+        self.rows = []
+        for index, _ in enumerate(row_elements):
+            cell_locator = f'({row_locator})[{index + 1}]/td'
+            cells = Element(cell_locator, f'{self.name}: Row {index} cells')
+            self.rows.append(cells)
+```
+
+Here `source_locator` is used to dynamically compose new XPath expressions
+via string concatenation. This cannot be achieved with the parent mechanism because:
+
+- The XPath grouping operator `(…)[n]` requires building the full expression as a single string.
+- New `Element` objects are created at runtime, not as class-level attributes.
+- After initialization, `locator` is transformed with platform prefixes
+  (e.g., `xpath=` for Playwright), making it unsuitable for string concatenation.
+
+```{note}
+`source_locator` preserves the exact type passed in: if a `Locator` dataclass was given, it stays a `Locator`;
+if a string was given, it stays the original string.
+The `locator` attribute, by contrast, is resolved to a platform-specific string and may be further modified
+(e.g., prefixed with `xpath=` for Playwright or converted to a CSS selector for ID-based locators in Selenium).
+```

mops/base/element.py

@@ -70,12 +70,13 @@ class Element(DriverMixin, InternalMixin, Logging, ElementABC, metaclass=Element
     It dynamically adapts to different driver types (Playwright, Appium, Selenium)
     and provides a unified interface for UI interactions.
     """
-
     _object: str = 'element'
     _initialized: bool = False
     _is_locator_configured: bool = False
     _base_cls: Type[PlayElement, MobileElement, WebElement]
 
+    source_locator: Union[Locator, str]
+
     def __new__(cls, *args, **kwargs):
         instance = super(Element, cls).__new__(cls)
         set_instance_frame(instance)
@@ -121,6 +122,7 @@ def __init__(
         """
         self.driver_wrapper = get_driver_wrapper_from_object(driver_wrapper)
 
+        self.source_locator = locator
         self.locator = locator
         self.name = name or locator
         self.parent = parent

tests/static_tests/integration/test_source_locator.py

@@ -0,0 +1,83 @@
+import pytest
+
+from mops.base.element import Element
+from mops.base.group import Group
+from mops.mixins.objects.locator import Locator
+from tests.static_tests.conftest import desktop_drivers, desktop_ids, mobile_drivers, mobile_ids
+
+
+xpath_locator = '//div[@class="test"]'
+css_locator = '.test-class'
+id_locator = 'test-id'
+ios_locator = 'ios_locator'
+android_locator = 'android_locator'
+mobile_locator = 'mobile_locator'
+
+multi_platform_locator = Locator(
+    default='default_locator',
+    desktop='desktop_locator',
+    mobile=mobile_locator,
+    ios=ios_locator,
+    android=android_locator,
+)
+
+
+class SourceLocatorGroup(Group):
+    def __init__(self):
+        super().__init__(xpath_locator, name='source locator group')
+
+    sub_element = Element(css_locator, name='sub element')
+    multi_element = Element(multi_platform_locator, name='multi element')
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_preserved_for_string_xpath(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(xpath_locator, name='xpath element')
+    assert element.source_locator == xpath_locator
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_preserved_for_string_css(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(css_locator, name='css element')
+    assert element.source_locator == css_locator
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_preserved_for_string_id(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(id_locator, name='id element')
+    assert element.source_locator == id_locator
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_differs_from_transformed_locator(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(xpath_locator, name='xpath element')
+    assert element.source_locator == xpath_locator
+    assert element.locator != xpath_locator or element.source_locator == element.locator
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_preserved_for_locator_dataclass(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(multi_platform_locator, name='multi element')
+    assert element.source_locator is multi_platform_locator
+
+
+@pytest.mark.parametrize('driver', mobile_drivers, ids=mobile_ids)
+def test_source_locator_preserved_for_locator_dataclass_mobile(driver, request):
+    request.getfixturevalue(driver)
+    element = Element(multi_platform_locator, name='multi element')
+    assert element.source_locator is multi_platform_locator
+    assert isinstance(element.locator, str)
+
+
+@pytest.mark.parametrize('driver', desktop_drivers, ids=desktop_ids)
+def test_source_locator_preserved_in_sub_elements(driver, request):
+    request.getfixturevalue(driver)
+    group = SourceLocatorGroup()
+    assert group.source_locator == xpath_locator
+    assert group.sub_element.source_locator == css_locator
+    assert group.multi_element.source_locator is multi_platform_locator