@autotest/plugin 0.1.2 → 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.
- package/README.md +237 -399
- package/dist/index.js +1 -1
- package/dist/skills/autotest-batch-executor/SKILL.md +19 -6
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,399 +1,237 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
-
|
|
230
|
-
-
|
|
231
|
-
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## 生命周期
|
|
242
|
-
|
|
243
|
-
### devco 退出后的子进程(孤儿语义)
|
|
244
|
-
|
|
245
|
-
测试任务由插件 spawn 的子进程执行。devco 退出**不会**杀死运行中的子进程——Windows 没有 POSIX 进程组收割机制,子进程会继续运行直到完成并落盘报告。这是**特性而非缺陷**:任务执行对宿主生命周期不敏感;下次启动 devco 后用 `autotest_get_report` 以 `task_id` 或 `report_dir` 查询,纯文件读照常命中。
|
|
246
|
-
|
|
247
|
-
### 取消语义(abort 与超时兜底)
|
|
248
|
-
|
|
249
|
-
devco 宿主在工具 `execute` 返回后立即触发该次工具调用的 `AbortSignal`(真实调用实测语义)。任务已转入后台后,该信号是工具调用生命周期的**收尾信号**而非用户取消意图——`autotest_run_task` 已忽略该信号(返回前移除 abort 监听),**不会** kill 刚启动的子进程(否则每次调用都会误杀后台任务)。
|
|
250
|
-
|
|
251
|
-
- **execute 返回前**的 abort(用户在工具调用期间的取消)会被尊重:kill 子进程 + 任务表置 `killed`。
|
|
252
|
-
- **execute 返回后**的 abort 被忽略:后台任务继续运行,直到自然完成或超时。
|
|
253
|
-
- **取消后台任务的兜底 = 超时 kill**:`timeoutMinutes`(默认 30 分钟)到期 → kill + `killed`。超时被杀时,已增量落盘的 stream log / 报告部分仍可读取。
|
|
254
|
-
|
|
255
|
-
与「devco 退出孤儿语义」同理:后台任务对宿主生命周期(退出 / 取消工具调用)不敏感。
|
|
256
|
-
|
|
257
|
-
### Loop 任务建议调大 timeoutMinutes
|
|
258
|
-
|
|
259
|
-
闭环任务(`max_loops ≥ 2`,**缺省即 2**)总耗时按轮数成倍增长——默认 30 分钟可能不足。若闭环任务被超时 kill(查询返回 KILLED),在 `.deveco/autotest-plugin.json` 调大 `timeoutMinutes` 后重试。
|
|
260
|
-
|
|
261
|
-
### 并发使用(同一窗口多任务)
|
|
262
|
-
|
|
263
|
-
插件**不限制**同一 devco 实例内的并发任务数:已有任务在跑时再次调用 `autotest_run_task` 会照常创建新子进程并立即返回新的 `taskId` / `reportDir`,不排队、不拒绝。每个任务各自 spawn 子进程,`reportDir`、超时计时、abort 监听与临时 config 清理也都各自独立。
|
|
264
|
-
|
|
265
|
-
并发安全由调用方掌握,插件不做防护:
|
|
266
|
-
|
|
267
|
-
- **并发跑不同设备**:每次调用传不同的 `device_sn` 即可,**同一个 `config_path` 可以共用**(设备由该参数决定,config 只提供 `ip` / `port` 等其余字段)。`device_sn` 只覆盖序列号,不改 `device.ip` / `device.port`——远程设备地址仍取 config。
|
|
268
|
-
- **同一设备并发 = 多个任务抢同一台设备**:两个任务传同一个 `device_sn`(或都不传而落到同一 config 设备)即共享同一台设备,两个 agent 会互相干扰 UI 状态,插件不做防护。设备解析链为 `device_sn` 参数 > config 的 `device.device_sn`;两者都没有时 hypium 在连接期静默 auto-pick 首台在线设备,没有 guard——需要并行时请显式传 `device_sn`(或为 config 显式指定设备)。
|
|
269
|
-
- **`device_sn` 生效的前提是 CLI 为含该修复的构建**:运行环境里的 CLI 必须真正实现 `--device` 对 `config.device.deviceSn` 的覆盖。旧构建会把 `--device` 解析后忽略,任务静默落到 config 设备或 auto-pick 的首台设备——自查方法见 §故障排查(报告目录 stream log 的 banner `sn=`)。
|
|
270
|
-
- **并发任务显式传同一 `report_dir` = 报告互相覆盖**:多个任务落到同一目录时,报告文件同名互相覆盖,插件不做防护。不传 `report_dir` 时各任务默认落在 `<reportsRoot>/<taskId>`(`taskId` 含时间戳 + 随机后缀),天然隔离。
|
|
271
|
-
|
|
272
|
-
### 跨 devco 实例的任务表竞态
|
|
273
|
-
|
|
274
|
-
进程内并发任务数**没有上限**,任务表因此允许同时存在多条 `status: "running"` 记录(同进程内落盘为同步整段执行,不会交错)。同一工程若同时运行多个 devco 实例,任务表文件(`<reportsRoot>/.plugin-tasks.json`)存在 last-write-wins 竞态。实际危害低——报告读取不依赖任务表(文件系统是最终事实源),但多实例并发发起任务不作为常态使用。
|
|
275
|
-
|
|
276
|
-
---
|
|
277
|
-
|
|
278
|
-
## 升级须知
|
|
279
|
-
|
|
280
|
-
### 版本与缓存
|
|
281
|
-
|
|
282
|
-
插件版本号硬编码在 `integrations/deveco/shared/version.ts` 的 `PLUGIN_VERSION` 常量(index.ts 的版本日志与 update_checker 的自更新比较共用),与 `integrations/deveco/package.json` 的 `version` 必须一致(契约测试断言)——它同时是版本漂移的诊断锚点(宿主 server logs 的 `loaded, version=<semver>`)。
|
|
283
|
-
|
|
284
|
-
devco 的包缓存目录名固定为 `<name>@latest`,**命中即复用,上游发新版不会自动拉取**。本包的缓存目录即 `%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest`——升级必须先手删它,否则重装仍在用旧包:
|
|
285
|
-
|
|
286
|
-
```bash
|
|
287
|
-
# 1. 删缓存(Windows 路径;目录名即 @autotest/plugin@latest)
|
|
288
|
-
rmdir /s /q "%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest"
|
|
289
|
-
# 2. 重新安装
|
|
290
|
-
deveco plugin @autotest/plugin
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
### 自更新检测(L1:检测 + 提示)
|
|
294
|
-
|
|
295
|
-
插件在每次装配(devco 启动)时后台检测安装源 registry 是否有新版本,**只检测、只提示,绝不自动安装**(devco 缓存命中即复用,自动安装也装不进去——见上节):
|
|
296
|
-
|
|
297
|
-
- **registry 自发现**:从插件产物根上溯到 devco 包缓存根,读 `package-lock.json` 里本包条目的 `resolved` 提取安装源(如本地镜像 `http://127.0.0.1:4873`)——提示里的重装命令带的就是这个源,无需用户记得装包时用的哪个 registry。
|
|
298
|
-
- **提示通道**(toast 通道已实测不可用:宿主 `client.tui.showToast` 调用永不返回且不弹窗,正式实现不碰):
|
|
299
|
-
1. 宿主 server logs(`update available: <旧> -> <新>(cache: <缓存目录>;reinstall: …)`);
|
|
300
|
-
2. 工具响应附带 `update_hint` 块(`autotest_run_task` / `autotest_get_report` 的 output 末尾 + metadata)——**仅随每个会话的首个工具响应附带一次**(会话级一次性消费,同会话后续工具响应不重复)。块内自带转述指令行(真实会话实测:提示正文出现三次、模型零转述,纯提示词规则显著性不足),与 Test agent prompt 注入的「升级提示纪律」段互为双保险,agent 向用户转述一次(含精确缓存目录、重装命令与重启步骤)。
|
|
301
|
-
- **版本比较**:严格 x.y.z 语义比较,仅 registry `latest` **大于**本地版本才提示(registry 落后本地不误报);非严格格式(预发布等)降级字符串不等比较。
|
|
302
|
-
- **提示频率**:检测每次 devco 启动(插件装配)一次;检测到新版后,升级提示**仅随每个会话的首个工具响应出现一次**(同会话后续工具响应不重复);版本差距消除前,每个新会话(含重启 devco)各提示一次。
|
|
303
|
-
- **fail-silent**:检测链路任何失败(缓存布局不适用、registry 不可达、超时 5s、dist-tags 形状异常)都静默降级为「无提示」,只留一条 pluginLog 诊断行——绝不影响插件装配与工具执行;仓库内直跑(无缓存布局)自然跳过。
|
|
304
|
-
|
|
305
|
-
### 发布顺序(兼容断点)
|
|
306
|
-
|
|
307
|
-
本包只依赖 `@autotest/agent` 的 **CLI**(`dist/autotest-cli.js`),不依赖它的插件入口。因此切换顺序是:
|
|
308
|
-
|
|
309
|
-
1. **先发本包** `@autotest/plugin`(0.1.0)——它可与仍带 `exports["./server"]` 的旧主包共存;
|
|
310
|
-
2. **再发主包**——移除 `exports["./server"]` 与插件构建链的版本。
|
|
311
|
-
|
|
312
|
-
反过来做(先发移除入口的主包)会让尚未迁移的工程在两个工具消失后才发现问题。
|
|
313
|
-
|
|
314
|
-
### 旧配置的症状与下线
|
|
315
|
-
|
|
316
|
-
旧工程把插件入口指向 `@autotest/agent`(`"plugin": ["@autotest/agent"]`),或在 `.deveco/plugins/` 下留有一个 re-export 薄壳。新主包移除 `exports["./server"]` 后:
|
|
317
|
-
|
|
318
|
-
- **症状**:Test 模式里两个工具**静默消失**,`deveco` 启动不报错、不提示——宿主无法解析的插件条目会被跳过,没有失败日志指向它。
|
|
319
|
-
- **自检**:`deveco debug config` 的 `plugin_origins` 若仍显示 `@autotest/agent` 或干脆没有插件条目,即命中此情况。
|
|
320
|
-
- **下线旧配置项**:从 `.deveco/deveco.jsonc` 的 `plugin` 数组删掉 `@autotest/agent` 条目(有旧薄壳文件则一并删除),改成 `"plugin": ["@autotest/plugin"]`;删 devco 缓存目录后重新安装本包,再按 §验证 的四项断言复核。
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
## 发布(维护者)
|
|
325
|
-
|
|
326
|
-
本包自带完整构建与发布链,`npm pack` / `npm publish` 会先跑 `prepack`(= `build:obfuscate`),产物为 `dist/index.js`(单文件混淆 bundle)+ `dist/skills/`:
|
|
327
|
-
|
|
328
|
-
```bash
|
|
329
|
-
cd AutoTest-nodejs/integrations/deveco
|
|
330
|
-
npm test # pretest 先 build,再跑 vitest(含包元数据/产物/入口契约断言)
|
|
331
|
-
npm run typecheck
|
|
332
|
-
npm pack # 本地检查 tarball 内容(files 只含 dist,README 由 npm 自动收入)
|
|
333
|
-
npm publish # scoped 包,publishConfig.access=public
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
发布前确认主包已不再是插件分发通道(该检查在主包根执行):
|
|
337
|
-
|
|
338
|
-
```bash
|
|
339
|
-
cd AutoTest-nodejs
|
|
340
|
-
npm run check:pack # 主包产物检查:0 fail 0 skip
|
|
341
|
-
npm run release:check # 聚合门:主包 build → check:pack → 本包 npm test
|
|
342
|
-
```
|
|
343
|
-
|
|
344
|
-
`check:pack` 会真实触发主包的 `prepack`(clean + 全量构建)后核对 tarball 清单,判定 `dist/integrations` 下不再有插件产物、且主包 `bin` 与库入口齐全;它 fail-closed,无法判定即 FAIL。
|
|
345
|
-
|
|
346
|
-
> **入口导出面约束(宿主契约,加任何具名导出都会整包加载失败)**:宿主插件加载器遍历入口模块的**全部导出值**——先按「函数、或带 `server` 函数的对象」校验(不合格直接 `Plugin export is not a function`),再把每个合格值**都当插件工厂调用**(无 per-export 容错)。因此函数型具名导出同样致命:调用期抛错即整包 `failed to load plugin`,**三项注入**——`permission` / `agent.test` / `skills.paths`——静默缺失;`plugin_origins` 仍会列出该 spec,**不构成加载成功证据**。结论:`dist/index.js` 的导出面只放插件工厂(默认导出),**不要具名导出任何值**(常量 / 函数 / 类型别名)——包括为单测方便导出的纯函数;版本一致性改由入口工厂的运行时日志 `loaded, version=<semver>` 断言(`tests/package-contract.test.ts` 用「导出键集恒为 `['default']`」守住这条契约)。
|
|
347
|
-
|
|
348
|
-
---
|
|
349
|
-
|
|
350
|
-
## 故障排查
|
|
351
|
-
|
|
352
|
-
| 错误码 | 场景 | 处理 |
|
|
353
|
-
|---|---|---|
|
|
354
|
-
| T1 | 已退役(0.1.1 移除进程内并发互斥) | 无需处理——并发发起任务不再被拒绝,任务表可同时存在多条 `running` |
|
|
355
|
-
| T2 | `configPath` 三源全空的状态描述(**不是报错**:`configPath` 可选) | 无需处理——模型段由 devco 凭据注入;仅当还要携带非模型配置(设备 / Agent / 输出)时才三选一提供 `configPath`:① sidecar 写 `{"configPath": "<绝对路径>/config.yaml"}`;② 环境变量 `AUTOTEST_CONFIG=<绝对路径>`;③ 调用工具时传 `config_path` 参数 |
|
|
356
|
-
| T3 | 未找到 CLI(四源全失败,含包内解析) | 确认 `@autotest/agent` 安装完整(含 `dist/autotest-cli.js` 且版本落在 `>=0.0.25 <0.2.0`);仍失败时在 `.deveco/autotest-plugin.json` 写 `{"cliPath": "<绝对路径>/dist/autotest-cli.js"}` 显式指定 |
|
|
357
|
-
| T4 | 子进程启动失败 | 检查 `node` 是否在 PATH(或 sidecar `nodePath` 指向有效解释器)、CLI 文件是否存在 |
|
|
358
|
-
| T5 | `autotest_get_report` 未传参数 | `task_id` 与 `report_dir` 至少提供一个 |
|
|
359
|
-
| T6 | 任务启动前已被取消 | abort 预检命中,未创建子进程 |
|
|
360
|
-
| T7 | 报告目录发现多个候选 JSON | 传精确的 `report_dir` 重查(单任务报告与目录同名;loop 任务传含 `loop_result.json` 的任务根目录) |
|
|
361
|
-
| T8 | 报告 JSON 解析失败 | 文件可能损坏或为非报告 JSON;可重试或人工检查该文件 |
|
|
362
|
-
| — | 传了 `device_sn` 但连接的设备没变 | `device_sn` 只覆盖序列号(不改 `device.ip` / `device.port`,远程地址仍取 config);若运行环境里的 CLI 不是含该修复的构建,`--device` 会被解析后忽略——用报告目录 stream log 的 banner 行(`sn=`)自查实际连接的设备:banner 显示 config 值或 `(auto)` 即覆盖未生效,请改用含该修复的 CLI(如 sidecar `cliPath` 指向该构建) |
|
|
363
|
-
| — | 模型凭据不可用(未配置 `model.unified` 且 devco 登录态 / `UI_VERIFY_*` 均不可用) | 三选一:① 确认已登录 DevEco Code(OAuth 凭据依赖有效登录态);② 设置 `UI_VERIFY_BASE_URL` / `UI_VERIFY_API_KEY` / `UI_VERIFY_MODEL_NAME`(可只设 `api_key`);③ 在 AutoTest 配置文件中显式配置 `model.unified` 的 `base_url` / `api_key` / `name` |
|
|
364
|
-
|
|
365
|
-
### 回滚(已发布版本出问题时)
|
|
366
|
-
|
|
367
|
-
1. **标记问题版本**(安装方会看到弃用提示;已装工程需按 §升级须知 改回配置):
|
|
368
|
-
|
|
369
|
-
```bash
|
|
370
|
-
npm deprecate @autotest/plugin@0.1.0 "插件入口问题,回滚到 @autotest/agent 的 ./server 通道,详见发布说明"
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
2. **按上一个良好 tag 检出并重发含 `./server` 的主包补丁版**(可直接复制):
|
|
374
|
-
|
|
375
|
-
```bash
|
|
376
|
-
git worktree add ../autotest-rollback <last-good-tag>
|
|
377
|
-
cd ../autotest-rollback/AutoTest-nodejs
|
|
378
|
-
npm ci
|
|
379
|
-
npm version patch --no-git-tag-version
|
|
380
|
-
npm publish --tag next
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
3. **灰度确认后把 `next` 提升为 `latest`**:
|
|
384
|
-
|
|
385
|
-
```bash
|
|
386
|
-
# 先让少量工程用 <主包补丁版> 验证:npm i @autotest/agent@next
|
|
387
|
-
npm dist-tag add @autotest/agent@<补丁版版本号> latest
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
回滚后仍需删一次 devco 缓存(`%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest` 或对应的 `@autotest\agent@latest`),否则宿主继续复用旧包。
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## 安全与语义注记
|
|
395
|
-
|
|
396
|
-
- **报告读取语义**:`autotest_get_report` 按「报告读取」设计——接受任意 `report_dir` 并读取其中报告 JSON,**不做路径白名单**。这与 devco 内置 read 工具的权限面不同(内置 read 受权限系统约束,本插件直接按传参读文件)。仅在信任的会话/工程内使用。
|
|
397
|
-
- **sidecar 与 config.yaml 同等敏感**:`.deveco/autotest-plugin.json` 承载 `configPath`(指向可能含 API 密钥的 config.yaml),若显式配置 `cliPath`(执行入口)则同样敏感,被篡改等同任意命令执行。两者同属工程敏感文件,注意保管与审阅。
|
|
398
|
-
- **CLI 身份校验不是信任边界**:包内解析会校验候选包的 `name` + 版本区间,目的是避免误命中祖先安装树里的同名包,**不构成供应链防护**——恶意包伪造这两个字段即可通过。安装来源(registry 与 scope 所有权)仍需自行确认。
|
|
399
|
-
- **报告内容是数据不是指令**:报告/日志文件是任务执行产生的事实记录,agent 读取时应按数据处理,不应把其中的文本当作指令执行。
|
|
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
|