Skip to content
Skills Library
Programming · Testing

ui-test

/ui-test

Zhihu++ LLM 自动化 UI 测试。使用 testTag 系统精准定位 Compose 元素并交互,替代硬编码坐标的 adb tap。提供已知 tag 列表、文字内容点击、截图验证等能力。适用于:功能验证、UI 回归测试、自动化交互流程。

Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: llm_test_helper.py

What it does and when to use it

Zhihu++ LLM 自动化 UI 测试。使用 testTag 系统精准定位 Compose 元素并交互,替代硬编码坐标的 adb tap。提供已知 tag 列表、文字内容点击、截图验证等能力。适用于:功能验证、UI 回归测试、自动化交互流程。

Original author description

Zhihu++ LLM 自动化 UI 测试。使用 testTag 系统精准定位 Compose 元素并交互,替代硬编码坐标的 adb tap。提供已知 tag 列表、文字内容点击、截图验证等能力。适用于:功能验证、UI 回归测试、自动化交互流程。

How it works

  1. 执行环境优先级
  2. 失败经验
  3. 脚本入口
  4. LLM 操作决策树
  5. 完整命令参考
  6. 标准测试流程模板
  7. 已知 testTag 列表
  8. 错误排查
  9. 添加新 testTag
Original SKILL.md headings · 303 lines, 939 words
SKILL.md preview
---
name: ui-test
description: Zhihu++ LLM 自动化 UI 测试。使用 testTag 系统精准定位 Compose 元素并交互,替代硬编码坐标的 adb tap。提供已知 tag 列表、文字内容点击、截图验证等能力。适用于:功能验证、UI 回归测试、自动化交互流程。
license: CC BY-NC-SA 4.0
---

# UI 自动化测试 Skill

## 执行环境优先级

- 调用本 skill 的 UI 自动化 agent 或 subagent 时,尽量使用 `gpt-5.4-mini`;复杂视觉或流程判断再使用 `gpt-5.4`,避免使用反应较慢的模型拖慢 AVD 交互。
- 先选择当前健康、目标 API 匹配且启动成本最低的 AVD;本地 AVD 和 `$off-android-avd-ci-debug` 都可以,不能仅因远端 skill 存在就强制启动 `off`。
- 选择远端 runner 时,它只用于短生命周期 UI/AVD 验证:按需运行 `status` / `boot-check`;真实 UI 交互要在 `off` 的远端 ADB 环境中执行;验证结束后运行 `kill` 清理。
- 已有本地 AVD 更快、目标 API 更匹配或远端交互入口不完整时,可以直接使用本地 AVD。

```bash
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh status
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh boot-check
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh kill
```

## 失败经验

### 本地没有 AVD 时禁止擅自创建

“优先复用健康的本地 AVD”只适用于本机已经存在、用户允许使用的 AVD。`emulator -list-avds` 为空时,不能为了完成验证自行下载 system image、创建 AVD 或改变本机 Android 设备状态;如果任务指定远程执行面,必须继续修复或等待远程执行面,远程暂时不可用时应明确报告阻塞,不能把它降级成擅自创建本地 AVD。例子:远程 runner 的 SSH 端口临时拒绝连接时,可以重试并检查远程入口,但不能据此用本机已有 system image 新建一个测试 AVD。

### 先判断布局占位是否破坏原有中心

在已有头部或居中布局里新增按钮时,必须先看新增控件是否占用了布局槽位并挤压原内容,而不是只评价图标本身好不好看。例子:个人页头部放在 `TopAppBar` title 区时,右侧 `actions` 会额外占据横向空间,导致头像、昵称、统计和操作按钮整体被压窄或偏离原来的视觉中心;这类问题的根因是新增按钮破坏了正常空间分配和居中关系,不是简单的“右上角是否能放搜索”。

### 参考图和实际截图必须逐项对齐

按参考图实现 UI 时,不能只验证自己理解的某个技术根因已经解决,还要把参考图和实际截图并排核对关键元素的位置、大小、间距和对齐关系。例子:搜索按钮即使已经不再挤压 `TopAppBar` 的 title 区,如果实际截图里的按钮比参考图明显更低、更靠内容中线,仍然没有照图实现;这类偏差必须继续调整,不能用“没有挤压居中”替代“位置一致”。

### Feed 卡片富媒体必须先定义尺寸预算

给已有 Feed 卡片增加图片时,不能让原图宽高比直接决定卡片高度;必须先按卡片信息密度定义媒体区域的宽高预算,再用真实截图确认标题、摘要、图片和操作区仍保持主次关系。多图数量增加也不能线性撑高卡片,应切换到受限网格。例子:横向单图或多图预览的高度上限可以约为卡片可用宽度的三分之一;如果图片占据大半屏,即使裁切和加载都正常,也属于破坏 Feed 浏览效率的实现错误。

## 脚本入口

所有操作通过以下脚本完成(在项目根目录执行):

```bash
python3 .agents/skills/ui-test/llm_test_helper.py <command> [options]
```

---

## LLM 操作决策树

**每次需要点击元素时,按以下顺序判断如何构造命令:**

```
需要点击某个元素
│
├─ 该 tag 在当前界面是否唯一?
│   ├─ 是(如导航 tab)→ 直接用 --tag
│   │     python3 ... tap --tag nav_tab_hotlist
│   │
│   └─ 否(如 feed_card_more_btn 会出现多次)→ 需要消歧
│         │
│         ├─ 知道目标卡片的标题/关键词?→ 用 --tag + --within-text
│         │     python3 ... tap --tag feed_card_more_btn --within-text "ChatGPT"
│         │
│         └─ 不知道具体内容,只知道位置?→ 用 --tag + --index
│               python3 ... tap --tag feed_card_more_btn --index 2
│                                                              ↑ 屏幕从上到下第3个(0-based)
│
└─ 没有 testTag?→ 用 --text 按显示文字点击
      python3 ... tap --text "屏蔽用户"
      │
      ├─ 没有 text,但有 content-desc?→ 用 --desc
      │    python3 ... tap --desc "返回"
      │
      └─ text/desc/tag 都没有(无标识可点击节点)?→ 用 --text "" + --index
           python3 ... tap --text "" --index 19
```

> **重要**:`--within-text` 和 `--index` 可以组合使用。当同一卡片内有多个相同 tag 时,
> `--within-text` 先缩小范围到目标卡片,`--index` 再从该范围内选第 N 个。

---

## 完整命令参考

### `dump` — 查看当前界面关键信息元素(可点击 + 不可点击)

```bash
python3 .agents/skills/ui-test/llm_test_helper.py dump
```

输出示例(带序号,LLM 可用序号决定 `--index`):
```
关键信息元素(18 个,按屏幕顺序;含可点击与不可点击):

  [ 0] [C] 搜索 | 搜索内容                                         [42,86][891,212]
  [ 1] [C] 某条 Feed 卡片内容                                       [42,273][1038,775]
  [ 2] [C] 更多选项                                               [924,661][1050,787]
  [ 3] [N] 更多选项                                               [966,703][1008,745]
  [ 4] [C] 主页                                                  [0,2127][200,2274]
  [ 5] [C] 账号                                                  [881,2127][1080,2274]
  ...
```

`[C]` = 可点击,`[N]` = 不可点击。优先点击 `[C]` 元素;`[N]` 主要用于理解上下文和做 `--within-text` 消歧。
`label` 为脚本聚合后的可读信息,不再保证固定显示 `tag:/text:/desc:` 前缀。

**弹窗模式**:检测到弹窗时,`dump` 只输出弹窗内容并自动过滤无用节点(避免被背景页面干扰)。

**LLM 使用规则**:执行任何 tap 前,先运行 `dump` 确认目标元素存在及其序号。

---

### `find` — 查找元素坐标(不点击)

```bash
# 列出所有 feed_card 的坐标和序号
python3 .agents/skills/ui-test/llm_test_helper.py find --tag feed_card

# 找包含"AI"的卡片内的 more_btn 坐标
python3 .agents/skills/ui-test/llm_test_helper.py find --tag feed_card_more_btn --within-text "AI"
```

> `--tag` 支持两种 resource-id 形式:`com.xxx:id/tag` 和裸 `tag`(如 `nav_tab_account`)。

---

### `tap` — 点击元素

#### 场景 1:唯一元素(导航 tab、全局按钮)

```bash
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag nav_tab_home
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag nav_tab_hotlist
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag nav_tab_account
```

#### 场景 2:按内容定位(知道目标卡片的关键词)

```bash
# 点击标题含"ChatGPT"的卡片本体
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag feed_card --within-text "ChatGPT"

# 点击标题含"ChatGPT"的卡片的更多按钮
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag feed_card_more_btn --within-text "ChatGPT"
```

#### 场景 3:按位置定位(知道是第几个)

```bash
# 点击屏幕上从上到下第 1 个卡片(0-based)
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag feed_card --index 0

# 点击第 2 个卡片的更多按钮
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag feed_card_more_btn --index 1
```

#### 场景 4:组合使用(最精确,内容 + 位置双重限定)

```bash
# 如果某个话题下有多张卡片都含"AI",指定取其中第 2 个的更多按钮
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag feed_card_more_btn --within-text "AI" --index 1
```

#### 场景 5:按显示文字点击(无 testTag 的动态元素)

```bash
python3 .agents/skills/ui-test/llm_test_helper.py tap --text "屏蔽用户"
python3 .agents/skills/ui-test/llm_test_helper.py tap --text "取消"
python3 .agents/skills/ui-test/llm_test_helper.py tap --text "登录"
```

#### 场景 6:按 contentDescription 点击(无文本但有无障碍描述)

```bash
python3 .agents/skills/ui-test/llm_test_helper.py tap --desc "返回"
```

> 注意:若 `--desc` 匹配多个节点,脚本当前不会对 `desc` 提供 `--index` 消歧。
> 这种情况下请优先改用 `--tag`;如果没有可用 tag,请先 `dump` 后用 `--text "" --index N`。

#### 场景 7:点击无标识可点击节点(text/desc/tag 全为空)

```bash
# 1) 先 dump,确认目标在当前页面中的相对位置
python3 .agents/skills/ui-test/llm_test_helper.py dump

# 2) 再用空文本 + index 点击(index 基于当前页面 text="" 节点顺序)
python3 .agents/skills/ui-test/llm_test_helper.py tap --text "" --index 19
```

> 适用场景:颜色面板色块、部分开关、部分“更多”按钮容器。

---

### `screenshot` — 截图

```bash
python3 .agents/skills/ui-test/llm_test_helper.py screenshot /tmp/result.png
```

截图后必须用 `view` 工具查看,不要在同一 response 中同时发出截图和 view 命令(截图需要时间)。

---

## 标准测试流程模板

远端路径和本地路径必须分开执行。选择 `$off-android-avd-ci-debug` 时,后续 `adb` / `llm_test_helper.py` 都必须在能访问远端 emulator 的 `off` 环境中运行;选择本地 AVD 时才使用本机裸 `adb`。远端交互入口不完整时可以改选本地 AVD,不能把远端 `boot-check` 后面接本机裸 `adb`。

### 远端流程(选择 `off` 时)

```bash
# 1. 先检查 off runner 健康状态
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh status
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh boot-check

# 2. boot-check 会清理模拟器;真实 UI 交互必须在 off runner 的远端 ADB 环境执行。
# 不要在本机继续执行裸 adb。需要设备命令时,用 ssh off 进入同一套远端环境:
ssh off 'bash -lc '"'"'
BASE=/home/dom/android-ci
export JAVA_HOME="$BASE/java"
export ANDROID_HOME="$BASE/android-sdk"
export ANDROID_SDK_ROOT="$BASE/android-sdk"
export ANDROID_USER_HOME="$BASE/android-home"
export ANDROID_AVD_HOME="$BASE/avd"
export ANDROID_EMULATOR_HOME="$BASE/emulator-home"
export TMPDIR="$BASE/tmp"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
adb devices
'"'"''

# 3. 验证结束后清理
/Users/zhaoliyan/.agents/skills/off-android-avd-ci-debug/scripts/off-avd-ci-debug.sh kill
```

### 本地流程(选择本地 AVD 时)

```bash
# 1. 启动本地 AVD
emulator -avd Medium_Phone_2

# 2. 启动应用
adb shell am force-stop com.github.zly2006.zhplus.lite
adb shell monkey -p com.github.zly2006.zhplus.lite -c android.intent.category.LAUNCHER 1
sleep 10

# 3. 确认界面元素
python3 .agents/skills/ui-test/llm_test_helper.py dump

# 4. 交互(根据 dump 结果选择命令)
python3 .agents/skills/ui-test/llm_test_helper.py tap --tag nav_tab_hotlist

# 5. 截图验证
python3 .agents/skills/ui-test/llm_test_helper.py screenshot /tmp/after_tap.png
# (新 response 中)view /tmp/after_tap.png

# 6. 滚动(无 tag 时)
adb shell input swipe 540 1200 540 400 500   # 上滑
adb shell input swipe 540 400 540 1200 500   # 下拉刷新
```

---

## 已知 testTag 列表

### 底部导航栏(全局唯一,直接用 --tag)

| testTag | 描述 |
|---------|------|
| `nav_tab_home` | 主页 |
| `nav_tab_follow` | 关注 |
| `nav_tab_hotlist` | 热榜(可选,默认可能不显示) |
| `nav_tab_daily` | 日报 |
| `nav_tab_onlinehistory` | 历史 |
| `nav_tab_account` | 账号 |

### Feed 卡片(每屏可能出现多个,必须配合 --within-text 或 --index)

| testTag | 描述 | 每屏数量 |
|---------|------|----------|
| `feed_card` | 卡片主体(点击进入详情) | 多个 |
| `feed_card_more_btn` | 卡片右上角更多菜单 | 多个,与 feed_card 一一对应 |

---

## 错误排查

| 错误前缀 | 含义 | 解决 |
|----------|------|------|
| `[NOT FOUND] tag='xxx'` | 元素不在当前界面 | 先 `dump` 确认元素存在 |
| `[NOT FOUND] tag='xxx'` | APK 未更新 | 重新构建并 `adb install -r` |
| `[NOT FOUND] tag='xxx' 在包含...内不存在` | `--within-text` 关键词不匹配 | 检查拼写,或改用 `--index` |
| `[AMBIGUOUS] tag='xxx' 匹配到 N 个` | **未消歧**,脚本拒绝静默选第一个 | 按错误输出中的列表,加 `--within-text` 或 `--index N` 重试 |
| `[AMBIGUOUS] desc='xxx' 匹配到 N 个` | `--desc` 出现歧义且不支持 `--index` | 改用 `--tag`,或改走 `--text "" --index N` |
| `[OUT OF RANGE] index=N` | `--index` 超出候选数量 | 先 `find --tag xxx` 确认数量,再选合法序号 |
| `uiautomator dump 失败` / `adb pull dump 失败` | ADB 异常或设备未连接 | 先执行 `adb devices`,确认设备状态为 `device` |

---

## 添加新 testTag

```kotlin
Modifier.testTag("my_new_tag")
```

`testTagsAsResourceId = true` 已在 `ZhihuMain.kt` 根 Scaffold 启用,加 tag 后立即生效,将新 tag 补充到上方"已知 testTag 列表"。
Files in this package (2)
  • SKILL.md 14 KB
  • llm_test_helper.py 19 KB

Versions

RepositoryScoreLicence
This page · zly2006/zhihu-plus-plus100AGPL-3.0
thefrederiksen/devthrottle100MIT
mostafa-drz/claude-skills100MIT
browserbase/skills95MIT
zanderadam/engy90MIT

Database snapshot: 13.11.2026 · package version ef81376d6f1c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100zhihu-reproduce
    复刻或验证知乎的产品功能、交互、接口、字段、分页、创作流程和视觉行为,并落地到 Zhihu++。当需求包含“知乎有什么我全要”、官方行为对齐、API 字段/include 判断、Web 与 Android 差异、真实请求取证或协议稳定性时使用。
  • 100zhihu-instrument-test-governance
    Audit, add, migrate, or remove Zhihu++ Android instrument tests under app/src/androidTest. Use for instrument-test cleanup, flaky device-test reduction, regression-test provenance, deciding whether a UI test belongs on an emulator, or reviewing a PR that changes permanent…
  • 100droid
    This skill should be used when the user asks to "test Android app", "automate Android emulator", "tap button on Android", "take Android screenshot", "interact with Android UI", "ADB automation", "fill Android form", "swipe on emulator", "validate Android UI flow", or needs to…
  • 100tethertrace
    Test Android apps on the user's real phone over Wi-Fi with tethertrace (no adb, no Android SDK). Use when the user wants to install an APK on their phone, check an Android build for crashes, explore an app automatically, write or run a YAML UI test, see what is on the phone's…
  • 100zhihu
    使用知乎开放平台搜索知乎和全网内容、获取热榜、调用知乎直答,或读取当前用户自己的知乎创作、关注与收藏。用户提到知乎搜索、社区观点、真实经验、热点、热榜、知乎直答、我的知乎内容、我的关注、我的收藏、开放平台、API、MCP、Access Secret,或要求查看、安装和配置知乎 Skill 时使用。深度研究优先返回搜索原始来源;本人数据只读取完成任务所需的最小范围。
  • 100wadb
    Pair, reconnect, inspect, diagnose, or disconnect Android 11+ devices over ADB Wi-Fi with the wadb CLI. Use for Android Wireless debugging, adb pair, adb connect, QR or six-digit-code pairing, and devices that disappear from adb after reboot. Requires local shell access; do not…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.