dp-cli 0.6.3__tar.gz → 0.7.0__tar.gz

dp_cli-0.7.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, mofanx
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{dp_cli-0.6.3 → dp_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.6.3
+Version: 0.7.0
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -13,6 +13,7 @@ Classifier: Topic :: Utilities
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: DrissionPage>=4.0
 Requires-Dist: click>=8.0
 Requires-Dist: aiohttp>=3.9
@@ -23,6 +24,7 @@ Requires-Dist: pytest>=7.4.0; extra == "test"
 Requires-Dist: pytest-cov>=4.1.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
 Requires-Dist: pytest-mock>=3.11.0; extra == "test"
+Dynamic: license-file
 
 # dp-cli
 
@@ -278,7 +280,8 @@ dp_cli/
     ├── snapshot_cmd.py  # snapshot / extract / query / find / inspect
     ├── element.py       # click / fill / select / hover / drag / check / upload / count
     ├── keyboard.py      # press / type / scroll / scroll-to / autoscroll
-    ├── page.py          # screenshot / pdf / eval / wait (idle/loaded/url/title) / dialog
+    ├── page.py          # screenshot / pdf / eval / wait / console / dialog
+    ├── assert_cmd.py    # assert-text / assert-url / assert-visible / assert-count
     ├── tab.py           # tab-list / tab-new / tab-select / tab-close
     ├── storage.py       # cookie-* / localstorage-* / sessionstorage-*
     ├── network.py       # listen / listen-stop / http-get / http-post
@@ -287,7 +290,7 @@ dp_cli/
 
 ## Documentation
 
-See [`skills/SKILL.md`](skills/SKILL.md) for full workflow guide and [`skills/references/commands.md`](skills/references/commands.md) for complete command reference.
+See [`skills/dp-cli/SKILL.md`](skills/dp-cli/SKILL.md) for full workflow guide and [`skills/dp-cli/references/commands.md`](skills/dp-cli/references/commands.md) for complete command reference. Exit-code contract: [`ERROR_CODES.md`](ERROR_CODES.md).
 
 ## License
 

{dp_cli-0.6.3 → dp_cli-0.7.0}/README.md

@@ -252,7 +252,8 @@ dp_cli/
     ├── snapshot_cmd.py  # snapshot / extract / query / find / inspect
     ├── element.py       # click / fill / select / hover / drag / check / upload / count
     ├── keyboard.py      # press / type / scroll / scroll-to / autoscroll
-    ├── page.py          # screenshot / pdf / eval / wait (idle/loaded/url/title) / dialog
+    ├── page.py          # screenshot / pdf / eval / wait / console / dialog
+    ├── assert_cmd.py    # assert-text / assert-url / assert-visible / assert-count
     ├── tab.py           # tab-list / tab-new / tab-select / tab-close
     ├── storage.py       # cookie-* / localstorage-* / sessionstorage-*
     ├── network.py       # listen / listen-stop / http-get / http-post
@@ -261,7 +262,7 @@ dp_cli/
 
 ## Documentation
 
-See [`skills/SKILL.md`](skills/SKILL.md) for full workflow guide and [`skills/references/commands.md`](skills/references/commands.md) for complete command reference.
+See [`skills/dp-cli/SKILL.md`](skills/dp-cli/SKILL.md) for full workflow guide and [`skills/dp-cli/references/commands.md`](skills/dp-cli/references/commands.md) for complete command reference. Exit-code contract: [`ERROR_CODES.md`](ERROR_CODES.md).
 
 ## License
 

{dp_cli-0.6.3 → dp_cli-0.7.0}/dp_cli/bridge.py

@@ -97,14 +97,14 @@ class CDPBridge:
             for ws in list(self._browser_clients):
                 try:
                     await ws.close(code=1011, message=b'upstream closed')
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('close downstream ws failed: %s', e)
             self._browser_clients.clear()
             for sid, ws in list(self._session_to_client.items()):
                 try:
                     await ws.close(code=1011, message=b'upstream closed')
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('close session ws failed: %s', e)
             self._session_to_client.clear()
             self.ws = None
             self._connected_evt.clear()
@@ -144,8 +144,8 @@ class CDPBridge:
             try:
                 if not client_ws.closed:
                     await client_ws.send_str(json.dumps(ev))
-            except Exception:
-                pass
+            except Exception as e:
+                log.debug('forward event to client failed: %s', e)
             return
 
         if not sess_id:
@@ -154,8 +154,8 @@ class CDPBridge:
                 try:
                     if not c.closed:
                         await c.send_str(ev_str)
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('broadcast event failed: %s', e)
 
     async def call(self, method: str, params: dict | None = None,
                    session_id: str | None = None) -> dict:
@@ -200,8 +200,8 @@ class CDPBridge:
                 err = {'id': client_id, 'error': {'code': -32000, 'message': str(e)}}
                 try:
                     await client_ws.send_str(json.dumps(err))
-                except Exception:
-                    pass
+                except Exception as e2:
+                    log.debug('send error reply failed: %s', e2)
 
     async def attach_page_client(self, target_id: str,
                                  client_ws: web.WebSocketResponse) -> str | None:
@@ -386,8 +386,8 @@ async def handle_ws(request: web.Request) -> web.StreamResponse:
                 try:
                     payload = json.loads(msg.data)
                     await bridge.forward_from_client(payload, client_ws, session_id)
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('forward client message failed: %s', e)
             elif msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED,
                               aiohttp.WSMsgType.ERROR):
                 break
@@ -479,14 +479,14 @@ async def main_async(user_data_dir: Path, host: str, port: int) -> None:
                 continue
             try:
                 signal.signal(sig, _win_signal_handler)
-            except (ValueError, OSError):
-                pass
+            except (ValueError, OSError) as e:
+                log.debug('register signal handler failed: %s', e)
     else:
         for sig in (signal.SIGINT, signal.SIGTERM):
             try:
                 loop.add_signal_handler(sig, stop_evt.set)
-            except NotImplementedError:
-                pass
+            except NotImplementedError as e:
+                log.debug('add_signal_handler unsupported: %s', e)
     try:
         await stop_evt.wait()
     finally:

{dp_cli-0.6.3 → dp_cli-0.7.0}/dp_cli/bridge_manager.py

@@ -24,6 +24,8 @@ import sys
 import time
 from pathlib import Path
 
+from dp_cli.logs import debug
+
 IS_WINDOWS = sys.platform == 'win32'
 
 
@@ -74,8 +76,8 @@ def _win_terminate(pid: int) -> None:
             check=False,
             timeout=5,
         )
-    except Exception:
-        pass
+    except Exception as e:
+        debug(f'taskkill pid={pid} 失败', e)
 
 
 _READY_RE = re.compile(r'^BRIDGE_READY host=(?P<host>\S+) port=(?P<port>\d+)\s*$')
@@ -113,8 +115,8 @@ def detect_inspect_mode(port: int, timeout: float = 2.0) -> bool:
         # 经典模式 /json/version 返回 dict，含 Browser 字段
         if isinstance(data, dict) and 'Browser' in data:
             return False
-    except Exception:
-        pass
+    except Exception as e:
+        debug(f'/json/version 响应解析失败，按 inspect 模式处理: port={port}', e)
     return True
 
 
@@ -166,8 +168,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
             for line in proc.stderr:
                 with stderr_lock:
                     stderr_buf.append(line)
-        except Exception:
-            pass
+        except Exception as e:
+            debug('bridge stderr 读取线程结束异常', e)
 
     stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
     stderr_thread.start()
@@ -207,8 +209,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
     except Exception:
         try:
             proc.terminate()
-        except Exception:
-            pass
+        except Exception as e:
+            debug('bridge 启动失败后 terminate 失败', e)
         raise
 
     # ready 后让 bridge 的 stdout 继续被 drain，避免管道阻塞。
@@ -217,8 +219,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
         try:
             for _ in stream:
                 pass
-        except Exception:
-            pass
+        except Exception as e:
+            debug('stdout drain 线程结束异常', e)
 
     if proc.stdout:
         threading.Thread(target=_drain, args=(proc.stdout,), daemon=True).start()
@@ -256,8 +258,8 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
         # 1) 优雅: 给整个进程组发 CTRL_BREAK_EVENT
         try:
             os.kill(pid, signal.CTRL_BREAK_EVENT)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'CTRL_BREAK_EVENT pid={pid} 失败', e)
 
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
@@ -276,8 +278,8 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
     except (ProcessLookupError, PermissionError, OSError):
         try:
             os.kill(pid, signal.SIGTERM)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'SIGTERM pid={pid} 失败', e)
 
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
@@ -291,7 +293,7 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
     except Exception:
         try:
             os.kill(pid, signal.SIGKILL)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'SIGKILL pid={pid} 失败', e)
     time.sleep(0.1)
     return not is_bridge_alive(pid)

{dp_cli-0.6.3 → dp_cli-0.7.0}/dp_cli/commands/__init__.py

@@ -2,9 +2,11 @@
 from dp_cli.commands import (
     browser, snapshot_cmd, element, keyboard,
     page, tab, storage, network, record, misc,
+    assert_cmd, emulate, observe,
 )
 
-_MODULES = [browser, snapshot_cmd, element, keyboard, page, tab, storage, network, record, misc]
+_MODULES = [browser, snapshot_cmd, element, keyboard, page, tab, storage, network, record, misc,
+            assert_cmd, emulate, observe]
 
 
 def register_all(cli):

{dp_cli-0.6.3 → dp_cli-0.7.0}/dp_cli/commands/_utils.py

@@ -8,7 +8,7 @@ from time import perf_counter, sleep as _sleep
 import click
 
 from dp_cli.session import get_browser, load_refs, load_session, save_session
-from dp_cli.output import error
+from dp_cli.output import error, debug
 
 
 def normalize_url(url: str) -> str:
@@ -25,6 +25,30 @@ def session_option(f):
                         help='会话名称，默认 default', show_default=True)(f)
 
 
+def frame_option(f):
+    return click.option('--frame', default=None,
+                        help='限定在 iframe 内查找元素（值为 iframe 的定位器，'
+                             '支持 css:/xpath:/pw:/ref:），如 --frame "css:iframe"')(f)
+
+
+def frame_ctx(page, frame_loc: str = None, session: str = 'default'):
+    """frame_loc 为 None 时返回 page 本身，否则返回该 iframe 的 frame 上下文。
+
+    返回对象（ChromiumFrame）同样提供 ele()/eles()，可直接替换 page 使用。
+    找不到 iframe 时 error(ELEMENT_NOT_FOUND) 退出。
+    """
+    if not frame_loc:
+        return page
+    loc = resolve_locator(frame_loc, session, page)
+    fr = page.get_frame(loc, timeout=3)
+    # 按类名判定：真实 NoneElement.__getattr__ 对任意属性抛
+    # ElementNotFoundError（非 AttributeError），getattr 默认值挡不住
+    if fr is None or fr.__class__.__name__ == 'NoneElement':
+        error(f'iframe 未找到: {frame_loc}', code='ELEMENT_NOT_FOUND')
+        return page
+    return fr
+
+
 def _get_page(session: str, raw: bool = False, inject_recording: bool = True):
     """获取页面对象，失败则 error 退出。
 
@@ -72,15 +96,31 @@ def _get_page(session: str, raw: bool = False, inject_recording: bool = True):
                           langs=stealth_cfg.get('langs'),
                           webgl_vendor=stealth_cfg.get('webgl_vendor'),
                           webgl_renderer=stealth_cfg.get('webgl_renderer'))
-        except Exception:
-            pass  # 不能让 stealth 失败阻塞常规命令
+        except Exception as e:
+            # 不能让 stealth 失败阻塞常规命令
+            debug('stealth 重注入失败', e)
 
     if inject_recording and sess.get('recording'):
         try:
             from dp_cli.recorder import inject_recorder
             inject_recorder(target)
-        except Exception:
-            pass
+        except Exception as e:
+            debug('录制器重注入失败', e)
+
+    # 会话级 CDP override 重放（emulate/intercept 每条命令重新应用）
+    from dp_cli.commands.emulate import _apply_emulate, _apply_intercept
+    emulate_cfg = sess.get('emulate')
+    if emulate_cfg:
+        try:
+            _apply_emulate(target, emulate_cfg)
+        except Exception as e:
+            debug('emulate 重放失败', e)
+    intercept_cfg = sess.get('intercept')
+    if intercept_cfg:
+        try:
+            _apply_intercept(target, intercept_cfg)
+        except Exception as e:
+            debug('intercept 重放失败', e)
 
     return target
 

dp_cli-0.7.0/dp_cli/commands/assert_cmd.py

@@ -0,0 +1,172 @@
+# -*- coding:utf-8 -*-
+"""断言命令: assert-text / assert-url / assert-visible / assert-count
+
+面向脚本与 agent 自检闭环：断言失败输出 JSON error 并以非零码退出，
+可直接用于 `&&` 串联或 CI 检查。
+"""
+import click
+
+from dp_cli.output import ok, error
+from dp_cli.commands._utils import (session_option, frame_option,
+                                    _get_page, resolve_locator, frame_ctx)
+
+
+def _is_missing(ele) -> bool:
+    return not ele or ele.__class__.__name__ == 'NoneElement'
+
+
+def register(cli):
+
+    @cli.command('assert-text')
+    @click.argument('text')
+    @session_option
+    @click.option('--locator', default=None, help='限定断言范围到指定元素')
+    @click.option('--exact', is_flag=True, help='精确匹配（默认包含匹配；建议配合 --locator）')
+    @frame_option
+    @click.option('--timeout', default=5, type=float, help='元素等待超时秒数', show_default=True)
+    def assert_text(text, session, locator, exact, frame, timeout):
+        """断言页面或指定元素包含文本。
+
+        \b
+        示例:
+          dp assert-text "登录成功"
+          dp assert-text "订单已提交" --locator "#msg"
+          dp assert-text "Hello" --locator "#title" --exact
+        """
+        page = _get_page(session)
+        ctx = frame_ctx(page, frame, session)
+        try:
+            if locator:
+                real_loc = resolve_locator(locator, session)
+                ele = ctx.ele(real_loc, timeout=timeout)
+                if _is_missing(ele):
+                    error(f'断言失败：元素不存在 {real_loc}', code='ASSERT_FAILED')
+                    return
+                haystack = (ele.raw_text or '').strip()
+                scope = f'元素 {real_loc}'
+            else:
+                haystack = page.html or ''
+                scope = '页面'
+            matched = haystack == text if exact else text in haystack
+            if matched:
+                ok({'text': text, 'scope': scope, 'exact': exact}, msg='断言通过')
+            else:
+                error(f'断言失败：{scope}不包含文本 "{text}"', code='ASSERT_FAILED',
+                      detail=(haystack[:200] if haystack else '(空)'))
+        except Exception as e:
+            error('断言执行失败', code='ASSERT_FAILED', detail=str(e))
+
+    @cli.command('assert-url')
+    @click.argument('text')
+    @session_option
+    @click.option('--exact', is_flag=True, help='精确匹配（默认包含匹配）')
+    @click.option('--title', 'check_title', is_flag=True, help='断言标题而非 URL')
+    def assert_url(text, session, exact, check_title):
+        """断言当前 URL（或 --title 断言标题）包含文本。
+
+        \b
+        示例:
+          dp assert-url "dashboard"
+          dp assert-url "https://example.com/home" --exact
+          dp assert-url "搜索结果" --title
+        """
+        page = _get_page(session)
+        try:
+            field = 'title' if check_title else 'url'
+            actual = page.title if check_title else page.url
+            actual = actual or ''
+            matched = actual == text if exact else text in actual
+            if matched:
+                ok({'field': field, 'actual': actual, 'exact': exact}, msg='断言通过')
+            else:
+                error(f'断言失败：{field} 不包含 "{text}"', code='ASSERT_FAILED',
+                      detail=f'实际值: {actual[:200]}')
+        except Exception as e:
+            error('断言执行失败', code='ASSERT_FAILED', detail=str(e))
+
+    @cli.command('assert-visible')
+    @click.argument('locator')
+    @session_option
+    @click.option('--hidden', 'expect_hidden', is_flag=True,
+                  help='断言元素不可见或不存在')
+    @frame_option
+    @click.option('--timeout', default=5, type=float, help='元素等待超时秒数', show_default=True)
+    def assert_visible(locator, session, expect_hidden, frame, timeout):
+        """断言元素可见（--hidden 断言不可见/不存在）。
+
+        \b
+        示例:
+          dp assert-visible "#result"
+          dp assert-visible "ref:5"
+          dp assert-visible ".loading" --hidden   # 等待加载指示器消失后断言
+        """
+        page = _get_page(session)
+        ctx = frame_ctx(page, frame, session)
+        try:
+            real_loc = resolve_locator(locator, session)
+            ele = ctx.ele(real_loc, timeout=timeout)
+            missing = _is_missing(ele)
+            visible = False if missing else bool(ele.states.is_displayed)
+            if expect_hidden:
+                if visible:
+                    error(f'断言失败：元素仍可见 {real_loc}', code='ASSERT_FAILED')
+                else:
+                    ok({'locator': real_loc, 'hidden': True}, msg='断言通过：元素不可见')
+            elif missing:
+                error(f'断言失败：元素不存在 {real_loc}', code='ASSERT_FAILED')
+            elif not visible:
+                error(f'断言失败：元素存在但不可见 {real_loc}', code='ASSERT_FAILED')
+            else:
+                ok({'locator': real_loc}, msg='断言通过：元素可见')
+        except Exception as e:
+            error('断言执行失败', code='ASSERT_FAILED', detail=str(e))
+
+    @cli.command('assert-count')
+    @click.argument('locator')
+    @click.argument('expected', required=False, type=int, default=None)
+    @session_option
+    @click.option('--min', 'min_count', type=int, default=None, help='最小数量（含）')
+    @click.option('--max', 'max_count', type=int, default=None, help='最大数量（含）')
+    @frame_option
+    @click.option('--timeout', default=0, type=float,
+                  help='等待元素出现的超时秒数（默认 0 即时返回）', show_default=True)
+    def assert_count(locator, expected, session, min_count, max_count, frame, timeout):
+        """断言匹配元素的数量。
+
+        \b
+        示例:
+          dp assert-count ".item" 20          # 恰好 20 个
+          dp assert-count ".item" --min 1     # 至少 1 个
+          dp assert-count ".error" 0          # 无错误元素
+          dp assert-count "li" --min 3 --max 10
+        """
+        if expected is not None and (min_count is not None
+                                     or max_count is not None):
+            error('位置参数 expected 与 --min/--max 互斥，请二选一',
+                  code='INVALID_ARGS')
+            return
+        if expected is None and min_count is None and max_count is None:
+            error('请指定期望数量或 --min/--max', code='INVALID_ARGS')
+            return
+        page = _get_page(session)
+        try:
+            ctx = frame_ctx(page, frame, session)
+            real_loc = resolve_locator(locator, session)
+            eles = ctx.eles(real_loc, timeout=timeout)
+            n = len(eles)
+            if expected is not None:
+                passed = n == expected
+                desc = f'期望 {expected} 个，实际 {n} 个'
+            else:
+                lo = min_count if min_count is not None else 0
+                hi = max_count if max_count is not None else n
+                passed = lo <= n <= hi
+                lo_s = str(min_count) if min_count is not None else '-∞'
+                hi_s = str(max_count) if max_count is not None else '+∞'
+                desc = f'期望 [{lo_s}, {hi_s}]，实际 {n} 个'
+            if passed:
+                ok({'locator': real_loc, 'count': n}, msg='断言通过')
+            else:
+                error(f'断言失败：{desc}', code='ASSERT_FAILED')
+        except Exception as e:
+            error('断言执行失败', code='ASSERT_FAILED', detail=str(e))