@autotest/plugin 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +237 -237
  2. package/dist/index.js +1 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,237 +1,237 @@
1
- # DevecoCode Test模式
2
-
3
- DevEco Code(devco)Test 模式插件。通过自然语言描述测试用例,在已连接的 HarmonyOS 设备上执行 UI 自动化测试,生成可回看的测试报告,并在用例失败时进行根因分析与受限自愈。
4
-
5
- | 项 | 值 |
6
- |---|---|
7
- | 包名 | `@autotest/plugin` |
8
- | 运行环境 | Node.js ≥ 18 |
9
-
10
- ## 目录
11
-
12
- - [1. 功能范围](#1-功能范围)
13
- - [2. 环境要求](#2-环境要求)
14
- - [3. 安装](#3-安装)
15
- - [4. 快速开始](#4-快速开始)
16
- - [5. 执行流程与输出](#5-执行流程与输出)
17
- - [6. Loop 闭环](#6-loop-闭环)
18
- - [7. 报告](#7-报告)
19
- - [8. 配置](#8-配置)
20
- - [9. 故障排查](#9-故障排查)
21
-
22
- ---
23
-
24
- ## 1. 功能范围
25
-
26
- **支持**
27
-
28
- - 单条用例:自然语言描述操作步骤与预期结果,自动完成点击、输入、滑动、返回等操作并验证结果
29
- - 批量执行:一次提供多条用例,按顺序串行执行并汇总结果
30
- - 需求生成用例:提供需求描述,先设计可执行的 UI 用例,再逐条执行
31
- - 报告输出:JSON / HTML / Markdown,包含步骤、截图、耗时与 Token 用量
32
-
33
- **不支持**
34
-
35
- - 纯后端逻辑、接口层校验
36
- - 性能压测、网络抓包
37
- - 无界面的功能验证
38
-
39
- ---
40
-
41
- ## 2. 环境要求
42
-
43
- | 项 | 要求 |
44
- |---|---|
45
- | DevEco Code | 已安装并可正常启动 |
46
- | Node.js | ≥ 18 |
47
- | 设备 | 已通过 HDC 连接、已解锁的 HarmonyOS 设备 |
48
- | 模型 | 支持图片输入的多模态模型 |
49
-
50
- 检查设备连接:
51
-
52
- ```bash
53
- hdc list targets
54
- ```
55
-
56
- ---
57
-
58
- ## 3. 安装
59
-
60
- 在工程根目录执行:
61
-
62
- ```bash
63
- # 安装最新版本
64
- deveco plugin @autotest/plugin
65
- ```
66
-
67
- 插件安装在 devco 自己的包缓存中。
68
-
69
- ---
70
-
71
- ## 4. 快速开始
72
-
73
- 1. 在 devco 的 agent 列表中选择 **Test** 模式。
74
- 2. 直接输入用例描述:
75
-
76
- ```text
77
- 打开设置,进入“WLAN”页面,验证可用网络列表正常显示
78
- ```
79
-
80
- 插件将依次执行:设备检查 → 启动任务 → 按约 30 秒间隔查询进度 → 输出终态结果与报告路径。
81
-
82
- ---
83
-
84
- ## 5. 执行流程与输出
85
-
86
- 插件按「设备检查 → 启动任务 → 轮询进度 → 输出结果」执行,轮询间隔约 30 秒。
87
-
88
- 执行过程中会转述当前操作步骤(每轮只列本轮新增行):
89
-
90
- ```text
91
- 第 1 条用例执行中(RUNNING,已完成 4 步)
92
- 3. 打开设置应用
93
- 4. 点击“WLAN”入口
94
- ```
95
-
96
- 到达终态后输出执行结果、结论摘要与 JSON / HTML / Markdown 报告路径。
97
-
98
- ---
99
-
100
- ## 6. Loop 闭环
101
-
102
- Loop 在用例失败后执行「归因 → 改写 → 重执行」,默认最多 2 轮。
103
-
104
- | `max_loops` | 行为 |
105
- |---|---|
106
- | `0` | 只执行一次,不做归因与改写 |
107
- | `1` | 只执行一次 |
108
- | `2`(默认) | 最多两轮闭环 |
109
- | `3` | 最多三轮闭环 |
110
-
111
- 开启 Loop 后,每轮报告隔离在 `iter_N/` 目录,根目录生成 `loop_result.json` 与 `loop_summary.html`。
112
-
113
- ---
114
-
115
- ## 7. 报告
116
-
117
- 默认报告根目录:
118
-
119
- ```text
120
- <工程目录>/autotest-reports/
121
- ```
122
-
123
- 单次任务:
124
-
125
- ```text
126
- autotest-reports/
127
- └── <task_name>/
128
- ├── *.json
129
- ├── *.html
130
- ├── *.md
131
- ├── agent_*.log
132
- └── screenPath/
133
- ```
134
-
135
- Loop 任务:
136
-
137
- ```text
138
- autotest-reports/
139
- └── <task_name>/
140
- ├── loop_result.json
141
- ├── loop_summary.html
142
- ├── plugin_stream.log
143
- └── iter_1/
144
- ├── *.json / *.html / *.md
145
- ├── log/
146
- └── screenPath/
147
- ```
148
-
149
- 报告内容包含:每步操作与截图、模型判定、耗时与 Token 用量。`plugin_stream.log` 为插件转述数据源,排查执行问题时优先查看。
150
-
151
- ---
152
-
153
- ## 8. 配置
154
-
155
- ### 8.1 AutoTest 配置
156
-
157
- 未提供时插件可使用内置配置运行,模型由 devco 登录态提供。建议自行配置模型与设备,保证环境稳定性。
158
-
159
- 配置文件按以下顺序查找,命中即用:
160
-
161
- 1. 显式指定的配置文件
162
- 2. `<工程>/.deveco/autotest/config.local.yaml`(工程本地覆盖)
163
- 3. `<工程>/.deveco/autotest/config.yaml`(工程基础配置)
164
- 4. `~/.deveco/autotest/config.yaml`(全局默认)
165
-
166
- 最小配置示例:
167
-
168
- ```yaml
169
- model:
170
- unified:
171
- name: "your-vision-model"
172
- base_url: "https://your-gateway/v1"
173
- api_key: "..."
174
-
175
- device:
176
- device_sn: "YOUR_DEVICE_SN" # 通过 hdc list targets 获取
177
- ```
178
-
179
- 说明:
180
-
181
- - 模型必须支持图片输入;纯文本模型在首次截图后会失败
182
- - 用户配置了有效模型时优先使用用户配置;未配置时插件从 devco 登录态注入模型三键
183
- - 任务参数 `device_sn` 仅覆盖设备序列号,不修改 `device.ip` / `device.port`
184
- - 不传 `device_sn` 时,跟随配置文件的 `device.device_sn`;配置为空时可能自动选择首个在线设备,多设备场景建议显式指定
185
-
186
- ---
187
-
188
- ## 9. 故障排查
189
-
190
- ### Test 模式无法执行用例
191
-
192
- - 确认当前为 **Test** 模式
193
- - 确认插件已在 devco 中启用
194
- - 确认插件安装后已重启 devco
195
-
196
- ### 找不到设备
197
-
198
- ```bash
199
- hdc list targets
200
- ```
201
-
202
- 确认设备在线且已解锁;多设备时显式传入 `device_sn`。
203
-
204
- ### 无法启动应用
205
-
206
- 应用无法按显示名启动(未找到、名称重复或启动了错误应用)时,请在用例中显式给出应用包名:
207
-
208
- ```text
209
- 打开应用(包名 com.example.app),进入“WLAN”页面,验证可用网络列表正常显示
210
- ```
211
-
212
- `com.example.app` 替换为实际包名,可通过 `hdc shell bm dump -a` 查看。
213
-
214
- ### 任务长时间处于 RUNNING
215
-
216
- - 继续轮询任务状态
217
- - 查看任务目录下 `plugin_stream.log`,确认是否存在设备断连、模型超时或重试记录
218
-
219
- ### 模型调用失败
220
-
221
- 属于模型服务侧问题,可尝试:
222
-
223
- - 稍后重试
224
- - 更换稳定的多模态模型
225
- - 在 AutoTest 配置 `model.unified` 中显式指定可用模型
226
-
227
- ### 找不到报告
228
-
229
- - 使用任务启动时返回的 `taskId` 或 `reportDir` 查询
230
- - 确认报告目录未被手动删除
231
- - Loop 任务请传任务根目录,不要只传某一轮的 `iter_N`
232
-
233
- ---
234
-
235
- ## License
236
-
237
- MIT
1
+ # DevecoCode Test模式
2
+
3
+ DevEco Code(devco)Test 模式插件。通过自然语言描述测试用例,在已连接的 HarmonyOS 设备上执行 UI 自动化测试,生成可回看的测试报告,并在用例失败时进行根因分析与受限自愈。
4
+
5
+ | 项 | 值 |
6
+ |---|---|
7
+ | 包名 | `@autotest/plugin` |
8
+ | 运行环境 | Node.js ≥ 18 |
9
+
10
+ ## 目录
11
+
12
+ - [1. 功能范围](#1-功能范围)
13
+ - [2. 环境要求](#2-环境要求)
14
+ - [3. 安装](#3-安装)
15
+ - [4. 快速开始](#4-快速开始)
16
+ - [5. 执行流程与输出](#5-执行流程与输出)
17
+ - [6. Loop 闭环](#6-loop-闭环)
18
+ - [7. 报告](#7-报告)
19
+ - [8. 配置](#8-配置)
20
+ - [9. 故障排查](#9-故障排查)
21
+
22
+ ---
23
+
24
+ ## 1. 功能范围
25
+
26
+ **支持**
27
+
28
+ - 单条用例:自然语言描述操作步骤与预期结果,自动完成点击、输入、滑动、返回等操作并验证结果
29
+ - 批量执行:一次提供多条用例,按顺序串行执行并汇总结果
30
+ - 需求生成用例:提供需求描述,先设计可执行的 UI 用例,再逐条执行
31
+ - 报告输出:JSON / HTML / Markdown,包含步骤、截图、耗时与 Token 用量
32
+
33
+ **不支持**
34
+
35
+ - 纯后端逻辑、接口层校验
36
+ - 性能压测、网络抓包
37
+ - 无界面的功能验证
38
+
39
+ ---
40
+
41
+ ## 2. 环境要求
42
+
43
+ | 项 | 要求 |
44
+ |---|---|
45
+ | DevEco Code | 已安装并可正常启动 |
46
+ | Node.js | ≥ 18 |
47
+ | 设备 | 已通过 HDC 连接、已解锁的 HarmonyOS 设备 |
48
+ | 模型 | 支持图片输入的多模态模型 |
49
+
50
+ 检查设备连接:
51
+
52
+ ```bash
53
+ hdc list targets
54
+ ```
55
+
56
+ ---
57
+
58
+ ## 3. 安装
59
+
60
+ 在工程根目录执行:
61
+
62
+ ```bash
63
+ # 安装最新版本
64
+ deveco plugin @autotest/plugin
65
+ ```
66
+
67
+ 插件安装在 devco 自己的包缓存中。
68
+
69
+ ---
70
+
71
+ ## 4. 快速开始
72
+
73
+ 1. 在 devco 的 agent 列表中选择 **Test** 模式。
74
+ 2. 直接输入用例描述:
75
+
76
+ ```text
77
+ 打开设置,进入“WLAN”页面,验证可用网络列表正常显示
78
+ ```
79
+
80
+ 插件将依次执行:设备检查 → 启动任务 → 按约 30 秒间隔查询进度 → 输出终态结果与报告路径。
81
+
82
+ ---
83
+
84
+ ## 5. 执行流程与输出
85
+
86
+ 插件按「设备检查 → 启动任务 → 轮询进度 → 输出结果」执行,轮询间隔约 30 秒。
87
+
88
+ 执行过程中会转述当前操作步骤(每轮只列本轮新增行):
89
+
90
+ ```text
91
+ 第 1 条用例执行中(RUNNING,已完成 4 步)
92
+ 3. 打开设置应用
93
+ 4. 点击“WLAN”入口
94
+ ```
95
+
96
+ 到达终态后输出执行结果、结论摘要与 JSON / HTML / Markdown 报告路径。
97
+
98
+ ---
99
+
100
+ ## 6. Loop 闭环
101
+
102
+ Loop 在用例失败后执行「归因 → 改写 → 重执行」,默认最多 2 轮。
103
+
104
+ | `max_loops` | 行为 |
105
+ |---|---|
106
+ | `0` | 只执行一次,不做归因与改写 |
107
+ | `1` | 只执行一次 |
108
+ | `2`(默认) | 最多两轮闭环 |
109
+ | `3` | 最多三轮闭环 |
110
+
111
+ 开启 Loop 后,每轮报告隔离在 `iter_N/` 目录,根目录生成 `loop_result.json` 与 `loop_summary.html`。
112
+
113
+ ---
114
+
115
+ ## 7. 报告
116
+
117
+ 默认报告根目录:
118
+
119
+ ```text
120
+ <工程目录>/autotest-reports/
121
+ ```
122
+
123
+ 单次任务:
124
+
125
+ ```text
126
+ autotest-reports/
127
+ └── <task_name>/
128
+ ├── *.json
129
+ ├── *.html
130
+ ├── *.md
131
+ ├── agent_*.log
132
+ └── screenPath/
133
+ ```
134
+
135
+ Loop 任务:
136
+
137
+ ```text
138
+ autotest-reports/
139
+ └── <task_name>/
140
+ ├── loop_result.json
141
+ ├── loop_summary.html
142
+ ├── plugin_stream.log
143
+ └── iter_1/
144
+ ├── *.json / *.html / *.md
145
+ ├── log/
146
+ └── screenPath/
147
+ ```
148
+
149
+ 报告内容包含:每步操作与截图、模型判定、耗时与 Token 用量。`plugin_stream.log` 为插件转述数据源,排查执行问题时优先查看。
150
+
151
+ ---
152
+
153
+ ## 8. 配置
154
+
155
+ ### 8.1 AutoTest 配置
156
+
157
+ 未提供时插件可使用内置配置运行,模型由 devco 登录态提供。建议自行配置模型与设备,保证环境稳定性。
158
+
159
+ 配置文件按以下顺序查找,命中即用:
160
+
161
+ 1. 显式指定的配置文件
162
+ 2. `<工程>/.deveco/autotest/config.local.yaml`(工程本地覆盖)
163
+ 3. `<工程>/.deveco/autotest/config.yaml`(工程基础配置)
164
+ 4. `~/.deveco/autotest/config.yaml`(全局默认)
165
+
166
+ 最小配置示例:
167
+
168
+ ```yaml
169
+ model:
170
+ unified:
171
+ name: "your-vision-model"
172
+ base_url: "https://your-gateway/v1"
173
+ api_key: "..."
174
+
175
+ device:
176
+ device_sn: "YOUR_DEVICE_SN" # 通过 hdc list targets 获取
177
+ ```
178
+
179
+ 说明:
180
+
181
+ - 模型必须支持图片输入;纯文本模型在首次截图后会失败
182
+ - 用户配置了有效模型时优先使用用户配置;未配置时插件从 devco 登录态注入模型三键
183
+ - 任务参数 `device_sn` 仅覆盖设备序列号,不修改 `device.ip` / `device.port`
184
+ - 不传 `device_sn` 时,跟随配置文件的 `device.device_sn`;配置为空时可能自动选择首个在线设备,多设备场景建议显式指定
185
+
186
+ ---
187
+
188
+ ## 9. 故障排查
189
+
190
+ ### Test 模式无法执行用例
191
+
192
+ - 确认当前为 **Test** 模式
193
+ - 确认插件已在 devco 中启用
194
+ - 确认插件安装后已重启 devco
195
+
196
+ ### 找不到设备
197
+
198
+ ```bash
199
+ hdc list targets
200
+ ```
201
+
202
+ 确认设备在线且已解锁;多设备时显式传入 `device_sn`。
203
+
204
+ ### 无法启动应用
205
+
206
+ 应用无法按显示名启动(未找到、名称重复或启动了错误应用)时,请在用例中显式给出应用包名:
207
+
208
+ ```text
209
+ 打开应用(包名 com.example.app),进入“WLAN”页面,验证可用网络列表正常显示
210
+ ```
211
+
212
+ `com.example.app` 替换为实际包名,可通过 `hdc shell bm dump -a` 查看。
213
+
214
+ ### 任务长时间处于 RUNNING
215
+
216
+ - 继续轮询任务状态
217
+ - 查看任务目录下 `plugin_stream.log`,确认是否存在设备断连、模型超时或重试记录
218
+
219
+ ### 模型调用失败
220
+
221
+ 属于模型服务侧问题,可尝试:
222
+
223
+ - 稍后重试
224
+ - 更换稳定的多模态模型
225
+ - 在 AutoTest 配置 `model.unified` 中显式指定可用模型
226
+
227
+ ### 找不到报告
228
+
229
+ - 使用任务启动时返回的 `taskId` 或 `reportDir` 查询
230
+ - 确认报告目录未被手动删除
231
+ - Loop 任务请传任务根目录,不要只传某一轮的 `iter_N`
232
+
233
+ ---
234
+
235
+ ## License
236
+
237
+ MIT