SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mobile-sim-verification

mobile-sim-verification

测试与质量

查看项目

更新于 10-30 16:30

技能介绍

用途

mobile-sim-verification 是 cdp-verification 的移动端对应物，用于在 iOS 模拟器上对 apps/mobile 的行为做端到端验证。手机上不存在 CDP，因此输入通过 Maestro 完成，证据来自 simctl 截图与录屏，状态来自真实的本地 API 和 relay。资料把内容分为“规则”（什么算有效证据）和“机制”（如何做到）两部分，并指出 apps/mobile/scripts/e2e/host-states.sh 是一个可运行的示例。

主要能力与验证规则

  • 使用真实界面：像用户一样登录并到达目标页面。临时预览路由只挂载一个带固定 props 的组件，属于诊断辅助，必须如实说明，因为它会隐藏头部、数据钩子、加载状态和导航。
  • 通过真实服务驱动状态：通过改动本地 API 或 relay（注册主机、打开或关闭其 socket）来改变应用看到的内容，而不是向查询缓存里塞数据。
  • 报告“已测试”前先跑边界用例：主路径不算测试。至少包括冷启动、依赖宕机（relay 或 API 停止）、恢复、应用进入后台再恢复、快速状态抖动、超长名称、一个长字符串语言（德语）和一个中日韩语言、最大字号；并说明哪些跑了、哪些没跑。
  • 不要把“unknown”显示成否定结论：处于 pending 或 failed 的查询并不等于说了“离线”“空”或“无”。要检查两种状态下屏幕实际绘制的内容，资料称这是该流程发现的最常见移动端 bug。
  • 用录屏捕捉闪烁：睡一会儿再截图无法捕捉只持续半秒的状态；录下启动过程并逐帧比对。
  • 正确归因失败：在报告某个检查在 main 上失败前，先在 CI 中确认。新的 worktree 上移动端 typecheck 可能显示 CI 并不会出现的无关包错误。

使用方式（机制）

服务启动：每个服务都在 Superset 终端中启动以在工具调用结束后存活，--local 为必需参数： superset terminals create --local --workspace "$SUPERSET_WORKSPACE_ID" --command "<cmd>"

  • API：cd apps/api && bun run dev。若出现 password authentication failed 的 500，说明该 worktree 的 Neon 分支被每日清理删除，需按 .superset/lib/setup/steps.sh 的方式重建，并改写 .env 中 # Workspace Database 下的三行。
  • Relay：在循环中运行。客户端中断请求时 wrangler dev 会以空的 ✘ [ERROR] 退出，而每次重启应用都会发生这种情况；Durable Object 状态在重启后仍保留。
  • Realtime：bun dev:realtime，在该 worktree 的 REALTIME_PORT 上运行 Worker，退出时自动重启；没有它应用会退回轮询，提示无法送达。
  • Metro：cd apps/mobile && CI=1 bunx expo start --dev-client --port 8081。CI=1 关闭文件监听，改代码后需重启 Metro；依赖变更后首次打包需数分钟，dev client 会等不及，可先用 curl -H 'expo-platform: ios' localhost:8081 取 launchAsset.url 预热。

应用：模拟器上需安装 dev-client 构建。仅当原生依赖未变时可复用 DerivedData 中的构建；否则先 bunx expo prebuild -p ios，再用 xcodebuild 构建并 xcrun simctl install 安装。纯 JavaScript 改动无需重新构建。ios/ 已被 gitignore。首次开发者菜单可通过 simctl spawn booted defaults write 关闭。登录用 maestro test apps/mobile/.maestro/flows/sign-in.yml。dev 账号没有套餐，Home 会显示付费墙，可在该 worktree 的 Neon 分支给其组织临时插入一条订阅记录，事后删除；插入前先确认 DATABASE_URL_UNPOOLED 是工作区分支。

无第二台机器时的主机：apps/mobile/scripts/e2e/stand-in-host.ts 通过 host.ensure 注册主机，保持 relay 控制 socket 打开使其在线，读取其 presence，最后通过 host.delete 删除；它拒绝对非本地 API 运行。在线期间它接收应用的 stream:dial 票据但不作应答，因此该主机背后的列表会一直加载。

证据采集：可用 simctl status_bar 覆盖时间与电量，simctl io 截图，simctl io recordVideo 录屏（SIGINT 停止），再用 ffmpeg 抽帧；用 defaults write 切换语言，用 simctl ui 设置内容字号。通过 relay 日志统计请求数来证明轮询行为（例如后台时没有请求）。结束后要重置语言、字号和状态栏，停止服务，删除测试主机和临时套餐。

无 Mac（Linux、云工作区）：apps/mobile/scripts/eas-dev.sh 在 EAS 云模拟器上运行 dev client，详见 .agents/skills/mobile-eas-dev/SKILL.md。simctl 步骤改为 agent-device 命令，模拟器只能通过本地出口访问本机。脚本会安装与该 checkout 指纹匹配的模拟器构建，仅在原生变更后才构建。它转发 Metro、API、relay 和 realtime 端口；未转发的端口在应用里表现为网络错误，relay 未运行则 Home 提示无法检查主机。输入用 agent-device snapshot -i、press、fill、screenshot，press 和 fill 支持 --settle 并打印变化；开发者菜单会遮住首屏，先按 Continue 再 Close。请求计数见 /tmp/superset-eas-egress.log。云工作区方面，工作区的 Neon 分支是生产副本，云访问取决于邮箱上的 PostHog 开关，dev 账号看不到云工作区，优先使用带该开关的测试账号；仅在账号所有者同意下使用真实账号，并保存其 auth.accounts 凭据密码、设置临时哈希、用“Sign in with email (dev)”登录，测试后恢复哈希并删除测试创建的会话。清理时在 apps/mobile 下执行 eas simulator:stop（会话按运行计费，闲置 15 分钟后自动停止），本地进程按 PID 停止，因为 pkill -f 也会匹配运行它的 shell。

适用场景与限制

该技能适合维护 apps/mobile 并需要可复现、可归因的 iOS 端到端验证证据的开发者，尤其在没有第二台真机、需要模拟主机在线状态或需要跨语言与字号做边界验证时。它是一套流程与命令参考，不提供图形化产品功能；资料未说明收费、价格、正式发布平台或效果指标。引用具体命令时需注意其中的 Superset、Neon、EAS、agent-device 等环境依赖，缺失的环境事实需按实际部署确认。