argent-test-ui-flow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Platform-agnostic

跨平台兼容

The interaction tool names are identical on iOS and Android —

gesture-tap

gesture-swipe

describe

screenshot

launch-app

, etc. — and the tool-server auto-dispatches based on the

udid

you pass (UUID-shape → iOS, adb serial → Android).

Before testing, resolve which device to test on. Call

list-devices

and follow

<device_selection_rule>

: prefer a running device on any platform;

Once a platform is chosen, the per-platform setup skill takes over:

Platform	Setup skill	Find devices with
iOS	`argent-ios-simulator-setup`	`list-devices` → `boot-device` with `udid` if none booted
Android	`argent-android-emulator-setup`	`list-devices` → `boot-device` with `avdName` if none ready

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. Workflow

1. 工作流程

All interactions go through argent MCP tools. Ensure the simulator/emulator is ready before starting.

Baseline screenshot: Call
```
screenshot
```
to see the current UI state.
Find target: Before tapping, use a discovery tool to get element coordinates:
- React Native apps: use
```
debugger-component-tree
```
  — it returns component names with (tap: x,y) coordinates. This is the preferred tool for RN apps on either platform. To use it, resolve the
```
argent-react-native-app-workflow
```
  skill for setup; on Android you must also run
```
adb -s <serial> reverse tcp:8081 tcp:8081
```
  so Metro is reachable from the device.
- Standard app screens and in-app modals: use
```
describe
```
  . On iOS this returns the AX tree (falls back to native-devtools when AX is empty); on Android it returns the uiautomator tree in the same DescribeNode shape.
- Permission prompts / system modal overlays: try
```
describe
```
  first. Fall back to
```
screenshot
```
  only if the overlay is not exposed reliably.
- Fallback: use
```
screenshot
```
  to estimate where the desired component is, then verify immediately after the action.
Interact: Perform the action (
```
gesture-tap
```
,
```
gesture-swipe
```
,
```
keyboard
```
,
```
button
```
, ...) — you receive a screenshot automatically.
Verify: Check the returned screenshot for expected results. If it shows a loading/transitional state, retake with
```
screenshot
```
.
Repeat for each step in the flow.

所有交互均通过argent MCP工具完成。开始前请确保模拟器/模拟器已就绪。

基准截图：调用
```
screenshot
```
查看当前UI状态。
定位目标元素：点击前，使用发现工具获取元素坐标：
- React Native应用：使用
```
debugger-component-tree
```
  —— 它会返回组件名称及（点击坐标：x,y）。这是RN应用在任一平台上的首选工具。使用前需调用
```
argent-react-native-app-workflow
```
  技能完成设置；Android平台上还需运行
```
adb -s <serial> reverse tcp:8081 tcp:8081
```
  ，确保设备可访问Metro。
- 标准应用界面与应用内弹窗：使用
```
describe
```
  。iOS平台会返回AX树（AX为空时 fallback 到原生开发工具）；Android平台会返回同DescribeNode格式的uiautomator树。
- 权限提示/系统弹窗覆盖层：优先尝试
```
describe
```
  。仅当覆盖层无法可靠识别时，才 fallback 到
```
screenshot
```
  。
- 最终方案：使用
```
screenshot
```
  估算目标组件位置，操作后立即验证。
执行交互：执行操作（
```
gesture-tap
```
、
```
gesture-swipe
```
、
```
keyboard
```
、
```
button
```
等）—— 系统会自动返回截图。
验证结果：检查返回的截图是否符合预期。若显示加载/过渡状态，使用
```
screenshot
```
重新截图。
重复执行：针对流程中的每一步重复上述操作。

2. Template

2. 模板

Goal: Test [feature name]

Steps:
1. screenshot → see current state (baseline)
2. [Navigate / tap / type to reach starting point] → verify auto-screenshot
3. [Perform the action to test] → verify auto-screenshot
4. Report: pass / fail with details

目标：测试[功能名称]

步骤：
1. screenshot → 查看当前状态（基准）
2. [导航/点击/输入以到达起始点] → 验证自动截图
3. [执行待测试操作] → 验证自动截图
4. 报告：通过/失败及详细信息

3. Examples

3. 示例

Login flow

登录流程

1. screenshot → see login screen
2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
3. paste { text: "user@example.com" }
4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
5. paste { text: "password123" }
6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
7. screenshot → verify home screen appeared

1. screenshot → 查看登录界面
2. gesture-tap { x: 0.5, y: 0.4 }  → 点击邮箱输入框
3. paste { text: "user@example.com" }
4. gesture-tap { x: 0.5, y: 0.55 } → 点击密码输入框
5. paste { text: "password123" }
6. gesture-tap { x: 0.5, y: 0.7 }  → 点击登录按钮
7. screenshot → 验证首页已显示

Scroll and navigation

滚动与导航

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. screenshot → 查看列表顶部
2. gesture-swipe { fromY: 0.7, toY: 0.3 } → 向下滚动
3. gesture-tap 可见位置的项目 → 验证自动截图
4. screenshot → 验证详情页已打开
5. button { button: "back" }
6. screenshot → 验证已返回列表

4. Recovery Pattern

4. 恢复机制

If screenshot shows loading/transition: wait 500ms, retake with
```
screenshot
```
.
If tap misses target: re-run discovery tool (
```
describe
```
/
```
debugger-component-tree
```
), retry once with new coordinates.
If a permission dialog or modal is visible: re-run
```
describe
```
first. Stay in screenshot-driven navigation only when the overlay is not exposed reliably, then switch back to
```
describe
```
/
```
debugger-component-tree
```
as soon as it is dismissed.
If tap fails twice at same coordinates: stop, re-discover, report if element not found.
If a saved flow fails during
```
flow-execute
```
replay (as opposed to live test steps above): follow
```
argent-create-flow
```
skill §10 for structured diagnosis and correction.

若截图显示加载/过渡状态：等待500ms，使用
```
screenshot
```
重新截图。
若点击未命中目标：重新运行发现工具（
```
describe
```
/
```
debugger-component-tree
```
），使用新坐标重试一次。
若权限弹窗或模态框可见：先重新运行
```
describe
```
。仅当覆盖层无法可靠识别时，才采用截图驱动导航，覆盖层消失后立即切换回
```
describe
```
/
```
debugger-component-tree
```
。
若同一坐标连续两次点击失败：停止操作，重新查找元素，若未找到则上报。
若已保存的流程在
```
flow-execute
```
重放时失败（与上述实时测试步骤不同）：遵循
```
argent-create-flow
```
技能第10节进行结构化诊断与修正。

Tips

提示

Use
paste
for text entry on iOS — faster and more reliable than key-by-key
```
keyboard
```
.
```
paste
```
is iOS-only; on Android use
```
keyboard
```
instead.
Use
gesture-custom
for long-press context menus (800ms hold).
Report clearly: state what you expected, what you saw, and the verdict.
Coordinate estimation: center = 0.5, 0.5; top-third ~ 0.2; bottom-third ~ 0.8.
Permission modals: try
```
describe
```
first. Use
```
screenshot
```
only as fallback, tap one visible button at a time, and verify with the returned screenshot before continuing.
Record for replay: If a tested flow is likely to be repeated, use the
```
argent-create-flow
```
skill to record it as a
```
.yaml
```
script. This lets you replay the entire sequence later with a single
```
flow-execute
```
call instead of re-running each step manually.

iOS文本输入使用
paste
—— 比逐键输入
```
keyboard
```
更快更可靠。
```
paste
```
仅支持iOS；Android平台请使用
```
keyboard
```
。
长按上下文菜单使用
gesture-custom
（按住800ms）。
清晰报告：说明预期结果、实际结果及判定结论。
坐标估算：中心为0.5, 0.5；上三分之一约为0.2；下三分之一约为0.8。
权限弹窗：优先尝试
```
describe
```
。仅作为最后手段使用
```
screenshot
```
，每次点击一个可见按钮，继续操作前需通过返回的截图验证结果。
录制流程以便重放：若测试的流程可能重复执行，使用
```
argent-create-flow
```
技能将其录制为
```
.yaml
```
脚本。后续只需调用一次
```
flow-execute
```
即可重放整个序列，无需手动重复每一步。

Skill	When to use
`argent-device-interact`	Tool usage for tapping, swiping, typing (iOS + Android)
`argent-ios-simulator-setup`	Booting and connecting an iOS simulator
`argent-android-emulator-setup`	Booting and connecting an Android emulator
`argent-react-native-app-workflow`	Starting the app, Metro, build issues
`argent-metro-debugger`	Breakpoints, console logs, JS evaluation
`argent-create-flow`	Record a test sequence as a replayable flow

技能名称	使用场景
`argent-device-interact`	iOS和Android平台的点击、滑动、输入等工具使用
`argent-ios-simulator-setup`	启动并连接iOS模拟器
`argent-android-emulator-setup`	启动并连接Android模拟器
`argent-react-native-app-workflow`	应用启动、Metro配置、构建问题处理
`argent-metro-debugger`	断点设置、控制台日志查看、JS代码评估
`argent-create-flow`	将测试序列录制为可重放的流程