入门篇

从零开始，学会写基本的自动化流程。

文件结构

每个 .yaml 文件由两部分组成，用 --- 分隔：

yaml

# ═══ 第一部分：配置区（头部）═══
appId: com.example.app         # 必填：目标 App 的包名
name: 我的流程                   # 选填：给流程取个名字
tags: [测试, 登录]               # 选填：标签分类
env:                            # 选填：变量定义
  USERNAME: admin

# ═══ 分隔线 ═══
---

# ═══ 第二部分：命令区（步骤列表）═══
- launchApp
- tapOn: "登录"
- inputText: "hello"

配置字段	是否必填	说明
`appId`	必填	目标 App 包名，如 `com.android.settings`
`name`	选填	流程的显示名称
`tags`	选填	标签数组，用于分类管理
`env`	选填	环境变量，在命令中通过 `${KEY}` 引用
`url`	选填	流程启动时自动打开的 URL
`properties`	选填	自定义属性键值对
`onFlowStart`	选填	流程开始前执行的命令（见高级篇）
`onFlowComplete`	选填	流程结束后执行的命令（见高级篇）
`exceptionHandlers`	选填	自动处理弹窗（见进阶篇）

第一个 Flow：打开设置

创建文件 my-first-flow.yaml：

yaml

appId: com.android.settings
name: 我的第一个流程
---
- launchApp
- assertVisible: "设置"

这个流程做了两件事：

启动 Android 设置 App
验证屏幕上出现了"设置"这两个字

如果"设置"出现了，流程成功；如果 17 秒内没出现，流程报错。

点击元素 tapOn

tapOn 是最常用的命令——在屏幕上找到某个元素并点击它。

简写形式：直接写文字

yaml

- tapOn: "登录"

引擎会在屏幕上找到显示"登录"的元素，然后点击它。

对象形式：更多控制

yaml

- tapOn:
    text: "登录"

效果和简写完全相同，但对象形式可以加更多参数：

yaml

- tapOn:
    text: "登录"
    optional: true              # 找不到也不报错，跳过继续

yaml

- tapOn:
    id: "btn_login"             # 通过元素 ID 查找（比文字更精确）

yaml

- tapOn:
    text: "提交"
    retryTapIfNoChange: true    # 点击后如果界面没变化，自动重试

yaml

- tapOn:
    text: "加载中按钮"
    waitUntilVisible: true      # 等元素出现后再点击

等待界面稳定

yaml

- tapOn:
    text: "登录"
    waitToSettleTimeoutMs: 3000  # 点击后等界面稳定，最多等 3 秒

waitToSettleTimeoutMs 上限为 30000 毫秒，超过会自动限制为 30000。

连续点击

yaml

- tapOn:
    text: "+"
    repeat: 5                   # 连续点击 5 次
    delay: 200                  # 每次间隔 200 毫秒（默认 100 毫秒）

输入文字 inputText

在当前光标所在的输入框中输入文字。

yaml

- inputText: "hello world"

通常搭配 tapOn 先点击输入框：

yaml

- tapOn: "用户名"               # 先点击输入框
- inputText: "admin"            # 再输入文字

支持使用变量（见进阶篇）：

yaml

- inputText: "${USERNAME}"

数字也可以直接输入：

yaml

- inputText: 123456

删除文字 eraseText

删除输入框中的文字。

yaml

- eraseText                     # 删除最多 50 个字符（默认）

指定删除数量（两种写法）：

yaml

- eraseText: 10                 # 简写：删除 10 个字符

- eraseText:
    charactersToErase: 10       # 对象形式：删除 10 个字符

滑动 swipe

模拟手指滑动操作。

方向滑动

yaml

# 简写形式
- swipe: UP                     # 向上滑

# 对象形式
- swipe:
    direction: UP               # 向上滑（刷新闻、翻视频常用）

四个方向：UP、DOWN、LEFT、RIGHT。

控制滑动速度

yaml

- swipe:
    direction: UP
    duration: 400               # 滑动耗时 400 毫秒（数值越大越慢）

随机速度

yaml

- swipe:
    direction: UP
    duration: [200, 500]        # 每次随机在 200~500 毫秒之间

从元素位置滑动

yaml

- swipe:
    direction: LEFT
    from:                       # 从这个元素的中心开始滑动
      text: "卡片标题"
    duration: 500

滑动后不等待界面稳定

yaml

- swipe:
    direction: UP
    waitToSettleTimeoutMs: 0    # 滑动后不等待界面稳定（适合连续快速滑动）

滚动 scroll

最简单的滚动——向上滑动一次，让页面内容向下滚动。

yaml

- scroll

等效于 swipe: { direction: UP }，但更简洁。

返回键 back

模拟按下 Android 返回键。

yaml

- back

也可以用来收起键盘。

等待与延时 sleep

暂停执行，等待指定时间。

固定等待

yaml

- sleep: 2000                   # 等待 2 秒（单位：毫秒）

随机等待

yaml

- sleep: [3000, 8000]           # 随机等待 3~8 秒

对象形式

yaml

# 固定等待
- sleep:
    duration: 2000

# 随机范围
- sleep:
    min: 3000
    max: 8000

验证界面 assertVisible / assertNotVisible

检查屏幕上是否出现了某个元素。如果检查不通过，流程会报错停止。

验证元素可见

yaml

- assertVisible: "欢迎回来"     # 屏幕上必须出现"欢迎回来"

默认等待 17 秒。17 秒内出现就通过，否则报错。

验证元素不可见

yaml

- assertNotVisible: "加载中..."  # 屏幕上不能出现"加载中..."

连续检查 7 秒，如果一直没出现就通过；中途出现了则报错。

对象形式

yaml

- assertVisible:
    text: "登录成功"
    id: "success_message"       # 同时匹配文字和 ID

启动和关闭 App launchApp / stopApp

启动 App

yaml

- launchApp                     # 启动配置区中 appId 指定的 App

启动其他 App：

yaml

- launchApp: com.example.other  # 启动指定包名的 App

启动时清除 App 的所有存储数据：

yaml

- launchApp:
    appId: com.example.app
    clearState: true            # 清除 App 所有数据

launchApp 所有参数

yaml

- launchApp:
    appId: com.example.app      # 指定包名（不填则用配置区 appId）
    clearState: true            # 清除 App 所有数据
    stopApp: true               # 先停止已运行的实例（默认 true）
    permissions:                # 启动时授予权限
      android.permission.CAMERA: allow
    arguments:                  # 启动参数
      key: "value"

停止 App

yaml

- stopApp                       # 停止当前 App
- stopApp: com.example.app      # 停止指定 App

强制杀死 App

yaml

- killApp: com.example.app

清除 App 数据

yaml

- clearState                    # 清除当前 App 数据
- clearState: com.example.app   # 清除指定 App 数据

收起键盘 hideKeyboard

yaml

- hideKeyboard

也可以写成 hide keyboard（带空格）：

yaml

- hide keyboard

按键 pressKey

模拟按下物理按键或虚拟按键。

yaml

- pressKey: Home                # 回到桌面
- pressKey: Back                # 返回（等效于 back 命令）
- pressKey: Enter               # 回车/确认
- pressKey: VolumeUp            # 音量加
- pressKey: VolumeDown          # 音量减

也可以直接传 Android keyCode 数字：

yaml

- pressKey: 66                  # 66 = KEYCODE_ENTER

完整按键列表见速查表。

入门实战：登录流程

把前面学到的命令组合起来，完成一个真实的登录操作：

yaml

appId: com.example.app
name: 登录流程
env:
  USERNAME: test_user
  PASSWORD: secret123
---
# 1. 启动 App
- launchApp

# 2. 输入用户名
- tapOn: "用户名"
- inputText: "${USERNAME}"

# 3. 输入密码
- tapOn: "密码"
- inputText: "${PASSWORD}"

# 4. 点击登录按钮（等待界面稳定后再继续）
- tapOn:
    text: "登录"
    waitToSettleTimeoutMs: 3000

# 5. 验证登录成功
- assertVisible: "欢迎"

学会了基础命令？接下来进入 → 进阶篇

入门篇 ​

文件结构 ​

第一个 Flow：打开设置 ​

点击元素 tapOn ​

简写形式：直接写文字 ​

对象形式：更多控制 ​

等待界面稳定 ​

连续点击 ​

输入文字 inputText ​

删除文字 eraseText ​

滑动 swipe ​

方向滑动 ​

控制滑动速度 ​

随机速度 ​

从元素位置滑动 ​

滑动后不等待界面稳定 ​

滚动 scroll ​

返回键 back ​

等待与延时 sleep ​

固定等待 ​

随机等待 ​

对象形式 ​

验证界面 assertVisible / assertNotVisible ​

验证元素可见 ​

验证元素不可见 ​

对象形式 ​

启动和关闭 App launchApp / stopApp ​

启动 App ​

launchApp 所有参数 ​

停止 App ​

强制杀死 App ​

清除 App 数据 ​

收起键盘 hideKeyboard ​

按键 pressKey ​

入门实战：登录流程 ​

入门篇

文件结构

第一个 Flow：打开设置

点击元素 tapOn

简写形式：直接写文字

对象形式：更多控制

等待界面稳定

连续点击

输入文字 inputText

删除文字 eraseText

滑动 swipe

方向滑动

控制滑动速度

随机速度

从元素位置滑动

滑动后不等待界面稳定

滚动 scroll

返回键 back

等待与延时 sleep

固定等待

随机等待

对象形式

验证界面 assertVisible / assertNotVisible

验证元素可见

验证元素不可见

对象形式

启动和关闭 App launchApp / stopApp

启动 App

launchApp 所有参数

停止 App

强制杀死 App

清除 App 数据

收起键盘 hideKeyboard

按键 pressKey

入门实战：登录流程