fix: map exception when try to take screenshot of an iframe

Author: thalissonvs

.github/workflows/tests.yml

@@ -22,6 +22,10 @@ jobs:
         run: |
           python -m pip install poetry
           poetry install
+      - name: Install Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 132
       - name: Run tests with coverage
         run: |
           poetry run pytest -s -x --cov=pydoll -vv --cov-report=xml

.gitignore

@@ -161,4 +161,7 @@ cython_debug/
 #.idea/
 
 .czrc
-.ruff_cache/
+.ruff_cache/
+
+# Dev test file
+dev_test_file.py

CHANGELOG.md

@@ -1,3 +1,38 @@
+## 2.8.1 (2025-09-27)
+
+### Fix
+
+- store the opened tab in the _tabs_opened dictionary
+- **elements**: correctly detect parenthesized XPath expressions
+
+### Refactor
+
+- simplify FindElementsMixin._get_expression_type startswith checks into single tuple
+
+## 2.8.0 (2025-08-28)
+
+### Feat
+
+- adding get_siblings_elements method
+- adding get_children_elements method
+- refactor Tab class to support optional WebSocket address handling
+- add WebSocket connection support for existing browser instances
+- add optional WebSocket address support in connection handler
+
+### Fix
+
+- add get siblings and get childen methods a raise_exc option
+- improving children and parent retrive docstring and creating a private generic method for then
+- using new execute_script public method
+- solving conflicts
+- rename pages fixtures files and adding a error test
+
+### Refactor
+
+- refactor Tab class to improve initialization and error handling
+- refactor Browser class to manage opened tabs and WebSocket setup
+- add new exception classes for connection and WebSocket errors
+
 ## 2.7.0 (2025-08-22)
 
 ### Feat

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright © 2025 <copyright holders>
+Copyright © 2025 AutoscrapeLabs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -47,6 +47,45 @@ We believe that powerful automation shouldn't require you to become an expert in
 
 ## What's New
 
+### Remote connections via WebSocket — control any Chrome from anywhere!
+
+You asked for it, we delivered. You can now connect to an already running browser remotely via its WebSocket address and use the full Pydoll API immediately.
+
+```python
+from pydoll.browser.chromium import Chrome
+
+chrome = Chrome()
+tab = await chrome.connect('ws://YOUR_HOST:9222/devtools/browser/XXXX')
+
+# Full power unlocked: navigation, element automation, requests, events…
+await tab.go_to('https://example.com')
+title = await tab.execute_script('return document.title')
+print(title)
+```
+
+This makes it effortless to run Pydoll against remote/CI browsers, containers, or shared debugging targets — no local launch required. Just point to the WS endpoint and automate.
+
+### Navigate the DOM like a pro: get_children_elements() and get_siblings_elements()
+
+Two delightful helpers to traverse complex layouts with intention:
+
+```python
+# Grab direct children of a container
+container = await tab.find(id='cards')
+cards = await container.get_children_elements(max_depth=1)
+
+# Want to go deeper? This will return children of children (and so on)
+elements = await container.get_children_elements(max_depth=2) 
+
+# Walk horizontal lists without re-querying the DOM
+active = await tab.find(class_name='item-active')
+siblings = await active.get_siblings_elements()
+
+print(len(cards), len(siblings))
+```
+
+Use them to cut boilerplate, express intent, and keep your scraping/automation logic clean and readable — especially in dynamic grids, lists and menus.
+
 ### WebElement: state waiting and new public APIs
 
 - New `wait_until(...)` on `WebElement` to await element states with minimal code:

README_zh.md

@@ -49,6 +49,45 @@ Pydoll 采用全新设计理念，从零构建，直接对接 Chrome DevTools Pr
 
 ## 最新功能
 
+### 通过 WebSocket 进行远程连接 —— 随时随地控制浏览器！
+
+现在你可以使用浏览器的 WebSocket 地址直接连接到已运行的实例，并立即使用完整的 Pydoll API：
+
+```python
+from pydoll.browser.chromium import Chrome
+
+chrome = Chrome()
+tab = await chrome.connect('ws://YOUR_HOST:9222/devtools/browser/XXXX')
+
+# 直接开干：导航、元素自动化、请求、事件…
+await tab.go_to('https://example.com')
+title = await tab.execute_script('return document.title')
+print(title)
+```
+
+这让你可以轻松对接远程/CI 浏览器、容器或共享调试目标——无需本地启动，只需指向 WS 端点即可自动化。
+
+### 像专业人士一样漫游 DOM：get_children_elements() 与 get_siblings_elements()
+
+两个让复杂布局遍历更优雅的小助手：
+
+```python
+# 获取容器的直接子元素
+container = await tab.find(id='cards')
+cards = await container.get_children_elements(max_depth=1)
+
+# 想更深入？这将返回子元素的子元素（以此类推）
+elements = await container.get_children_elements(max_depth=2) 
+
+# 在横向列表中无痛遍历兄弟元素
+active = await tab.find(class_name='item--active')
+siblings = await active.get_siblings_elements()
+
+print(len(cards), len(siblings))
+```
+
+用更少样板代码表达更多意图，特别适合动态网格、列表与菜单的场景，让抓取/自动化逻辑更清晰、更可读。
+
 ### WebElement：状态等待与新的公共 API
 
 - 新增 `wait_until(...)` 用于等待元素状态，使用更简单：
@@ -212,7 +251,7 @@ options.browser_preferences = {
 
 这种控制级别以前只有 Chrome 扩展开发者才能使用 - 现在它在你的自动化工具包中！
 
-查看[文档](https://autoscrape-labs.github.io/pydoll/features/custom-browser-preferences/)了解更多详情。
+查看[文档](https://pydoll.tech/docs/zh/features/#custom-browser-preferences/)了解更多详情。
 
 ### 新的 `get_parent_element()` 方法
 检索任何 WebElement 的父元素，使导航 DOM 结构更加容易：

cz.yaml

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

public/docs/features.md

@@ -57,6 +57,53 @@ Capture visual content from web pages:
 - **High-Quality PDF Export**: Generate PDF documents from web pages
 - **Custom Formatting**: Coming soon!
 
+## Remote Connections and Hybrid Automation
+
+### Connect to a running browser via WebSocket
+
+Control an already running browser remotely by pointing Pydoll to its DevTools WebSocket address.
+
+```python
+import asyncio
+from pydoll.browser.chromium import Chrome
+
+async def main():
+    chrome = Chrome()
+    tab = await chrome.connect('ws://YOUR_HOST:9222/devtools/browser/XXXX')
+
+    await tab.go_to('https://example.com')
+    title = await tab.execute_script('return document.title')
+    print(title)
+
+asyncio.run(main())
+```
+
+Perfect for CI, containers, remote hosts, or shared debugging targets—no local launch required. Just provide the WS endpoint and automate.
+
+### Bring your own CDP: wrap existing sessions with Pydoll objects
+
+If you already have your own CDP integration, you can still leverage Pydoll’s high-level API by wiring it to an existing DevTools session. As long as you know an element’s `objectId`, you can create a `WebElement` directly:
+
+```python
+from pydoll.connection import ConnectionHandler
+from pydoll.elements.web_element import WebElement
+
+# Your DevTools WebSocket endpoint and an element objectId you resolved via CDP
+ws = 'ws://YOUR_HOST:9222/devtools/page/ABCDEF...'
+object_id = 'REMOTE_ELEMENT_OBJECT_ID'
+
+connection_handler = ConnectionHandler(ws_address=ws)
+element = WebElement(object_id=object_id, connection_handler=connection_handler)
+
+# Use the full WebElement API immediately
+visible = await element.is_visible()
+await element.wait_until(is_interactable=True, timeout=10)
+await element.click()
+text = await element.text
+```
+
+This hybrid approach lets you blend your low-level CDP tooling (for discovery, instrumentation, or custom flows) with Pydoll’s ergonomic element API.
+
 ## Intuitive Element Finding
 
 Pydoll v2.0+ introduces a revolutionary approach to finding elements that's both more intuitive and more powerful than traditional selector-based methods.
@@ -137,6 +184,44 @@ async def query_examples():
 asyncio.run(query_examples())
 ```
 
+### DOM Traversal Helpers: get_children_elements() and get_siblings_elements()
+
+These helpers let you traverse the DOM tree from a known anchor, preserving scope and intent.
+
+- get_children_elements(max_depth: int = 1, tag_filter: list[str] | None = None, raise_exc: bool = False) -> list[WebElement]
+  - Returns descendants up to max_depth using pre-order traversal (direct children first, then their descendants)
+  - max_depth=1 returns only direct children; 2 includes grandchildren, and so on
+  - tag_filter restricts results to specific tags (use lowercase names, e.g. ['a', 'li'])
+  - raise_exc=True raises ElementNotFound if the underlying script fails to resolve
+
+- get_siblings_elements(tag_filter: list[str] | None = None, raise_exc: bool = False) -> list[WebElement]
+  - Returns elements sharing the same parent, excluding the current element
+  - tag_filter narrows by tag; order follows the parent’s child order
+
+```python
+# Direct children in document order
+container = await tab.find(id='cards')
+children = await container.get_children_elements(max_depth=1)
+
+# Include grandchildren
+descendants = await container.get_children_elements(max_depth=2)
+
+# Filter by tag
+links = await container.get_children_elements(max_depth=4, tag_filter=['a'])
+
+# Horizontal traversal
+active = await tab.find(class_name='item-active')
+siblings = await active.get_siblings_elements()
+link_siblings = await active.get_siblings_elements(tag_filter=['a'])
+```
+
+Performance and correctness notes:
+
+- DOM is a tree: breadth expands quickly with depth. Prefer small max_depth values and apply tag_filter to minimize work.
+- Ordering: children follow document order; siblings follow the parent’s order for stable iteration.
+- iFrames: each iframe has its own tree. Use `tab.get_frame(iframe_element)` to traverse inside the frame, then call these helpers there.
+- Large documents: deep traversals can touch many nodes. Combine shallow traversal with targeted `find()`/`query()` on subtree anchors for best performance.
+
 ## Native Cloudflare Captcha Bypass
 
 !!! warning "Important Information About Captcha Bypass"
@@ -440,12 +525,8 @@ async def main():
     async with Chrome() as browser:
         # Start the browser once
         await browser.start()
-        
-        # Create partial function with browser parameter
-        scrape_with_browser = partial(scrape_page, browser)
-        
         # Process all URLs concurrently using the same browser
-        results = await asyncio.gather(*(scrape_with_browser(url) for url in urls))
+        results = await asyncio.gather(*(scrape_page(browser, url) for url in urls))
 
     # Print results
     for result in results: