Merge branch 'autoscrape-labs:main' into issue-214

Author: LucasAlvws

CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2.7.0 (2025-08-22)
+
+### Feat
+
+- refactor WebElement methods to use a unified naming convention
+- add Response type and new bring_to_front method to Tab class
+- improve element interactability scripts
+
+### Fix
+
+- **browser**: add google-chrome-stable path for Arch Linux AUR package
+- run actions to fix badges
+- enforce combined condition logic in wait_until
+- **web_element**: raise WaitElementTimeout on wait_until timeout
+
+### Refactor
+
+- update command responses to use Response for empty responses
+- **webelement**: simplify wait_until condition mapping
+
 ## 2.6.0 (2025-08-10)
 
 ### Feat

README.md

@@ -47,6 +47,40 @@ We believe that powerful automation shouldn't require you to become an expert in
 
 ## What's New
 
+### WebElement: state waiting and new public APIs
+
+- New `wait_until(...)` on `WebElement` to await element states with minimal code:
+
+```python
+# Wait until it becomes visible OR the timeout expires
+await element.wait_until(is_visible=True, timeout=5)
+
+# Wait until it becomes interactable (visible, on top, receiving pointer events)
+await element.wait_until(is_interactable=True, timeout=10)
+```
+
+- Methods now public on `WebElement`:
+  - `is_visible()`
+    - Checks that the element has a visible area (> 0), isn’t hidden by CSS and is in the viewport (after `scroll_into_view()` when needed). Useful pre-check before interactions.
+  - `is_interactable()`
+    - “Click-ready” state: combines visibility, enabledness and pointer-event hit testing. Ideal for robust flows that avoid lost clicks.
+  - `is_on_top()`
+    - Verifies the element is the top hit-test target at the intended click point, avoiding overlays.
+  - `execute_script(script: str, return_by_value: bool = False)`
+    - Executes JavaScript in the element’s own context (where `this` is the element). Great for fine-tuning and quick inspections.
+
+```python
+# Visually outline the element via JS
+await element.execute_script("this.style.outline='2px solid #22d3ee'")
+
+# Confirm states
+visible = await element.is_visible()
+interactable = await element.is_interactable()
+on_top = await element.is_on_top()
+```
+
+These additions simplify waiting and state validation before clicking/typing, reducing flakiness and making automations more predictable.
+
 ### Browser-context HTTP requests - game changer for hybrid automation!
 Ever wished you could make HTTP requests that automatically inherit all your browser's session state? **Now you can!**<br>
 The `tab.request` property gives you a beautiful `requests`-like interface that executes HTTP calls directly in the browser's JavaScript context. This means every request automatically gets cookies, authentication headers, CORS policies, and session state, just as if the browser made the request itself.

README_zh.md

@@ -49,6 +49,40 @@ Pydoll 采用全新设计理念，从零构建，直接对接 Chrome DevTools Pr
 
 ## 最新功能
 
+### WebElement：状态等待与新的公共 API
+
+- 新增 `wait_until(...)` 用于等待元素状态，使用更简单：
+
+```python
+# 等待元素变为可见，直到超时
+await element.wait_until(is_visible=True, timeout=5)
+
+# 等待元素变为可交互（可见、位于顶层并可接收事件）
+await element.wait_until(is_interactable=True, timeout=10)
+```
+
+- 以下 `WebElement` 方法现已公开：
+  - `is_visible()`
+    - 判断元素是否具有可见区域、未被 CSS 隐藏，并在需要时滚动进入视口。适用于交互前的快速校验。
+  - `is_interactable()`
+    - “可点击”状态：综合可见性、启用状态与指针事件命中等条件，适合构建更稳健的交互流程。
+  - `is_on_top()`
+    - 检查元素在点击位置是否为顶部命中目标，避免被覆盖导致点击失效。
+  - `execute_script(script: str, return_by_value: bool = False)`
+    - 在元素上下文中执行 JavaScript（this 指向该元素），便于细粒度调整与快速检查。
+
+```python
+# 使用 JS 高亮元素
+await element.execute_script("this.style.outline='2px solid #22d3ee'")
+
+# 校验状态
+visible = await element.is_visible()
+interactable = await element.is_interactable()
+on_top = await element.is_on_top()
+```
+
+以上新增能力能显著简化“等待+验证”场景，降低自动化过程中的不稳定性，使用例更可预测。
+
 ### 浏览器上下文 HTTP 请求 - 混合自动化的游戏规则改变者！
 你是否曾经希望能够发出自动继承浏览器所有会话状态的 HTTP 请求？**现在你可以了！**<br>
 `tab.request` 属性为你提供了一个美观的 `requests` 风格接口，可在浏览器的 JavaScript 上下文中直接执行 HTTP 调用。这意味着每个请求都会自动获得 cookies、身份验证标头、CORS 策略和会话状态，就像浏览器本身发出请求一样。

cz.yaml

@@ -2,4 +2,4 @@
 commitizen:
   name: cz_conventional_commits
   tag_format: $version
-  version: 2.6.0
+  version: 2.7.0