Merge pull request #201 from autoscrape-labs/feat/get-parent-element

feat: add method to retrieve parent element and its attributes

Author: thalissonvs

pydoll/constants.py

@@ -119,6 +119,12 @@ class Scripts:
         }
     """
 
+    GET_PARENT_NODE = """
+        function() {
+            return this.parentElement;
+        }
+    """
+
 
 class Key(tuple[str, int], Enum):
     BACKSPACE = ('Backspace', 8)

pydoll/elements/mixins/find_elements_mixin.py

@@ -205,18 +205,13 @@ async def _find_element(
             EvaluateResponse, CallFunctionOnResponse
         ] = await self._execute_command(command)
 
-        if not response_for_command.get('result', {}).get('result', {}).get('objectId'):
+        if not self._has_object_id_key(response_for_command):
             if raise_exc:
                 raise ElementNotFound()
             return None
 
         object_id = response_for_command['result']['result']['objectId']
-        node_description = await self._describe_node(object_id=object_id)
-        attributes = node_description.get('attributes', [])
-
-        tag_name = node_description.get('nodeName', '').lower()
-        attributes.extend(['tag_name', tag_name])
-
+        attributes = await self._get_object_attributes(object_id=object_id)
         return create_web_element(object_id, self._connection_handler, by, value, attributes)  # type: ignore
 
     async def _find_elements(
@@ -280,6 +275,16 @@ async def _find_elements(
             )
         return elements
 
+    async def _get_object_attributes(self, object_id: str) -> list[str]:
+        """
+        Get attributes of a DOM node.
+        """
+        node_description = await self._describe_node(object_id=object_id)
+        attributes = node_description.get('attributes', [])
+        tag_name = node_description.get('nodeName', '').lower()
+        attributes.extend(['tag_name', tag_name])
+        return attributes
+
     def _get_by_and_value(  # noqa: PLR0913, PLR0917
         self,
         by_map: dict[str, By],
@@ -491,3 +496,10 @@ def _ensure_relative_xpath(xpath: str) -> str:
         Converts absolute XPath to relative for context-based searches.
         """
         return f'.{xpath}' if not xpath.startswith('.') else xpath
+
+    @staticmethod
+    def _has_object_id_key(response: Union[EvaluateResponse, CallFunctionOnResponse]) -> bool:
+        """
+        Check if response has objectId key.
+        """
+        return bool(response.get('result', {}).get('result', {}).get('objectId'))

pydoll/elements/web_element.py

@@ -23,6 +23,7 @@
 from pydoll.elements.mixins import FindElementsMixin
 from pydoll.exceptions import (
     ElementNotAFileInput,
+    ElementNotFound,
     ElementNotInteractable,
     ElementNotVisible,
 )
@@ -130,6 +131,16 @@ async def get_bounds_using_js(self) -> dict[str, int]:
         response = await self._execute_script(Scripts.BOUNDS, return_by_value=True)
         return json.loads(response['result']['result']['value'])
 
+    async def get_parent_element(self) -> 'WebElement':
+        """Element's parent element."""
+        result = await self._execute_script(Scripts.GET_PARENT_NODE)
+        if not self._has_object_id_key(result):
+            raise ElementNotFound(f'Parent element not found for element: {self}')
+
+        object_id = result['result']['result']['objectId']
+        attributes = await self._get_object_attributes(object_id=object_id)
+        return WebElement(object_id, self._connection_handler, attributes_list=attributes)
+
     async def take_screenshot(self, path: str, quality: int = 100):
         """
         Capture screenshot of this element only.
@@ -345,11 +356,13 @@ async def press_keyboard_key(
 
     async def _click_option_tag(self):
         """Specialized method for clicking <option> elements in dropdowns."""
-        await self._execute_command(RuntimeCommands.call_function_on(
-            object_id=self._object_id,
-            function_declaration=Scripts.CLICK_OPTION_TAG,
-            return_by_value=True,
-        ))
+        await self._execute_command(
+            RuntimeCommands.call_function_on(
+                object_id=self._object_id,
+                function_declaration=Scripts.CLICK_OPTION_TAG,
+                return_by_value=True,
+            )
+        )
 
     async def _is_element_visible(self):
         """Check if element is visible using comprehensive JavaScript visibility test."""

tests/test_web_element.py

@@ -314,6 +314,130 @@ async def test_type_text_default_interval(self, input_element):
         mock_sleep.assert_called_with(0.1)  # Default interval
         assert input_element.click.call_count == 1
 
+    @pytest.mark.asyncio
+    async def test_get_parent_element_success(self, web_element):
+        """Test successful parent element retrieval."""
+        script_response = {
+            'result': {
+                'result': {
+                    'objectId': 'parent-object-id'
+                }
+            }
+        }
+        describe_response = {
+            'result': {
+                'node': {
+                    'nodeName': 'DIV',
+                    'attributes': ['id', 'parent-container', 'class', 'container']
+                }
+            }
+        }
+        web_element._connection_handler.execute_command.side_effect = [
+            script_response,  # Script execution
+            describe_response,  # Describe node
+        ]
+        
+        parent_element = await web_element.get_parent_element()
+
+        assert isinstance(parent_element, WebElement)
+        assert parent_element._object_id == 'parent-object-id'
+        assert parent_element._attributes == {
+            'id': 'parent-container',
+            'class_name': 'container',
+            'tag_name': 'div'
+        }
+        web_element._connection_handler.execute_command.assert_called()
+
+    @pytest.mark.asyncio
+    async def test_get_parent_element_not_found(self, web_element):
+        """Test parent element not found raises ElementNotFound."""
+        script_response = {
+            'result': {
+                'result': {}  # No objectId
+            }
+        }
+
+        web_element._connection_handler.execute_command.return_value = script_response
+
+        with pytest.raises(ElementNotFound, match='Parent element not found for element:'):
+            await web_element.get_parent_element()
+
+    @pytest.mark.asyncio
+    async def test_get_parent_element_with_complex_attributes(self, web_element):
+        """Test parent element with complex attribute list."""
+        script_response = {
+            'result': {
+                'result': {
+                    'objectId': 'complex-parent-id'
+                }
+            }
+        }
+
+        describe_response = {
+            'result': {
+                'node': {
+                    'nodeName': 'SECTION',
+                    'attributes': [
+                        'id', 'main-section',
+                        'class', 'content-wrapper',
+                        'data-testid', 'parent-element',
+                        'aria-label', 'Main content area'
+                    ]
+                }
+            }
+        }
+        
+        web_element._connection_handler.execute_command.side_effect = [
+            script_response,
+            describe_response,
+        ]
+        
+        parent_element = await web_element.get_parent_element()
+
+        assert isinstance(parent_element, WebElement)
+        assert parent_element._object_id == 'complex-parent-id'
+        assert parent_element._attributes == {
+            'id': 'main-section',
+            'class_name': 'content-wrapper',
+            'data-testid': 'parent-element',
+            'aria-label': 'Main content area',
+            'tag_name': 'section'
+        }
+
+    @pytest.mark.asyncio
+    async def test_get_parent_element_root_element(self, web_element):
+        """Test getting parent of root element (should return document body)."""
+        script_response = {
+            'result': {
+                'result': {
+                    'objectId': 'body-object-id'
+                }
+            }
+        }
+        
+        describe_response = {
+            'result': {
+                'node': {
+                    'nodeName': 'BODY',
+                    'attributes': ['class', 'page-body']
+                }
+            }
+        }
+        
+        web_element._connection_handler.execute_command.side_effect = [
+            script_response,
+            describe_response,
+        ]
+        
+        parent_element = await web_element.get_parent_element()
+
+        assert isinstance(parent_element, WebElement)
+        assert parent_element._object_id == 'body-object-id'
+        assert parent_element._attributes == {
+            'class_name': 'page-body',
+            'tag_name': 'body'
+        }
+
 
 class TestWebElementKeyboardInteraction:
     """Test keyboard interaction methods."""