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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.6.2
+Version: 0.6.3
 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

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/commands/keyboard.py

@@ -34,13 +34,17 @@ def register(cli):
 
         \b
         支持的按键: Enter, Tab, Escape, Space, Backspace,
-                   ArrowUp/Down/Left/Right, F1-F12,
-                   Control+A, Shift+Enter, Alt+F4 等组合键。
+                   ArrowUp/Down/Left/Right, F1-F12, Home, End,
+                   PageUp/PageDown, Insert, Delete 等。
+        组合键: Control+A, Shift+Enter, Alt+F4,
+               支持多修饰键如 Control+Shift+Delete。
 
         \b
         示例:
           dp press Enter
           dp press "Control+A"
+          dp press "Control+Shift+Delete"
+          dp press F5
           dp press Escape
         """
         page = _get_page(session)
@@ -52,20 +56,46 @@ def register(cli):
                 'arrowup': '\ue013', 'arrowdown': '\ue015',
                 'arrowleft': '\ue012', 'arrowright': '\ue014',
             }
-            k = key.lower()
+            mod_map = {'control': Keys.CTRL, 'ctrl': Keys.CTRL,
+                       'shift': Keys.SHIFT, 'alt': Keys.ALT,
+                       'meta': Keys.META, 'cmd': Keys.COMMAND,
+                       'command': Keys.COMMAND}
+            # 常见键名别名 → Keys 枚举名（枚举用下划线风格，如 PAGE_UP；
+            # 映射失败会回退为字面输入，带修饰键时会误触浏览器快捷键，
+            # 所以别名必须覆盖常用名）
+            key_alias = {
+                'pageup': 'PAGE_UP', 'pgup': 'PAGE_UP',
+                'pagedown': 'PAGE_DOWN', 'pgdn': 'PAGE_DOWN',
+                'del': 'DEL', 'esc': 'ESCAPE', 'win': 'META',
+            }
+
+            def _key_token(name):
+                """键名 → Keys 枚举/特殊键码；未知键按字面输入。"""
+                low = name.strip().lower()
+                if low in key_map:
+                    return key_map[low]
+                attr = key_alias.get(
+                    low, low.upper().replace('-', '_').replace(' ', '_'))
+                k = getattr(Keys, attr, None)
+                return k if k is not None else name.strip()
+
             if '+' in key:
-                parts = key.split('+')
-                modifier = parts[0].lower()
-                main_key = parts[1]
-                mod_map = {'control': Keys.CTRL, 'ctrl': Keys.CTRL,
-                           'shift': Keys.SHIFT, 'alt': Keys.ALT}
-                if modifier in mod_map:
-                    page.actions.key_down(mod_map[modifier]).type(main_key).key_up(mod_map[modifier])
+                # 前缀修饰键逐个出栈，支持 Control+Shift+Delete 多修饰组合
+                parts = [p for p in key.split('+') if p.strip()]
+                mods = []
+                while len(parts) > 1 and parts[0].strip().lower() in mod_map:
+                    mods.append(mod_map[parts.pop(0).strip().lower()])
+                if mods and parts:
+                    act = page.actions
+                    for m in mods:
+                        act = act.key_down(m)
+                    act = act.type(_key_token('+'.join(parts)))
+                    for m in reversed(mods):
+                        act = act.key_up(m)
                 else:
                     page.actions.type(key)
             else:
-                actual_key = key_map.get(k, key)
-                page.actions.type(actual_key)
+                page.actions.type(_key_token(key))
             ok({'key': key}, msg='按键成功')
         except Exception as e:
             error(f'按键失败: {key}', code='KEY_FAILED', detail=str(e))

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/commands/misc.py

@@ -134,3 +134,5 @@ def register(cli):
                 co.set_user_data_path(user_path)
             co.save()
             ok(msg='配置已保存')
+        elif not copy_config:
+            click.echo('请至少指定一个选项。使用 --help 查看可用参数。')

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/commands/network.py

@@ -9,13 +9,46 @@ from dp_cli.output import ok, error
 from dp_cli.commands._utils import session_option, _get_page
 
 
+def _emit_response(page, output):
+    """构造 http-get/http-post 的输出。
+
+    --output 指定时把原始响应字节写入文件（兼容二进制），
+    否则把 body 内联到结果（JSON 优先，文本截断 3000 字）。
+    """
+    resp = page.response
+    result = {
+        'url': page.url,
+        'status_code': resp.status_code if resp is not None else None,
+    }
+    if output:
+        # response 为 None（请求失败未拿到响应）时写空文件，避免 AttributeError
+        Path(output).write_bytes(resp.content if resp is not None else b'')
+        result['saved_to'] = output
+        if resp is None:
+            result['warning'] = '无响应内容（response is None），已写入空文件'
+        return result
+    if resp is None:
+        result['body'] = None
+        return result
+    try:
+        result['body'] = resp.json()
+    except Exception:
+        try:
+            result['body'] = resp.text[:3000]
+        except Exception:
+            result['body'] = '<binary>'
+    return result
+
+
 def register(cli):
 
     @cli.command('listen')
     @session_option
     @click.option('--filter', 'url_filter', default=None, help='URL 过滤关键字，如 "api/user"')
-    @click.option('--count', default=10, help='最多捕获请求数', show_default=True)
-    @click.option('--timeout', default=30, help='监听超时秒数', show_default=True)
+    # --count/--timeout 对 listen.start 无意义（作用于 listen-stop 的 wait），
+    # 保留参数兼容性但从 help 隐藏，避免误导
+    @click.option('--count', default=10, hidden=True)
+    @click.option('--timeout', default=30, hidden=True)
     @click.option('--method', default=None, help='过滤请求方法，如 POST')
     def listen(session, url_filter, count, timeout, method):
         """监听网络请求（抓包）。先 listen，再执行触发操作，最后 listen-stop 读取结果。
@@ -26,7 +59,7 @@ def register(cli):
         \b
         示例:
           dp listen --filter "api/login"
-          dp listen --count 5 --timeout 10
+          dp listen --method POST
         """
         page = _get_page(session)
         try:
@@ -44,7 +77,11 @@ def register(cli):
         """停止监听并获取捕获的网络请求数据。"""
         page = _get_page(session)
         try:
-            packets = page.listen.wait(count=count, timeout=timeout, fit_count=False)
+            # finally 中 stop：wait 超时/出错也必须停止监听，否则监听器残留
+            try:
+                packets = page.listen.wait(count=count, timeout=timeout, fit_count=False)
+            finally:
+                page.listen.stop()
             results = []
             if packets:
                 pkts = packets if isinstance(packets, list) else [packets]
@@ -63,7 +100,6 @@ def register(cli):
                         results.append(item)
                     except Exception:
                         continue
-            page.listen.stop()
             ok({'packets': results, 'count': len(results)})
         except Exception as e:
             error(f'获取监听数据失败', code='LISTEN_FAILED', detail=str(e))
@@ -95,25 +131,7 @@ def register(cli):
 
             page = SessionPage(session_or_options=so)
             page.get(url, timeout=timeout)
-
-            result = {
-                'url': page.url,
-                'status_code': page.response.status_code if page.response else None,
-            }
-            try:
-                result['body'] = page.response.json()
-            except Exception:
-                try:
-                    body_text = page.response.text[:3000]
-                except Exception:
-                    body_text = '<binary>'
-                if output:
-                    Path(output).write_text(page.response.text, encoding='utf-8')
-                    result['saved_to'] = output
-                else:
-                    result['body'] = body_text
-
-            ok(result)
+            ok(_emit_response(page, output))
         except Exception as e:
             error(f'HTTP GET 失败', code='HTTP_FAILED', detail=str(e))
 
@@ -124,7 +142,8 @@ def register(cli):
     @click.option('--headers', default=None, help='JSON 格式的 Headers')
     @click.option('--proxy', default=None, help='代理地址')
     @click.option('--timeout', default=30, help='超时秒数', show_default=True)
-    def http_post(url, data, form, headers, proxy, timeout):
+    @click.option('--output', default=None, help='响应体保存路径')
+    def http_post(url, data, form, headers, proxy, timeout, output):
         """发送 HTTP POST 请求（不启动浏览器）。
 
         \b
@@ -151,19 +170,6 @@ def register(cli):
                 kwargs['data'] = json.loads(form)
 
             page.post(url, **kwargs)
-
-            result = {
-                'url': page.url,
-                'status_code': page.response.status_code if page.response else None,
-            }
-            try:
-                result['body'] = page.response.json()
-            except Exception:
-                try:
-                    result['body'] = page.response.text[:3000]
-                except Exception:
-                    result['body'] = '<binary>'
-
-            ok(result)
+            ok(_emit_response(page, output))
         except Exception as e:
             error(f'HTTP POST 失败', code='HTTP_FAILED', detail=str(e))

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/commands/record.py

@@ -1,5 +1,6 @@
 # -*- coding:utf-8 -*-
 """操作录制命令: record-start / record-stop / record-show / record-clear"""
+import sys
 from pathlib import Path
 
 import click
@@ -16,20 +17,22 @@ def _get_active_page_for_record(session):
     """获取浏览器当前激活的标签页用于录制（忽略 session 中的 active_tab 绑定）"""
     from dp_cli.session import get_browser
     page = get_browser(session)
-    
-    # 使用 CDP 找到当前真正激活的标签页
+
+    # 使用 CDP 找到当前真正激活的标签页，直接按 targetId 取 tab
+    # （DrissionPage 的 tab_id 即 CDP targetId，无需为每个 target 遍历全部 tab）
     try:
         result = page.run_cdp('Target.getTargets')
         for target in result.get('targetInfos', []):
             if target.get('attached') and target.get('type') == 'page':
-                target_id = target.get('targetId')
-                # 通过 targetId 获取对应的 tab
-                for tab in [page.get_tab(tid) for tid in _get_all_tab_ids(page)]:
-                    if tab and tab.tab_id == target_id:
-                        return tab
+                try:
+                    tab = page.get_tab(target.get('targetId'))
+                except Exception:
+                    continue
+                if tab:
+                    return tab
     except Exception as e:
-        print(f'[record] Failed to get active tab via CDP: {e}', file=__import__('sys').stderr)
-    
+        print(f'[record] Failed to get active tab via CDP: {e}', file=sys.stderr)
+
     # 回退到 latest_tab
     try:
         return page.latest_tab or page
@@ -37,19 +40,6 @@ def _get_active_page_for_record(session):
         return page
 
 
-def _get_all_tab_ids(page):
-    """获取所有标签页的 ID 列表"""
-    try:
-        # 使用 CDP 获取所有目标
-        result = page.run_cdp('Target.getTargets')
-        return [
-            t.get('targetId') for t in result.get('targetInfos', [])
-            if t.get('type') == 'page'
-        ]
-    except Exception:
-        return []
-
-
 def _get_recording_page(session):
     page = _get_page(session, raw=True, inject_recording=False)
     sess = load_session(session) or {}
@@ -98,7 +88,8 @@ def register(cli):
             save_session(session, sess)
             data = dict(status or {})
             data['tab'] = _page_info(page)
-            msg = (f'操作录制已开始，已绑定标签页: {data["tab"]["url"][:40]}...\n'
+            tab_url = (data['tab']['url'] or '')[:40]
+            msg = (f'操作录制已开始，已绑定标签页: {tab_url}...\n'
                    f'  提示: 如果绑定不正确，请先执行 "dp tab-select <序号>" 选择正确标签，再录制')
             ok(data, msg=msg)
         except Exception as e:

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/commands/storage.py

@@ -26,10 +26,32 @@ def register(cli):
         """
         page = _get_page(session)
         try:
-            cookies = page.cookies(all_domains=True).as_dict()
+            # all_info=True 保留 domain/path 等完整字段，供 --domain/--url 过滤
+            cookies = page.cookies(all_domains=True, all_info=True)
+            # --url：取 host 做 cookie domain 匹配（.example.com 匹配 sub.example.com）
+            host = None
+            if url:
+                host = url.split('://', 1)[-1].split('/')[0].split(':')[0].lower()
             cookie_list_data = []
-            for name, value in cookies.items():
-                cookie_list_data.append({'name': name, 'value': value})
+            for c in cookies:
+                c_domain = (c.get('domain') or '')
+                if domain:
+                    # 域级匹配（标签边界）：example.com 命中 .example.com /
+                    # sub.example.com 的 cookie，不命中 notexample.com
+                    # （子串匹配会误中）
+                    fd = domain.lower().lstrip('.')
+                    cd = c_domain.lower().lstrip('.')
+                    if not (cd == fd or cd.endswith('.' + fd)
+                            or fd.endswith('.' + cd)):
+                        continue
+                if host:
+                    d = c_domain.lstrip('.')
+                    if not (host == d or host.endswith('.' + d)):
+                        continue
+                cookie_list_data.append({'name': c.get('name'),
+                                         'value': c.get('value'),
+                                         'domain': c_domain,
+                                         'path': c.get('path', '/')})
             ok({'cookies': cookie_list_data, 'count': len(cookie_list_data)})
         except Exception as e:
             error(f'获取 Cookie 失败', code='COOKIE_FAILED', detail=str(e))
@@ -210,6 +232,18 @@ def register(cli):
         except Exception as e:
             error(f'设置 sessionStorage 失败', code='STORAGE_FAILED', detail=str(e))
 
+    @cli.command('sessionstorage-delete')
+    @click.argument('key')
+    @session_option
+    def sessionstorage_delete(key, session):
+        """删除 sessionStorage 指定键。"""
+        page = _get_page(session)
+        try:
+            page.run_js(f'sessionStorage.removeItem({json.dumps(key)})', as_expr=True)
+            ok({'key': key}, msg='sessionStorage 键已删除')
+        except Exception as e:
+            error(f'删除 sessionStorage 失败', code='STORAGE_FAILED', detail=str(e))
+
     @cli.command('sessionstorage-clear')
     @session_option
     def sessionstorage_clear(session):

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/recorder.py

@@ -266,7 +266,7 @@ _RECORDER_JS = r"""
   }
 
   function findScrollable(el) {
-    let cur = el && el.nodeType === 1 ? el : el.parentElement;
+    let cur = (el && el.nodeType === 1) ? el : (el && el.parentElement);
     while (cur && cur !== document.body && cur !== document.documentElement) {
       const st = getComputedStyle(cur);
       const canY = /(auto|scroll|overlay)/.test(st.overflowY) && cur.scrollHeight > cur.clientHeight + 1;
@@ -362,8 +362,6 @@ _RECORDER_JS = r"""
   document.addEventListener('keydown', onKeyDown, true);
   document.addEventListener('wheel', onWheel, true);
 
-  console.log('[dp-recorder] initialized, version:', VERSION);
-
   window.__dpRecorder = {
     version: VERSION,
     start: function () { setRecording(true); },

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/snapshot/a11y.py

@@ -13,6 +13,8 @@ a11y tree — 浏览器原生无障碍树获取与渲染
   5. render_a11y_text() 渲染为可读文本
   6. CDP 失败时降级到 JS fallback
 """
+import json
+
 from .utils import suggest_locator
 
 # 交互角色列表：需要生成定位器的角色
@@ -368,9 +370,11 @@ def _find_subtree_by_selector(page, tree: dict, all_nodes: list,
             xpath_selector = normalized[6:]
             # 使用 Runtime.evaluate 执行 document.evaluate 支持 xpath
             # ponytail: 不使用 returnByValue，直接获取 objectId
+            # xpath 经 json.dumps 转义——xpath 常含双引号（如 //div[@class="x"]），
+            # 直接拼进 JS 字符串会语法错误，甚至有注入风险
             js_code = f'''
             (function() {{
-                const result = document.evaluate("{xpath_selector}", document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+                const result = document.evaluate({json.dumps(xpath_selector)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
                 return result.singleNodeValue;
             }})()
             '''
@@ -397,10 +401,9 @@ def _find_subtree_by_selector(page, tree: dict, all_nodes: list,
 
         # ponytail: iframe 特殊处理 - 获取 iframe 的 frameId 并返回该 frame 的快照
         if node_name == 'iframe':
-            # 获取 iframe 的 frameId
+            # 上面的 describeNode 结果已含 frameId，无需重复 CDP 调用
             try:
-                frame_info = page.run_cdp('DOM.describeNode', nodeId=node_id)
-                frame_id = frame_info['node'].get('frameId')
+                frame_id = node_info.get('frameId')
                 if frame_id:
                     # 重新获取该 frame 的 a11y tree
                     flat_nodes = _get_full_tree_cdp(page, max_depth=None, frame_id=frame_id)
@@ -502,7 +505,19 @@ def _build_tree(flat_nodes: list) -> dict:
     roots = [n for n in flat_nodes
              if not n.get('parentId') or n['parentId'] not in node_map]
 
-    return roots[0] if roots else flat_nodes[0] if flat_nodes else {}
+    if not roots:
+        return flat_nodes[0] if flat_nodes else {}
+    if len(roots) == 1:
+        return roots[0]
+    # 多根节点（如 iframe）：用合成容器包裹，避免丢失子树
+    return {
+        'nodeId': '__root__',
+        'role': 'generic',
+        'name': '',
+        'children': roots,
+        'backendNodeId': None,
+        'locator': None,
+    }
 
 
 def _compute_stats(nodes: list) -> dict:
@@ -553,7 +568,6 @@ def _generate_locators_batch(page, interactive_nodes: list, frame_id: str = None
         attrs_map = {}
         try:
             # 如果没有指定自定义优先级，使用默认优先级
-            from .utils import suggest_locator
             default_priority = [
                 'data-testid', 'data-test', 'data-test-id',
                 'data-qa', 'data-cy', 'id', 'aria-label', 'name', 'placeholder'
@@ -565,15 +579,16 @@ def _generate_locators_batch(page, interactive_nodes: list, frame_id: str = None
             combined_selector = ','.join(selectors)
 
             # 使用 JS 一次性获取所有元素的属性
+            # selector 与 attr 列表经 json.dumps 转义，避免引号破坏 JS / 注入
             js = f"""
             (function() {{
                 const result = {{}};
-                const elements = document.querySelectorAll('{combined_selector}');
+                const elements = document.querySelectorAll({json.dumps(combined_selector)});
                 elements.forEach(el => {{
                     const text = el.textContent.trim().substring(0, 50);
                     if (text && !result[text]) {{
                         const attrs = {{}};
-                        for (const attr of {attrs_to_get}) {{
+                        for (const attr of {json.dumps(attrs_to_get)}) {{
                             if (el.hasAttribute(attr)) {{
                                 attrs[attr] = el.getAttribute(attr);
                             }}
@@ -588,7 +603,6 @@ def _generate_locators_batch(page, interactive_nodes: list, frame_id: str = None
             """
             result = page.run_cdp('Runtime.evaluate', expression=js, returnByValue=True)
             if result.get('result', {}).get('value'):
-                import json
                 attrs_map = json.loads(result['result']['value'])
         except Exception:
             pass
@@ -708,7 +722,7 @@ def _build_dom_bid_map(page, frame_id: str = None) -> dict:
     :param frame_id: 可选，限制获取特定 frame 的 DOM 树
     """
     try:
-        kwargs = {'depth': -1}
+        kwargs = {'depth': -1, 'pierce': True}
         if frame_id:
             kwargs['frameId'] = frame_id
         doc = page.run_cdp('DOM.getDocument', **kwargs)
@@ -763,7 +777,8 @@ def _render_node(node: dict, lines: list, depth: int = 0,
     """递归渲染单个 a11y 节点为文本行
 
     :param parent_text: 父节点已显示的文本，用于消除子节点冗余
-    :param brief: True 时跳过内容节点（paragraph/heading 等），只显示交互元素
+    :param brief: True 时跳过独立文本节点并截断内容节点长文本（>80 字），
+                  保留结构 + 交互元素概览，省 token
     :param ctx: 渲染上下文 {'counter': int, 'refs': dict}，用于分配 [N] 编号
     """
     role = node.get('role', '')
@@ -771,10 +786,14 @@ def _render_node(node: dict, lines: list, depth: int = 0,
     ignored = node.get('ignored', False)
     children = node.get('children', [])
 
-    # brief 模式：跳过内容节点（paragraph/heading 等），但保留交互元素和容器
-    if brief and role in _CONTENT_ROLES:
+    # brief 模式：跳过非关键内容节点（cell/listitem/caption 等），
+    # 但保留 _REF_CONTENT_ROLES（paragraph/heading/code/blockquote），由后续逻辑截断；
+    # 跳过时仍递归子节点，避免丢失嵌套的交互元素
+    if brief and role in _CONTENT_ROLES and role not in _REF_CONTENT_ROLES:
+        for child in children:
+            _render_node(child, lines, depth, verbose=verbose,
+                         parent_text=parent_text, brief=brief, ctx=ctx)
         return
-
     # 跳过 ignored 节点（除非 verbose），但仍然渲染子节点
     if ignored and not verbose:
         for child in children:

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli/snapshot/js_scripts.py

@@ -105,6 +105,15 @@ _JS_A11Y_FALLBACK = """
             const cn = buildNode(child, depth + 1);
             if (cn) children.push(cn);
         }
+        // 穿透 open shadow DOM
+        if (el.shadowRoot) {
+            try {
+                for (const child of el.shadowRoot.children) {
+                    const cn = buildNode(child, depth + 1);
+                    if (cn) children.push(cn);
+                }
+            } catch (e) {}
+        }
 
         // 跳过无意义容器（无 role、无 name、只有一个子节点）
         if (!role && !name && children.length === 1) {
@@ -140,9 +149,12 @@ _JS_A11Y_FALLBACK = """
             const v = el.getAttribute(attr);
             if (v) return '@' + attr + '=' + v;
         }
-        const cls = el.className;
-        if (typeof cls === 'string' && cls.trim()) {
-            return '.' + cls.trim().split(/\\s+/)[0];
+        const cls = typeof el.className === 'string' ? el.className : (el.className && el.className.baseVal) || '';
+        if (cls.trim()) {
+            const parts = cls.trim().split(/\\s+/).filter(function(c) {
+                return c && !/^[a-z0-9]{6,}$/i.test(c) && !/^[_-]/.test(c);
+            });
+            if (parts.length) return '.' + parts[0];
         }
         const text = (el.textContent || '').trim();
         if (text && text.length <= 30) return 'text:' + text;

{dp_cli-0.6.2 → dp_cli-0.6.3}/dp_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.6.2
+Version: 0.6.3
 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

{dp_cli-0.6.2 → dp_cli-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dp-cli"
-version = "0.6.2"
+version = "0.6.3"
 description = "A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more."
 readme = "README.md"
 requires-python = ">=3.8"

{dp_cli-0.6.2 → dp_cli-0.6.3}/tests/test_a11y.py

@@ -658,4 +658,88 @@ def test_generate_locators_iframe_frame():
     # 没有 id 的使用 class
     assert interactive_nodes[1]['locator'] == '.btn-export' or 'btn-export' in interactive_nodes[1]['locator']
     # 查找失败的回退到 text:
-    assert interactive_nodes[2]['locator'] == 'text:搜索'
+    assert interactive_nodes[2]['locator'] == 'text:搜索'
+
+# ─────────────────────────────────────────────────────────────────────────────
+# t3 增强回归：JS 转义 / iframe describeNode 去重
+# ─────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.unit
+def test_find_subtree_xpath_quotes_escaped():
+    """xpath 含双引号（如 //div[@class="x"]）时必须转义后再拼进 JS，
+    否则 Runtime.evaluate 语法错误；断言传入的 expression 已被 json 转义。"""
+    exprs = []
+
+    def rt(**kw):
+        exprs.append(kw.get('expression', ''))
+        return {'result': {'type': 'object', 'objectId': 'obj1'}}
+
+    page = FakePage(cdp_map={
+        'DOM.getDocument': {'root': {'nodeId': 1}},
+        'Runtime.evaluate': rt,
+        'DOM.requestNode': {'nodeId': 100},
+        'DOM.describeNode': {'node': {'backendNodeId': 200, 'nodeName': 'DIV'}},
+    })
+    tree = node(role='root', backendNodeId=1, children=[
+        node(role='generic', backendNodeId=200)
+    ])
+    result, warning, frame_id = a11y._find_subtree_by_selector(
+        page, tree, [], 'xpath://div[@class="x"]')
+
+    assert exprs, 'Runtime.evaluate 未被调用'
+    # xpath 应作为 JSON 字符串字面量出现（双引号被 \" 转义）
+    assert '//div[@class=\\"x\\"]' in exprs[0]
+    assert warning is None
+    assert result['backendNodeId'] == 200
+
+
+@pytest.mark.unit
+def test_find_subtree_iframe_describe_node_once():
+    """iframe 分支复用首次 describeNode 的 frameId，整个流程只调 1 次。"""
+    calls = []
+
+    def describe(**kw):
+        calls.append(kw)
+        return {'node': {'backendNodeId': 200, 'nodeName': 'IFRAME',
+                         'frameId': 'F1'}}
+
+    page = FakePage(cdp_map={
+        'DOM.getDocument': {'root': {'nodeId': 1}},
+        'DOM.querySelector': {'nodeId': 100},
+        'DOM.describeNode': describe,
+        'Accessibility.getFullAXTree': {
+            'nodes': [{'nodeId': '1', 'role': {'value': 'WebArea'},
+                       'backendDOMNodeId': 1, 'childIds': []}]
+        },
+    })
+    tree = node(role='root', backendNodeId=1)
+    result, warning, frame_id = a11y._find_subtree_by_selector(
+        page, tree, [], 'iframe')
+
+    assert frame_id == 'F1'
+    assert '已切换到 iframe frame' in warning
+    assert len(calls) == 1
+
+
+@pytest.mark.unit
+def test_generate_locators_escapes_attr_selector():
+    """attr_priority 含引号时，拼进 JS 的 selector / attr 列表必须经
+    json.dumps 转义，不产生非法 JS 或注入。"""
+    exprs = []
+
+    def rt(**kw):
+        exprs.append(kw.get('expression', ''))
+        return {'result': {'value': '{}'}}
+
+    page = FakePage(cdp_map={
+        'DOM.getDocument': {'root': {'backendNodeId': 1, 'nodeName': 'DIV',
+                                     'attributes': [], 'children': []}},
+        'Runtime.evaluate': rt,
+    })
+    nodes = [node(role='button', backendNodeId=1, name='x')]
+    a11y._generate_locators_batch(page, nodes, attr_priority=["data-fo'o"])
+
+    assert exprs, 'Runtime.evaluate 未被调用'
+    # 属性名以 JSON 字符串形式出现（双引号包裹，单引号原样保留）
+    assert '"[data-fo\'o]"' in exprs[0]
+    assert '["data-fo\'o"]' in exprs[0]