Neo-ZQYY/_DEL/weixin-devtools/steering/workflow.md

微信开发者工具自动化工作流

连接策略

首次连接

connect_devtools（strategy: "auto"）

auto 策略会依次尝试：发现已运行实例 → 通过 CLI 启动 → ws 直连。

连接失败排查

1. check_environment — 检查 CLI 路径、项目路径是否正确
2. diagnose_connection — 检查端口、进程状态
3. 确认开发者工具「设置 → 安全 → 服务端口」已开启

重连

reconnect_devtools  // 复用上次参数

页面导航模式

普通页面跳转

navigate_to(url: "/pages/task/task-list/index", params: { status: "pending" })

TabBar 页面

switch_tab(url: "/pages/index/index")

注意：navigate_to 无法跳转 TabBar 页面，必须用 switch_tab。

重启并跳转

relaunch(url: "/pages/index/index")

清空页面栈，适合需要干净状态的场景。

返回

navigate_back(delta: 1)  // 返回上一页
navigate_back(delta: 2)  // 返回两层

元素操作最佳实践

操作流程（必须遵循）

1. get_page_snapshot 获取当前页面所有元素的 uid
2. 从快照中找到目标元素的 uid
3. 用 uid 执行操作（click / input_text / get_value / assert_*）

快照格式选择

• compact（默认推荐）：含 uid、标签、文本、位置、尺寸，token 用量减少 60-70%
• minimal：只含 uid、标签、文本，最省 token
• json：完整 JSON，需要属性详情时用

CSS 选择器查找

$("view.container")     // 类名
$("#myId")              // ID
$("text=按钮")          // 文本匹配

返回匹配元素的详细信息，适合精确定位。

输入文本

input_text(uid: "xxx", text: "测试内容")
input_text(uid: "xxx", text: "追加内容", append: true)
input_text(uid: "xxx", text: "新内容", clear: true)  // 先清空再输入

表单控件

set_form_control(uid: "xxx", value: 2)          // picker 选第3项
set_form_control(uid: "xxx", value: true)        // switch 开启
set_form_control(uid: "xxx", value: 50)          // slider 设为50

断言验证

文本断言

assert_text(uid: "xxx", text: "精确匹配")
assert_text(uid: "xxx", textContains: "包含")
assert_text(uid: "xxx", textMatches: "\\d{4}-\\d{2}-\\d{2}")  // 正则

状态断言

assert_state(uid: "xxx", visible: true)
assert_state(uid: "xxx", enabled: false)
assert_state(uid: "xxx", checked: true)

属性断言

assert_attribute(uid: "xxx", attributeKey: "class", attributeValue: "active")

JS 执行

读取页面数据

evaluate_script({
  function: "() => { const pages = getCurrentPages(); return pages[pages.length-1].data; }"
})

读取全局数据

evaluate_script({
  function: "() => { return getApp().globalData; }"
})

调用 wx API

evaluate_script({
  function: "() => { return wx.getSystemInfoSync(); }"
})

带参数执行

evaluate_script({
  function: "(key) => { return wx.getStorageSync(key); }",
  args: ["userToken"]
})

截图与视觉验证

保存截图到文件

screenshot(path: "C:/Project/NeoZQYY/export/screenshots/task-list.png")

配合 pixel-audit Power 做视觉对比

1. H5 页面用 Playwright 截图
2. MP 页面用 screenshot 截图
3. 用 image-compare（已集成在 pixel-audit）对比差异

网络请求监控

查看请求

get_network_requests(urlPattern: "api/v1/tasks", limit: 10)
get_network_requests(type: "request", successOnly: true)

清空并重新监控

clear_network_requests → 执行操作 → get_network_requests

等待策略

等待元素出现

waitFor(selector: ".loading", disappear: true, timeout: 10000)  // 等 loading 消失
waitFor(selector: ".task-card", timeout: 5000)                   // 等元素出现
waitFor(text: "加载完成", timeout: 5000)                         // 等文本出现

固定延时

waitFor(delay: 2000)  // 等待 2 秒

常见问题

问题	解决方案
连接超时	检查 9420 端口是否开启，diagnose_connection
元素找不到	先 get_page_snapshot 确认页面已加载完成
navigate_to 失败	TabBar 页面必须用 switch_tab
evaluate_script 报错	函数不能引用外部闭包变量，必须自包含
截图空白	页面可能还在加载，先 waitFor