uni-app的app端自动化测试必须使用uni-automator，因其通过websocket连接真机/模拟器，驱动原生ui并跨平台一致执行；jest仅运行于node环境，无法访问page对象、触发渲染或平台特有api。
App端自动化测试在uni-app里不是“配个Jest就能跑”，必须走 uni-automator 这条路径——它才是唯一能真正驱动真机/模拟器、操作原生UI、跨Android/iOS一致执行的方案。Jest只适合单元测试，对App端页面渲染、手势、生命周期等完全无感知。
为什么不能直接用Jest跑App端测试
Jest运行在Node环境，模拟的是JS执行上下文，不启动App容器，也不连接设备。你写 page.$('.btn') 会直接报错：找不到 page 对象，因为 program.currentPage() 是 uni-automator 提供的、依赖WebSocket与真机通信的API，Jest根本加载不了。
- 常见错误现象：
TypeError: Cannot read property 'currentPage' of undefined或ReferenceError: program is not defined - 即使 mock 了
program，也无法触发原生渲染、WebView跳转、uni.showToast 等真实行为 - App端的组件层级、样式计算、平台差异（如iOS导航栏高度、Android软键盘弹起）全靠真机环境验证
uni-automator 初始化失败的三个高频原因
装完插件、配好脚本，npm run test:android 却卡在“正在启动基座”或报 adb device not found，大概率是下面这几个点没对上：
ApiPost是一个支持团队协作，支持模拟POST、GET、PUT等常见请求，并可直接生成文档的API调试、管理工具，ApiPost是后台接口开发者或前端、接口测试人员的工作必备工具。快速生成、一键导出API文档。感兴趣的朋友快来下载吧。软件说明ApiPost官方版是一款十分出色的接口调试与文档生成工具，ApiPost官方版界面美观大方，功能强劲实用，支持团队协作，支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员的工作必备工具。软件特色更方便支持接口调试的同时快速生成、一键
-
env.js文件缺失或路径错误：必须放在项目根目录，且内容要明确指定adbPath（Windows下需是完整路径如C:\platform-tools\adb.exe），Mac/Linux则用/usr/local/bin/adb - Android设备未开启USB调试 + “安装未知应用”权限；iOS需用HBuilderX连接模拟器（真机需额外配置证书和信任）
- 基座（runtime）版本不匹配：HBuilderX菜单 → 运行 → 构建自定义基座 → 确保已构建对应平台的最新版基座，并在
env.js中指向其路径，例如appAndroidRuntimePath: './unpackage/dist/dev/app-android'
test:android 和 test:ios 的关键参数差异
两者都依赖 UNI_PLATFORM 环境变量，但底层调用链完全不同，影响实际执行行为：
-
UNI_PLATFORM=app-android：走 adb 启动、注入 instrumentation、监听 logcat 输出；要求设备在线、adb 可识别、基座已安装 -
UNI_PLATFORM=app-ios：仅支持 macOS + 模拟器；依赖 Xcode 命令行工具（xcrun）和simctl控制模拟器；真机需额外签名，目前官方不推荐用于CI - 共性限制：两个命令都绕不开
jest.config.js中的testEnvironment: 'node'——这不是指Node环境跑App，而是告诉Jest“不要加载jsdom”，由uni-automator自己接管页面实例
page.$() 选择器在App端的实际表现
page.$('.login-btn') 看似简单，但在App端会因平台、基座版本、组件编译模式（vue vs uvue）产生不同结果：
- Android上可能匹配到
div元素，iOS模拟器却返回空 —— 因为uvue编译后生成的原生View ID规则不同 - 推荐优先用
data-testid属性：在模板中加data-testid="submit-btn"，测试时写page.$('[data-testid="submit-btn"]')，稳定且不依赖样式类名 - 避免用
page.$$()获取列表再取[0]，App端元素加载有延迟，应配合await page.waitForSelector('[data-testid="submit-btn"]')
最易被忽略的是：每次修改 env.js 或基座路径后，必须重启HBuilderX，否则旧配置仍被缓存；另外，uni-automator 的日志默认不输出到控制台，要看详细报错得打开HBuilderX底部面板里的“测试控制台”并勾选“显示详细日志”。
