Merge pull request #234 from autoscrape-labs/codex/use-commitizen-style-for-issue-#222

feat: add wait_until method to WebElement

Author: thalissonvs

docs/deep-dive/webelement-domain.md

@@ -73,6 +73,7 @@ classDiagram
         +get_attribute(name: str)
         +set_input_files(files: list[str])
         +scroll_into_view()
+        +wait_until()
         +take_screenshot(path: str)
         +text
         +inner_html
@@ -373,8 +374,19 @@ is_visible = await element._is_element_visible()
 
 # Check if element is the topmost at its position
 is_on_top = await element._is_element_on_top()
+
+# Check if element can be interacted with
+is_interactable = await element._is_element_interactable()
+
+# Wait until the element is ready for interaction
+await element.wait_until(is_visible=True, is_interactable=True, timeout=5)
+
+# Raises ``WaitElementTimeout`` if the conditions aren't met in time.
 ```
 
+If both ``is_visible`` and ``is_interactable`` are set to ``True``, the element
+must satisfy **both** conditions to proceed.
+
 These verifications are crucial for reliable automation, ensuring that elements can be interacted with before attempting operations.
 
 ## Position and Scrolling

docs/zh/deep-dive/webelement-domain.md

@@ -74,6 +74,7 @@ classDiagram
         +get_attribute(name: str)
         +set_input_files(files: list[str])
         +scroll_into_view()
+        +wait_until()
         +take_screenshot(path: str)
         +text
         +inner_html
@@ -366,7 +367,7 @@ async def _execute_script(
 
 ## 元素状态验证
 
-WebElement 提供了检查元素可见性和可交互性的方法：
+WebElement 提供了检查元素可见性和可交互性的方法，并可等待这些条件满足：
 
 
 ```python
@@ -375,8 +376,18 @@ is_visible = await element._is_element_visible()
 
 # Check if element is the topmost at its position
 is_on_top = await element._is_element_on_top()
+
+# Check if element can be interacted with
+is_interactable = await element._is_element_interactable()
+
+# Wait until the element is ready for interaction
+await element.wait_until(is_visible=True, is_interactable=True, timeout=5)
+
+# 未在限定时间内满足条件时会抛出 ``WaitElementTimeout``。
 ```
 
+如果同时传入 ``is_visible`` 和 ``is_interactable``，必须同时满足这两个条件。
+
 这些验证对于实现可靠的自动化至关重要，可在尝试操作前确保元素可被交互。
 
 ## 位置与滚动

pydoll/constants.py

@@ -25,11 +25,39 @@ class Scripts:
     ELEMENT_ON_TOP = """
     function() {
         const rect = this.getBoundingClientRect();
-        const elementFromPoint = document.elementFromPoint(
-            rect.x + rect.width / 2,
-            rect.y + rect.height / 2
-        );
-        return elementFromPoint === this;
+        const x = rect.x + rect.width / 2;
+        const y = rect.y + rect.height / 2;
+        const elementFromPoint = document.elementFromPoint(x, y);
+        if (!elementFromPoint) {
+            return false;
+        }
+        return elementFromPoint === this || this.contains(elementFromPoint);
+    }
+    """
+
+    ELEMENT_INTERACTIVE = """
+    function() {
+        const style = window.getComputedStyle(this);
+        const rect = this.getBoundingClientRect();
+        if (
+            rect.width <= 0 ||
+            rect.height <= 0 ||
+            style.visibility === 'hidden' ||
+            style.display === 'none' ||
+            style.pointerEvents === 'none'
+        ) {
+            return false;
+        }
+        const x = rect.x + rect.width / 2;
+        const y = rect.y + rect.height / 2;
+        const elementFromPoint = document.elementFromPoint(x, y);
+        if (!elementFromPoint || (elementFromPoint !== this && !this.contains(elementFromPoint))) {
+            return false;
+        }
+        if (this.disabled) {
+            return false;
+        }
+        return true;
     }
     """
 

pydoll/elements/web_element.py

@@ -21,6 +21,7 @@
     ElementNotFound,
     ElementNotInteractable,
     ElementNotVisible,
+    WaitElementTimeout,
 )
 from pydoll.protocol.dom.methods import (
     GetBoxModelResponse,
@@ -180,6 +181,50 @@ async def scroll_into_view(self):
         command = DomCommands.scroll_into_view_if_needed(object_id=self._object_id)
         await self._execute_command(command)
 
+    async def wait_until(
+        self,
+        *,
+        is_visible: bool = False,
+        is_interactable: bool = False,
+        timeout: int = 0,
+    ):
+        """Wait for element to meet specified conditions.
+
+        Raises:
+            ValueError: If neither ``is_visible`` nor ``is_interactable`` is True.
+            WaitElementTimeout: If the condition is not met within ``timeout``.
+        """
+        checks_map = [
+            (is_visible, self._is_element_visible),
+            (is_interactable, self._is_element_interactable),
+        ]
+        checks = [func for flag, func in checks_map if flag]
+        if not checks:
+            raise ValueError(
+                'At least one of is_visible or is_interactable must be True'
+            )
+
+        condition_parts = []
+        if is_visible:
+            condition_parts.append('visible')
+        if is_interactable:
+            condition_parts.append('interactable')
+        condition_msg = ' and '.join(condition_parts)
+
+        loop = asyncio.get_event_loop()
+        start_time = loop.time()
+        while True:
+            results = await asyncio.gather(*(check() for check in checks))
+            if all(results):
+                return
+
+            if timeout and loop.time() - start_time > timeout:
+                raise WaitElementTimeout(
+                    f'Timed out waiting for element to become {condition_msg}'
+                )
+
+            await asyncio.sleep(0.5)
+
     async def click_using_js(self):
         """
         Click element using JavaScript click() method.
@@ -375,6 +420,13 @@ async def _is_element_on_top(self):
         result = await self._execute_script(Scripts.ELEMENT_ON_TOP, return_by_value=True)
         return result['result']['result']['value']
 
+    async def _is_element_interactable(self):
+        """Check if element is interactable based on visibility and position."""
+        result = await self._execute_script(
+            Scripts.ELEMENT_INTERACTIVE, return_by_value=True
+        )
+        return result['result']['result']['value']
+
     async def _execute_script(self, script: str, return_by_value: bool = False):
         """
         Execute JavaScript in element context.

tests/test_web_element.py

@@ -719,10 +719,113 @@ async def test_is_element_on_top_false(self, web_element):
         web_element._execute_script = AsyncMock(
             return_value={'result': {'result': {'value': False}}}
         )
-        
+
         result = await web_element._is_element_on_top()
         assert result is False
 
+    @pytest.mark.asyncio
+    async def test_is_element_interactable_true(self, web_element):
+        """Test _is_element_interactable returns True."""
+        web_element._execute_script = AsyncMock(
+            return_value={'result': {'result': {'value': True}}}
+        )
+
+        result = await web_element._is_element_interactable()
+        assert result is True
+
+    @pytest.mark.asyncio
+    async def test_is_element_interactable_false(self, web_element):
+        """Test _is_element_interactable returns False."""
+        web_element._execute_script = AsyncMock(
+            return_value={'result': {'result': {'value': False}}}
+        )
+
+        result = await web_element._is_element_interactable()
+        assert result is False
+
+
+class TestWebElementWaitUntil:
+    """Test wait_until method."""
+
+    @pytest.mark.asyncio
+    async def test_wait_until_visible_success(self, web_element):
+        """Test wait_until succeeds when element becomes visible."""
+        web_element._is_element_visible = AsyncMock(side_effect=[False, True])
+
+        with patch('asyncio.sleep') as mock_sleep, \
+             patch('asyncio.get_event_loop') as mock_loop:
+            mock_loop.return_value.time.side_effect = [0, 0.5]
+
+            await web_element.wait_until(is_visible=True, timeout=2)
+
+        assert web_element._is_element_visible.call_count == 2
+        mock_sleep.assert_called_once_with(0.5)
+
+    @pytest.mark.asyncio
+    async def test_wait_until_visible_timeout(self, web_element):
+        """Test wait_until raises WaitElementTimeout when visibility not met."""
+        web_element._is_element_visible = AsyncMock(return_value=False)
+
+        with patch('asyncio.sleep') as mock_sleep, \
+             patch('asyncio.get_event_loop') as mock_loop:
+            mock_loop.return_value.time.side_effect = [0, 0.5, 1.0, 1.5, 2.1]
+
+            with pytest.raises(
+                WaitElementTimeout, match='element to become visible'
+            ):
+                await web_element.wait_until(is_visible=True, timeout=2)
+
+        assert mock_sleep.call_count == 3
+
+    @pytest.mark.asyncio
+    async def test_wait_until_interactable_success(self, web_element):
+        """Test wait_until succeeds when element becomes interactable."""
+        web_element._is_element_interactable = AsyncMock(return_value=True)
+
+        await web_element.wait_until(is_interactable=True, timeout=1)
+
+        web_element._is_element_interactable.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_wait_until_interactable_timeout(self, web_element):
+        """Test wait_until raises WaitElementTimeout when not interactable."""
+        web_element._is_element_interactable = AsyncMock(return_value=False)
+
+        with patch('asyncio.sleep') as mock_sleep, \
+             patch('asyncio.get_event_loop') as mock_loop:
+            mock_loop.return_value.time.side_effect = [0, 0.5, 1.1]
+
+            with pytest.raises(
+                WaitElementTimeout, match='element to become interactable'
+            ):
+                await web_element.wait_until(is_interactable=True, timeout=1)
+
+        mock_sleep.assert_called_once_with(0.5)
+
+    @pytest.mark.asyncio
+    async def test_wait_until_visible_and_interactable(self, web_element):
+        """Test wait_until requires both conditions when both are True."""
+        web_element._is_element_visible = AsyncMock(side_effect=[False, True])
+        web_element._is_element_interactable = AsyncMock(side_effect=[False, True])
+
+        with patch('asyncio.sleep') as mock_sleep, \
+             patch('asyncio.get_event_loop') as mock_loop:
+            mock_loop.return_value.time.side_effect = [0, 0.5, 1.0]
+
+            await web_element.wait_until(
+                is_visible=True, is_interactable=True, timeout=2
+            )
+
+        assert web_element._is_element_visible.call_count == 2
+        assert web_element._is_element_interactable.call_count == 2
+        mock_sleep.assert_called_once_with(0.5)
+
+    @pytest.mark.asyncio
+    async def test_wait_until_no_conditions(self, web_element):
+        """Test wait_until raises ValueError when no condition specified."""
+        with pytest.raises(ValueError):
+            await web_element.wait_until()
+
 
 class TestWebElementUtilityMethods:
     """Test utility and helper methods."""