@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/skills/d2h-hypium-forge/references/testability-template.md

@@ -0,0 +1,71 @@
+# 可测试性需求（Design for Testability）— 模板与累积清单
+
+> 调测中发现的「让 hypium 测试变慢/不准」的工程特征，反哺为对应用开发的需求。
+> 每条格式：现象（实测） → 根因 → 可测试性需求（对开发的要求） → 收益。
+
+## 累积清单（按工程验证时追加）
+
+### DFT-001 控件必须预置稳定 ID
+- 现象：无 .id() 控件用 BY.text 定位，文案随数据变化 → 脚本重试多轮、不稳定（实测：首个转化工程首轮全部超时）。
+- 根因：ArkTS 开发普遍省略 .id()，uitest 只能按 text/type 匹配。
+- 需求：**所有可交互控件（Button/Toggle/TextInput/入口 Image）必须写 .id()**，命名 `<语义>_<页面>`（如 btn_settings_index）。
+- 收益：脚本零重试定位；用例与实现解耦（文案改了脚本不断）。
+
+### DFT-002 条件渲染控件需可达路径
+- 现象：`if(testMode)` 内控件默认态不存在，存在性断言误报失败（实测 START TEST 按钮）。
+- 需求：条件功能的入口开关应在**入口页可达**（≤2 步操作），或提供 deeplink/want 参数直达。
+- 收益：状态覆盖用例可自动执行，不依赖复杂前置链。
+
+### DFT-003 运行时权限在模拟器的可预授性
+- 现象：首启权限弹窗阻塞 BFS/用例执行（实测 RaiseToAnswer 电话权限）。
+- 需求：应用不应在首帧同步弹多个权限弹窗；权限申请延后到功能触发点。
+- 收益：precondition 批量预授后用例零弹窗干扰。
+
+### DFT-004 登录需提供测试通道
+- 现象：真实登录页在模拟器无法自动完成 → 登录后功能全部 BLOCKED。
+- 需求：提供 mock 登录开关（want 参数/环境开关）或测试账号常量。
+- 收益：登录态用例可全自动执行。
+
+### DFT-005 首启弹窗需可编程处置
+- 现象：隐私协议/引导页弹窗文案各异，逐个适配成本高。
+- 需求：首启弹窗按钮文案使用标准词（同意并继续/跳过/我知道了）；提供"不再提醒"。
+- 收益：统一 dismiss 片段即可覆盖。
+
+（新工程验证时按编号追加，注明来源工程与实测数据）
+
+### DFT-006 HAP 更新必须卸载重装（模拟器缓存怪癖）
+- 现象：`install -r` 同版本号替换后，注入的 .id 运行时全部丢失（abc 缓存不失效，实测 News 工程）。
+- 需求/skill 规则：**注入 ID 重打包后一律 `hdc uninstall <bundle> && hdc install <hap>`**。
+
+### DFT-007 部分 HAR 模块 .id 运行时丢弃（待官方解释）
+- 现象：同一 HAP 内 commons/features-home 的 .id 生效，features-mine 的全部不生效（abc 字节串在、属性指令无效，跨 4 种注入位置复现）。
+- 需求：**smart_check/smart_click 必须带 orig_target 文本兜底**（key 失败转文本/类型断言）。
+- 来源：News 工程（2026-09-23 实测）。
+
+### DFT-008 同控件多次注入会叠 id（仅首个生效）
+- 现象：多条用例引用同一控件时注入器产生 `.id(a).id(b)`，运行时仅第一个可查。
+- 需求/skill 规则：**用例引用统一到首注入 ID（`_1` 后缀规约）**；注入器应检测已有 tc_ id 并复用。
+
+### DFT-009 Tab 切换的可靠路径
+- 现象：BY.text 精确/模糊点击 Tab 均可能点到正文同名文本；比例坐标受 Tab 数量与手势条影响。
+- 需求/skill 规则：**click_tab 用 find_all_components 取「最靠下的同名文本」的 bounds 中心 touch**（News/SchoolLife/CoolMall 2/3/4-Tab 全验证通过）。
+
+### DFT-010 资源化文案使静态覆盖度失准
+- 现象：CoolMall（70k 行）源码文案全部 `$r()` 资源化，scan 的交互点与运行时文本不匹配 → 静态覆盖度 0%。
+- 需求/skill 规则：大型工程覆盖度评估降级为**运行时可达性口径**（用例通过率 + dump 文本对照）；源码覆盖度仅对硬编码文案工程有效。
+
+### DFT-011 用例间需间歇（teardown 冷启动时序）
+- 现象：批量连跑时下一条 setup 的 start_app 未完成即断言（TC01 偶发失败）。
+- skill 规则：批量执行循环 **sleep 3s** + launch 等待 2.5s 起步。
+
+### DFT-012 输入法首用向导是隐藏前置（CoolMall 实测）
+- 现象：input_text 前拉起「小艺输入法」声明弹窗 + 键盘布局向导（多步），挡住输入与提交按钮；向导期间点登录无效。
+- skill 规则：precondition 增加 IME 预置步骤——检测并依次点掉「同意/下一步/完成」；输入后 **press_back 收键盘再点提交按钮**（否则按钮被键盘遮挡）。
+
+### DFT-013 输入框定位用 BY.hint 不用 BY.text
+- 现象：`BY.text('请输入手机号')` 匹配到的是 hint 展示文本节点而非 TextInput 本体，input_text 无效且无报错。
+- skill 规则：**带占位符的输入框一律 `BY.hint('<placeholder>')` 定位**（hypium 专属匹配器）。
+
+### DFT-014 设备访问 PC mock 需 rport（fport 是反向）
+- 现象：`hdc fport` 是 PC→设备方向；设备 App 访问 127.0.0.1:8787 的 PC mock 必须用 `hdc rport tcp:8787 tcp:8787`（CoolMall BASE_URL 已预指 mock）。
+- 附：mock 重启后 App 需 aa force-stop 冷启动才重新拉数据（失败态有缓存）。

package/skills/d2h-hypium-forge/scripts/_common_template.py

@@ -0,0 +1,614 @@
+# coding: utf-8
+"""d2h-hypium-forge 共享库（自动生成）
+
+前置条件分组编排约定（TD-004）：
+  需要登录态的用例文件顶部声明  PRECOND = 'logged_in'
+  首启态（bm clean）用例声明      PRECOND = 'first_launch'
+  缺省                          PRECOND = 'anonymous'
+  run_direct 按 anonymous→logged_in→first_launch 分组排序（破坏性递增，clean 类排尾），
+  组内软隔离（launch() 默认 reset_data=False，preferences 保留→登录态保持）。
+  ensure_login 等 setup 必须【幂等】：先探测状态（抽屉用户名已就位）再决定是否走完整
+  UI 登录——组首一次完整 setup，组内后续直接复用（省重复登录/注册）。
+  组首条执行时环境变量 FORGE_GROUP_FIRST=1（可选做完整冷启验证）。
+"""
+import time
+from hypium import *
+from hypium.model import MatchPattern, UiParam
+
+PACKAGE = "me.hackerchick.raisetoanswer"
+ABILITY = "EntryAbility"
+ENTRY_PAGE = "pages/Index"
+
+
+# ── Level 0 统一引导引擎（TD-008）：权限/隐私/广告/引导弹窗 + tab 归位，一揽子消化 ──
+# 关卡模型：每关 = 探测特征文案集合 → 处置（点击命中项）→ 循环消化到无特征。
+# app 级配置 GATES（按需增删）；bootstrap 幂等（主页锚可见即成功），超时输出页面快照供分诊。
+
+GATES = [
+    {"name": "privacy",    "texts": ["同意并继续", "同意", "知道了", "我知道了"]},
+    {"name": "permission", "texts": ["仅在使用中允许", "使用应用时允许", "允许"]},
+    {"name": "ad",         "texts": ["跳过", "关闭广告", "不再显示", "以后再说", "暂不"]},
+]
+
+def _page_texts(d):
+    try:
+        return [(c.getText() or '') for c in (d.find_all_components(BY.type("Text")) or [])
+                if c.getText()]
+    except Exception:
+        return []
+
+def bootstrap(d, gates=None, home_tab="", anchor_key="", total=60, log=print):
+    """冷启到可用基座。流程：轮询消化全部弹窗关卡（一轮多点，直到无特征）→
+    tab 归位（点目标 tab + 验证锚）→ 主页锚可见返回 True。
+    anchor_key 是"基座就绪"的唯一判据（app 级配置，如目标 tab 的内容控件 id）。"""
+    gates = gates if gates is not None else GATES
+    all_texts = [t for g in gates for t in g["texts"]]
+    t0 = time.time()
+    dismissed = []
+    while time.time() - t0 < total:
+        # 1) 主页锚已可见 → 提前成功（幂等）
+        if anchor_key:
+            try:
+                if d.find_component(BY.key(anchor_key)) is not None:
+                    if dismissed:
+                        log(f"  [L0] 弹窗消化: {dismissed}")
+                    return True
+            except Exception:
+                pass
+        # 2) 消化所有弹窗关卡：一轮内逐个点
+        hit_any = False
+        for t in all_texts:
+            if t == (home_tab or ""):
+                continue
+            try:
+                # 全类型探测（按钮常为 Button 非 Text——TD-008 实证：Text-only 扫描漏掉隐私页同意按钮）
+                if d.find_component(BY.text(t)) is not None:
+                    d.touch(BY.text(t))
+                    dismissed.append(t)
+                    hit_any = True
+                    time.sleep(1.2)
+                    break  # 点一个后重新扫（弹窗可能叠加/消失后露下一个）
+            except Exception:
+                pass
+        if hit_any:
+            continue
+        pts = _page_texts(d)
+        # 3) 无弹窗特征：tab 归位（点目标 tab，锚验证）
+        if home_tab and home_tab in pts:
+            if anchor_key:
+                try:
+                    if d.find_component(BY.key(anchor_key)) is not None:
+                        return True
+                except Exception:
+                    pass
+            try:
+                d.touch(BY.text(home_tab))
+                time.sleep(2.0)
+            except Exception:
+                pass
+        time.sleep(0.9)
+    # 超时：输出页面快照供分诊
+    log(f"  [L0] ✗ bootstrap 超时 {total}s；页面文本快照: {_page_texts(d)[:15]}")
+    return False
+
+
+# ── Level 0 前置三件套（TD-007：冷启自适应，用例不得自带）────────────────
+# ① 首启弹窗 dismiss：多文案轮询（隐私/权限/引导），幂等无弹窗秒过
+FIRST_RUN_DISMISS_TEXTS = ["同意并继续", "同意", "允许", "仅在使用中允许", "我知道了", "知道了", "暂不", "以后再说"]
+
+def dismiss_first_run(d, rounds=3, gap=1.2):
+    for _ in range(rounds):
+        hit = False
+        for t in FIRST_RUN_DISMISS_TEXTS:
+            try:
+                c = d.find_component(BY.text(t))
+                if c is not None:
+                    d.touch(BY.text(t)); time.sleep(gap); hit = True; break
+            except Exception:
+                pass
+        if not hit:
+            return
+
+# ② 首页 tab 归位：应用默认落在非目标 tab（如广场）时点回目标 tab（HOME_TAB 应用级配置）
+def ensure_home_tab(d, tab_text, timeout=10):
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        try:
+            if d.find_component(BY.text(tab_text)) is not None:
+                d.touch(BY.text(tab_text)); time.sleep(1.5); return True
+        except Exception:
+            pass
+        time.sleep(0.8)
+    return False
+
+# ③ 冷启三件套：launch 内自动执行——弹窗 dismiss + tab 归位（HOME_TAB 非空时）
+HOME_TAB = ""  # 应用级：主功能 tab 文案（如 "玩安卓"）；空串跳过归位
+
+
+def launch(d, want="", reset_data=False):
+    """v3-①②（EXEC-034）：want=启动参数（'k=v;k2=v2' → hdc aa start --ps 透传，启动参数门控应用免人工补丁）；
+    reset_data=True → bm clean -n 清应用数据（用例级状态重置，防跨用例泄漏）。"""
+    import os as _os, subprocess as _sp
+    d.stop_app(PACKAGE)
+    time.sleep(0.8)
+    if reset_data:
+        hdc = _os.environ.get("FORGE_HDC", "hdc")
+        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+        try:
+            # DEVIATION-3: bm clean 不带 -d 时仅清 cache(-c),持久化不清,用例间状态泄漏
+            # (TC02 关 answer 残留致 TC03/08/09 连锁失败);本机 bm 无 -b 选项,-d 清数据
+            _sp.run([hdc, "-t", dev, "shell", "bm", "clean", "-n", PACKAGE, "-d"],
+                    capture_output=True, timeout=15)
+            time.sleep(0.5)
+        except Exception as e:
+            print("  [reset] bm clean 失败:", e)
+    if want:
+        hdc = _os.environ.get("FORGE_HDC", "hdc")
+        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+        args = ["aa", "start", "-b", PACKAGE, "-a", ABILITY]
+        for kv in want.split(";"):
+            if "=" in kv:
+                k, v = kv.split("=", 1)
+                # DEVIATION-1: aa start 的 --ps 只接受空格分隔 key value,等号形式报
+                # "invalid number of parameters for option --ps" 导致带参启动全部失败
+                args += ["--ps", k, v]
+        # EXEC-038 修复：带参启动 3 轮重试 + 实测探活（FORGE_WANT_PROBE=key，可寻才算活）
+        probe = _os.environ.get("FORGE_WANT_PROBE", "")
+        for attempt in range(3):
+            try:
+                _sp.run([hdc, "-t", dev, "shell", "aa", "force-stop", PACKAGE], capture_output=True, timeout=10)
+                time.sleep(0.8)
+                _sp.run([hdc, "-t", dev, "shell"] + args, capture_output=True, timeout=15)
+                time.sleep(3.0)
+                if probe:
+                    c = None
+                    try:
+                        c = d.find_component(BY.key(probe))
+                    except Exception:
+                        pass
+                    if c is None:
+                        print(f"  [want] 第{attempt+1}轮探活失败(key={probe})，重试")
+                        time.sleep(1.5)
+                        continue
+                _dismiss_first_run(d)
+                return
+            except Exception as e:
+                print("  [want] 带参启动异常，重试:", e)
+                time.sleep(1.5)
+        print("  [want] 3 轮未探活成功，继续交由断言暴露")
+    d.start_app(PACKAGE, ABILITY)
+    ok = bootstrap(d, home_tab=HOME_TAB, anchor_key=HOME_ANCHOR)
+    if not ok:
+        raise AssertionError("L0 bootstrap failed（弹窗/tab 未消化，见日志快照）")
+    time.sleep(2.5)
+    _dismiss_first_run(d)
+
+
+def _dismiss_first_run(d):
+    """首启弹窗一键处置（权限/隐私协议）"""
+    for txt in ["同意并继续", "允许", "我知道了", "暂不", "以后再说", "同意"]:
+        try:
+            c = d.find_component(BY.text(txt))
+            if c:
+                c.click()
+                time.sleep(0.8)
+        except Exception:
+            pass
+
+
+def stop(d):
+    d.stop_app(PACKAGE)
+
+
+def nav_to(d, page):
+    """导航到目标页：入口页直接用；非入口页用返回键回根后再走用例自带链（由用例 steps 驱动）"""
+    if page == ENTRY_PAGE:
+        return
+    # 返回根页（最多 5 次）
+    for _ in range(5):
+        try:
+            if d.find_component(BY.key("__never__")) is None:
+                pass
+        except Exception:
+            pass
+        d.press_back()
+        time.sleep(0.4)
+
+
+TAB_LABELS = ["首页", "视频", "我的"]
+
+
+def click_tab(d, label):
+    """底部 Tab 切换：定位文本→bounds 中心 touch（比例坐标兜底）"""
+    import time as _t
+    for _ in range(8):
+        try:
+            comps = d.find_all_components(BY.text(label))
+            if comps:
+                c = comps[-1]  # 底部 tab 是同名文本中最靠下的
+                b = c.getBounds()
+                cx = (b.left + b.right) // 2
+                cy = (b.top + b.bottom) // 2
+                d.touch((int(cx), int(cy)))
+                _t.sleep(1.2)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    idx = TAB_LABELS.index(label) if label in TAB_LABELS else 2
+    w, h = d.get_display_size()
+    d.touch((int(w * (idx + 0.5) / len(TAB_LABELS)), int(h * 0.945)))
+    time.sleep(1.2)
+
+
+def click_text(d, txt, wait=6):
+    """按可见文本点击（tab 名/中文按钮等无 ID 控件）。
+    先试 BY.key——无下划线的单词 id（如 fab）无法与文本区分（_is_id_like 局限），此处兜底。"""
+    import time as _t
+    try:
+        c = d.find_component(BY.key(txt))
+        if c:
+            c.click()
+            _t.sleep(1.0)
+            return
+    except Exception:
+        pass
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+            if c:
+                c.click()
+                _t.sleep(1.0)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError("text not clickable: " + txt)
+
+
+def click_type_first(d, ctype, wait=6):
+    """点击指定类型的第一个组件（lineN:Type 引用的兜底点击）"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            comps = d.find_all_components(BY.type(ctype))
+            if comps:
+                b = comps[0].getBounds()
+                d.touch(((b.left + b.right) // 2, (b.top + b.bottom) // 2))
+                _t.sleep(1.2)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError("type not clickable: " + ctype)
+
+
+def id_click(d, cid, wait=6):
+    comp = _find(d, cid, wait)
+    comp.click()
+    time.sleep(1.0)
+
+
+def id_input(d, cid, text, wait=6):
+    comp = _find(d, cid, wait)
+    d.input_text(comp, text)
+    time.sleep(0.6)
+
+
+def _find(d, cid, wait=6):
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                return c
+        except Exception:
+            pass
+        try:
+            c = d.find_component(BY.id(cid))
+            if c:
+                return c
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError("component not found: " + cid)
+
+
+def smart_click(d, cid, txt=None, wait=6):
+    """key 优先点击；失败且有 txt 时文本点击（mine 类 HAR 模块 ID 丢失边界）"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                c.click()
+                _t.sleep(1.0)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    if txt and txt.startswith("line"):
+        import re as _re
+        m = _re.match(r"line\d+:(\w+)", txt)
+        if m:
+            click_type_first(d, m.group(1), wait)
+            return
+    if txt:
+        click_text(d, txt, wait)
+        return
+    raise AssertionError("component not found: " + cid)
+
+
+def scroll_text_exist(d, txt, wait=6):
+    """滚动查找文本，双向（EXEC-005）：上滑 N 次找 → 未中则下滑回落 N 次找。
+    单向滚动在连续断言场景必挂：上一断言滑到底后，本断言目标在上方，单向永远回不去。"""
+    import time as _t
+    w, h = d.get_display_size()
+    def _check():
+        try:
+            return d.find_component(BY.text(txt, MatchPattern.CONTAINS)) is not None
+        except Exception:
+            return False
+    for direction in (UiParam.UP, UiParam.DOWN):
+        for i in range(6):
+            if _check():
+                return True
+            d.swipe(direction, distance=40)
+            _t.sleep(1.0)
+    return text_exist(d, txt, wait)
+
+
+def smart_check(d, cid, txt=None, wait=6):
+    """key 优先断言；失败且有 txt 时降级文本断言（部分 HAR 模块 .id 运行时丢弃的边界）"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    if txt and txt.startswith("line"):
+        import re as _re
+        m = _re.match(r"line\d+:(\w+)", txt)
+        if m:
+            d.check_component_exist(BY.type(m.group(1)), wait_time=wait)
+            return True
+    if txt:
+        return text_exist(d, txt, wait)
+    raise AssertionError("component not found: " + cid)
+
+
+def text_equals(d, txt, wait=6):
+    """精确文本断言（EQUALS）——CONTAINS 会被前缀污染（如 ❄️Gallery 含 Gallery），
+    恢复/状态标记类断言必须用本原语。存在且精确相等返回 True，否则抛。"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError("text (exact) not found: " + txt)
+
+
+def text_absent(d, txt, wait=3):
+    """文本不存在断言（反向；等待短暂稳定后确认消失）"""
+    import time as _t
+    _t.sleep(1.0)
+    try:
+        c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+        if c:
+            raise AssertionError("text should be absent but found: " + txt)
+    except AssertionError:
+        raise
+    except Exception:
+        pass
+    return True
+
+
+def step_shot(d, label="step"):
+    """分步截图：一个动作/断言一张页面图（run_direct 设 FORGE_SHOT_DIR/FORGE_CASE 时启用）。
+    文件名 <case>_<序号>_<label>.jpeg，供 test-report.html 按步回放页面。"""
+    import os as _os
+    base = _os.environ.get("FORGE_SHOT_DIR")
+    case = _os.environ.get("FORGE_CASE", "case")
+    if not base:
+        return
+    n = step_shot.n.get(case, 0) + 1
+    try:
+        d.screenshot(_os.path.join(base, "%s_%02d_%s.jpeg" % (case, n, label)))
+        step_shot.n[case] = n
+    except Exception:
+        pass
+
+
+step_shot.n = {}
+
+
+def wait_for(d, by, timeout=10, interval=0.5):
+    """轮询等待控件出现（首屏锚点等待用）；返回组件或 None，不抛异常"""
+    import time as _t
+    end = _t.time() + timeout
+    while _t.time() < end:
+        try:
+            c = d.find_component(by)
+            if c:
+                return c
+        except Exception:
+            pass
+        _t.sleep(interval)
+    return None
+
+
+def text_exist(d, txt, wait=6):
+    """文本存在断言（BY.text CONTAINS）。
+    契约：存在返回 True；不存在【抛 AssertionError】——永不返回 False。
+    run_direct/analyze_results 依赖异常文本做 FAIL 判定与失败聚类，勿改为静默返回。"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError("text not found: " + txt)
+
+
+def text_value_equals(d, cid, expected, wait=6):
+    """值断言（EXEC-040 实证+反证）：getText() 精确等于期望——锚定 key 控件动态内容。"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c and c.getText() == expected:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    got = None
+    try:
+        c = d.find_component(BY.key(cid))
+        got = c.getText() if c else '(not found)'
+    except Exception:
+        pass
+    raise AssertionError(f"text value mismatch: expect {expected!r} got {got!r} (key={cid})")
+
+
+def text_value_contains(d, cid, part, wait=6):
+    """值包含断言：getText() 包含子串（动态文案前缀不定时用）。"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c and part in (c.getText() or ''):
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError(f"text value not containing {part!r} (key={cid})")
+
+
+def count_equals(d, target, expected, wait=6):
+    """计数断言（EXEC-040 实证）：key 或 CONTAINS 文本匹配的组件数==期望。"""
+    import time as _t, re as _re
+    deadline = _t.time() + wait
+    last = -1
+    while _t.time() < deadline:
+        try:
+            if _re.match(r'^[a-z][a-z0-9_]+$', target):
+                comps = d.find_all_components(BY.key(target))
+            else:
+                comps = d.find_all_components(BY.text(target, MatchPattern.CONTAINS))
+            last = len(comps) if comps else 0
+            if last == expected:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError(f"count mismatch: expect {expected} got {last} (target={target})")
+
+
+def is_below(d, cid, ref_cid, wait=6):
+    """几何断言（EXEC-040 实证）：cid 的 top >= ref_cid 的 bottom（垂直次序）。"""
+    import time as _t
+    deadline = _t.time() + wait
+    while _t.time() < deadline:
+        try:
+            a = d.find_component(BY.key(cid)); b = d.find_component(BY.key(ref_cid))
+            if a and b and a.getBounds().top >= b.getBounds().bottom:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.5)
+    raise AssertionError(f"geometry: {cid} not below {ref_cid}")
+
+
+def toast_exist(d, txt, wait=4, poll=0.5):
+    """Toast 断言（v3.1）：轮询 hilog 捕获 Toast 文本。需 FORGE_HDC/FORGE_DEVICE。"""
+    import os as _os, subprocess as _sp, time as _tt
+    hdc = _os.environ.get("FORGE_HDC", "hdc"); dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    deadline = _tt.time() + wait
+    while _tt.time() < deadline:
+        try:
+            r = _sp.run([hdc, "-t", dev, "shell", "hilog", "-x"],
+                        capture_output=True, timeout=8, text=True, errors="ignore")
+            if txt in (r.stdout or ""):
+                return True
+        except Exception:
+            pass
+        _tt.sleep(poll)
+    raise AssertionError("toast not found in hilog: " + txt)
+
+
+# ── 强断言原语（2026-09-29 吸收自 none 臂实证：无 skill 的 LLM 凭通用能力即达成 34% 强断言，
+#     B 线无理由低于此——Toast/系统事件/数据断言按下表选型，禁止只写 exist）──
+def _hdc(args, timeout=20):
+    import subprocess as _sp, os as _os
+    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    cmd = [HDC_BIN, "-t", dev] + args
+    r = _sp.run(cmd, capture_output=True, timeout=timeout)
+    return (r.stdout + r.stderr).decode("utf-8", "ignore")
+
+
+def _dump_layout(timeout=20):
+    """取当前全量布局 JSON（含系统对话框/浮层），返回原始文本（Round-2：确保本地 tmp 目录存在）"""
+    import json as _json, os as _os
+    _os.makedirs("./tmp", exist_ok=True)
+    _hdc(["shell", "uitest", "dumpLayout", "-p", "/data/local/tmp/forge_dump.json"], timeout=timeout)
+    _hdc(["file", "recv", "/data/local/tmp/forge_dump.json", "./tmp/forge_dump.json"], timeout=timeout)
+    try:
+        return open("./tmp/forge_dump.json", encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def hilog_clear():
+    """清 hilog 缓冲，防止上一用例残留关键字造成假 PASS（tag=RaiseToAnswer）"""
+    _hdc(["shell", "hilog", "-r"])
+    time.sleep(0.3)
+
+
+HILOG_TAG = 'JSAPP'
+
+
+def hilog_tail(tag=None, n=400):
+    tag = tag or HILOG_TAG
+    """读取 tag 过滤的最近 n 行 hilog（诊断用）"""
+    import subprocess as _sp, os as _os
+    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    r = _sp.run([HDC_BIN, "-t", dev, "shell", "hilog", "-z", str(n), "-T", tag],
+                capture_output=True, timeout=15)
+    return r.stdout.decode("utf-8", "ignore")
+
+
+def toast_text_seen(d, txt, timeout=6):
+    """Toast 文本断言（dump 版）。无 ID 例外：Toast 为瞬时浮层无稳定 ID，且 hypium find_component
+    实测看不到 Toast 子窗口，故以 uitest dumpLayout 原文轮询（首轮实测教训 Round-1）。"""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        raw = _dump_layout()
+        if txt in raw:
+            return True
+        time.sleep(0.6)
+    raise AssertionError("toast not seen: " + txt)
+
+
+def bm_clean():
+    """清应用持久化数据（公开包装；import * 不导出 _ 前缀——Round-1 教训）"""
+    _hdc(["shell", "bm", "clean", "-n", PACKAGE, "-d"])
+    time.sleep(0.6)