argent-test-ui-flow

跨平台

实体 iPhone（kind: "device"）：首先读取 argent-ios-device-interact。执行任何操作前先调用 launch-app；应用处于后台时，describe 会失败。

iOS 和 Android 上的交互工具名称相同（gesture-tap、gesture-swipe、describe、screenshot、launch-app 等），工具服务器会根据你传入的 udid 自动分派（UUID 格式 → iOS，adb 序列号 → Android）。

测试前，请确定要在哪台设备上测试。 调用 list-devices 并遵循 <device_selection_rule>：优先选择任意平台上正在运行的设备；

确定平台后，使用对应平台的设置技能：

平台	设置技能	查找设备
iOS	argent-ios-simulator-setup	list-devices → 如果没有已启动的设备，则使用 udid 调用 boot-device
Android	argent-android-emulator-setup	list-devices → 如果没有就绪的设备，则使用 avdName 调用 boot-device

1. 工作流

所有交互都通过 argent MCP 工具进行。开始前，请确保模拟器/仿真器已就绪。

对于会修改可见 UI 的实现任务，此工作流也可作为视觉验收路径。

1. 基准截图：调用 screenshot 查看当前 UI 状态。进行视觉回归比较或验证 UI 变更时，请在编辑前尽可能以 scale: 1.0 和 includeImageInContext: false 捕获基准截图，并保留返回的 path。
2. 查找目标：点击前，使用发现工具获取元素坐标：
   • React Native 应用：使用 debugger-component-tree：它会返回组件名称和 (tap: x,y) 坐标。这是两个平台上 RN 应用的首选工具。要使用它，请解析 argent-react-native-app-workflow 技能以完成设置；在 Android 上，还必须运行 adb -s <serial> reverse tcp:8081 tcp:8081，以便设备能够访问 Metro。
   • 标准应用屏幕和应用内模态框：使用 describe。在 iOS 上，它会返回 AX 树（如果 AX 为空，则回退到 native-devtools）；在 Android 上，它会以相同的 DescribeNode 形状返回 uiautomator 树。
   • 权限提示/系统模态浮层：先尝试 describe。只有在无法可靠地从浮层中获取信息时，才回退到 screenshot。当应用弹出自己的权限对话框时，请在此处作答；这才是正在测试的真实流程。若要将提示从流程中移除（在启动前预先授予/拒绝权限、重新启用用户已拒绝的权限，或重置权限以使对话框重新出现），请在设置期间使用 argent-settings-permissions 技能，而不要与对话框交互。
   • 回退方案：使用 screenshot 估算目标组件的位置，然后在操作后立即验证。
3. 交互：执行操作（gesture-tap、gesture-swipe、keyboard、button 等）；你会自动收到一张截图。
4. 验证：检查返回的截图，确认结果符合预期。如果显示加载/过渡状态，应优先使用 await-ui-element 阻塞等待状态稳定（预期元素 visible，或微调器 hidden），而不是猜测延迟；但只能使用可信的选择器（text/identifier/role），且屏幕上已知存在该选择器，或你在之前的 describe 中见过它；猜测的选择器只会导致超时。否则，使用较短的固定等待时间。根据要断言的内容选择证据：
   • 视觉（布局、间距、颜色、字体排版、图像/图标渲染、裁切、溢出、文本渲染）：优先使用第 1 步捕获的基准图执行 screenshot-diff；它能呈现自动截图可能遗漏的像素级可见变化。只有在没有稳定基准图时，才回退到目视检查自动截图。
   • 结构（导航状态、元素是否存在、无障碍标签/值、选中状态、层级、路由）：使用 describe、debugger-component-tree 或 native-describe-screen 验证。
   • 运行时/日志/网络（控制台错误、API 调用、持久化、时序）：使用 view-network-logs、debugger-log-registry、debugger-evaluate 或针对性测试进行验证。请注意，如果调试器无法访问，debugger-log-registry 会返回 { status: "not_connected", reason, guidance }，且不会提供日志文件；这并不能作为应用的证据。请按照其 guidance 重新连接，然后再次验证。
   • 混合：为每种相关类型收集证据。
   • 报告综合结论：预期行为、观察到的行为、使用的证据，以及请求的视觉差异检查是否存在任何阻碍。
5. 重复，处理流程中的每一步。

2. 模板

Goal: Test [feature name]

Steps:
1. Classify expected result: visual / structural / runtime-log-network / mixed → choose evidence
2. [Navigate / tap / type to reach stable comparable starting point] → verify auto-screenshot
3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path when visual or mixed evidence needs diffing
4. [Perform the action to test] → verify auto-screenshot
5. Use screenshot-diff when requested or when comparable images add useful visual evidence
6. Report: pass / fail with combined visual, structural, runtime/log/network evidence as applicable

3. 示例

登录流程

1. screenshot → see login screen
2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
3. keyboard { text: "[email protected]" }
4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
5. keyboard { text: "{{secret:APP_PASSWORD}}" }
6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
7. screenshot → verify home screen appeared

**凭据：**切勿输入明文凭据；请在 keyboard 中使用 {{secret:<NAME>}} 占位符，由服务端解析，这样值就不会进入 Agent 上下文。该值来自 ARGENT_SECRET_<NAME> 环境变量，或 argent 密钥文件（项目中的 .argent/secrets.env、~/.argent/secrets.env，或项目 .env / .env.local 中以 ARGENT_SECRET_ 为前缀的键）。如果未定义该名称，错误信息会列出可用名称和检查过的每个路径；请让用户将其添加到其中一个文件中（添加后立即生效），而不是将密钥粘贴到对话中。切勿编造凭据，也不要在报告或保存的文件中回显密钥值。

滚动与导航

1. screenshot → see list at top
2. gesture-swipe { fromY: 0.7, toY: 0.3 } → scroll down
3. gesture-tap item at visible position → verify auto-screenshot
4. screenshot → verify detail view opened
5. button { button: "back" }
6. screenshot → verify returned to list

视觉行为检查

1. Classify expected result as visual or mixed.
2. Navigate to the stable starting state.
3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path.
4. describe / debugger-component-tree → find the control and use its returned tap coordinates.
5. gesture-tap → perform the visual behavior under test.
6. screenshot-diff { baselinePath, captureCurrent: true, udid, outputDir } → inspect visible change or stability.
7. describe / debugger-component-tree → verify selected state, label, route, or attributes if relevant.
8. Report combined verdict from expected behavior, visual inspection, diff summary, and structural evidence.

等待加载指示器

1. gesture-tap { x: 0.5, y: 0.7 } → trigger an action that fetches data
2. screenshot → loading spinner is showing
3. await-ui-element { condition: hidden, selector: { text: "Loading" } } → block until the fetch finishes and the spinner disappears; its result carries the screenshot and element tree, so verify the fetched content rendered from it

---

4. 恢复模式

• 如果屏幕正处于转换或加载过程中：使用 await-ui-element 阻塞等待，直到状态稳定（等待目标元素变为 visible，或微调器／占位符变为 hidden），而不是盲目固定延时，然后重新检查。只有在没有元素能可靠标记转换状态时，才使用固定等待时间并调用 screenshot 作为后备方案。
• 如果点击未命中目标：重新运行发现工具（describe / debugger-component-tree），使用新坐标重试一次。
• 如果权限对话框或模态框可见：先重新运行 describe。只有在无法可靠地通过该工具查看覆盖层时，才继续使用基于截图的导航；覆盖层关闭后，立即切回 describe / debugger-component-tree。
• 如果在相同坐标点击两次都失败：停止操作，重新发现；如果未找到元素，则报告情况。
• 如果已保存的 e2e 测试在 e2e-execute 重放期间失败（而非上述实时测试步骤）：按照 argent-create-e2e 的诊断重放失败操作：对失败进行分类，检查实际屏幕，修复有充分依据的最小单元，然后重放完整的 e2e 测试。

提示

• 等待 UI，不要轮询。 如果某个步骤需要等待屏幕先发生变化，请使用 await-ui-element 作为门控（阻塞直到元素变为 visible / hidden 或包含 text），而不是反复调用 screenshot 并进行固定时长的休眠。请参阅 argent-device-interact 中的 await-ui-element 部分。
• 对长按上下文菜单（按住 800ms），使用 gesture-custom。
• **清晰报告：**说明预期情况、实际观察结果和判定。
• **权限模态框：**先尝试 describe。仅在后备情况下使用 screenshot；每次点击一个可见按钮，并在继续操作前通过返回的截图确认。
• **记录以便重放：**如果测试过的流程可能会重复执行，请使用 argent-create-e2e 技能将其记录为 .yaml 脚本。这样之后只需调用一次 e2e-execute，即可重放整个序列，无需手动重新执行每个步骤。

相关技能

技能	使用时机
argent-device-interact	点击、滑动、输入等工具的用法（iOS + Android）
argent-screenshot-diff	视觉回归和前后截图对比
argent-ios-simulator-setup	启动并连接 iOS 模拟器
argent-android-emulator-setup	启动并连接 Android 模拟器
argent-react-native-app-workflow	启动应用、Metro、构建问题
argent-metro-debugger	控制台日志、JS 求值、组件检查
argent-create-e2e	将测试序列记录为可重放的 e2e 测试