@autotest/plugin 0.1.0 → 0.1.3
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 +142 -284
- package/dist/index.js +1 -1
- package/dist/skills/autotest-batch-executor/SKILL.md +33 -17
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,379 +1,237 @@
|
|
|
1
|
-
#
|
|
1
|
+
# DevecoCode Test模式
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
DevEco Code(devco)Test 模式插件。通过自然语言描述测试用例,在已连接的 HarmonyOS 设备上执行 UI 自动化测试,生成可回看的测试报告,并在用例失败时进行根因分析与受限自愈。
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
两个工具**只在 Test 模式可用**(插件自动注入,见 §Test 模式),其他模式(build/plan 等)默认不可见:
|
|
8
|
-
|
|
9
|
-
| 工具 | 作用 |
|
|
5
|
+
| 项 | 值 |
|
|
10
6
|
|---|---|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
14
|
-
任务由插件 spawn 的 `node` 子进程调用 `@autotest/agent` 的 CLI 执行(`dist/autotest-cli.js`),插件自身不直连设备或模型。交互模型为「异步启动 + 轮询查询」,分钟级长任务不阻塞 devco 会话。
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## 安装
|
|
19
|
-
|
|
20
|
-
### 前提
|
|
21
|
-
|
|
22
|
-
- DevEco Code(devco)≥ 0.1.2
|
|
23
|
-
- Node.js ≥ 18
|
|
24
|
-
- `@autotest/agent` 由本包 `dependencies` 自动安装(版本区间 `>=0.0.25 <0.2.0`),**无需单独安装 CLI**
|
|
25
|
-
|
|
26
|
-
### 安装本包(唯一推荐通道:装进 devco 包缓存)
|
|
27
|
-
|
|
28
|
-
devco 对**包名** spec 的解析只看它自己的包缓存(`%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest`),**不读工程的 `node_modules`**。因此唯一可靠的安装动作是交给 devco 自己装——它会连同本包 `dependencies` 声明的 `@autotest/agent` 一起装进该缓存,并把包名写入工程配置:
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
deveco plugin @autotest/plugin
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
本地镜像 / 内网场景**必须用环境变量**指定 registry(工程 `.npmrc` 的 `registry=` 会被 devco 忽略):
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 deveco plugin @autotest/plugin
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
确认工程 `.deveco/deveco.jsonc` 的 `plugin` 数组已写入包名(`deveco plugin` 通常已自动写入,手写等价):
|
|
7
|
+
| 包名 | `@autotest/plugin` |
|
|
8
|
+
| 运行环境 | Node.js ≥ 18 |
|
|
41
9
|
|
|
42
|
-
|
|
43
|
-
{
|
|
44
|
-
"plugin": ["@autotest/plugin"]
|
|
45
|
-
}
|
|
46
|
-
```
|
|
10
|
+
## 目录
|
|
47
11
|
|
|
48
|
-
|
|
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-故障排查)
|
|
49
21
|
|
|
50
|
-
|
|
22
|
+
---
|
|
51
23
|
|
|
52
|
-
|
|
24
|
+
## 1. 功能范围
|
|
53
25
|
|
|
54
|
-
|
|
26
|
+
**支持**
|
|
55
27
|
|
|
56
|
-
|
|
28
|
+
- 单条用例:自然语言描述操作步骤与预期结果,自动完成点击、输入、滑动、返回等操作并验证结果
|
|
29
|
+
- 批量执行:一次提供多条用例,按顺序串行执行并汇总结果
|
|
30
|
+
- 需求生成用例:提供需求描述,先设计可执行的 UI 用例,再逐条执行
|
|
31
|
+
- 报告输出:JSON / HTML / Markdown,包含步骤、截图、耗时与 Token 用量
|
|
57
32
|
|
|
58
|
-
|
|
33
|
+
**不支持**
|
|
59
34
|
|
|
60
|
-
|
|
35
|
+
- 纯后端逻辑、接口层校验
|
|
36
|
+
- 性能压测、网络抓包
|
|
37
|
+
- 无界面的功能验证
|
|
61
38
|
|
|
62
|
-
|
|
39
|
+
---
|
|
63
40
|
|
|
64
|
-
|
|
41
|
+
## 2. 环境要求
|
|
65
42
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
43
|
+
| 项 | 要求 |
|
|
44
|
+
|---|---|
|
|
45
|
+
| DevEco Code | 已安装并可正常启动 |
|
|
46
|
+
| Node.js | ≥ 18 |
|
|
47
|
+
| 设备 | 已通过 HDC 连接、已解锁的 HarmonyOS 设备 |
|
|
48
|
+
| 模型 | 支持图片输入的多模态模型 |
|
|
71
49
|
|
|
72
|
-
|
|
50
|
+
检查设备连接:
|
|
73
51
|
|
|
74
52
|
```bash
|
|
75
|
-
|
|
76
|
-
NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 deveco plugin @autotest/plugin
|
|
53
|
+
hdc list targets
|
|
77
54
|
```
|
|
78
55
|
|
|
79
|
-
|
|
56
|
+
---
|
|
80
57
|
|
|
81
|
-
|
|
58
|
+
## 3. 安装
|
|
82
59
|
|
|
83
|
-
|
|
84
|
-
// .deveco/autotest-plugin.json
|
|
85
|
-
{ "cliPath": "<仓库绝对路径>/AutoTest-nodejs/dist/autotest-cli.js" }
|
|
86
|
-
```
|
|
60
|
+
在工程根目录执行:
|
|
87
61
|
|
|
88
62
|
```bash
|
|
89
|
-
#
|
|
90
|
-
|
|
63
|
+
# 安装最新版本
|
|
64
|
+
deveco plugin @autotest/plugin
|
|
91
65
|
```
|
|
92
66
|
|
|
93
|
-
|
|
67
|
+
插件安装在 devco 自己的包缓存中。
|
|
94
68
|
|
|
95
|
-
|
|
69
|
+
---
|
|
96
70
|
|
|
97
|
-
|
|
98
|
-
cd AutoTest-nodejs
|
|
99
|
-
node scripts-dev/local-registry/local-registry.mjs start
|
|
100
|
-
node scripts-dev/local-registry/local-registry.mjs publish # 1. @autotest/agent(本包的依赖)
|
|
101
|
-
node scripts-dev/local-registry/local-registry.mjs publish --pkg integrations/deveco # 2. @autotest/plugin
|
|
102
|
-
```
|
|
71
|
+
## 4. 快速开始
|
|
103
72
|
|
|
104
|
-
|
|
73
|
+
1. 在 devco 的 agent 列表中选择 **Test** 模式。
|
|
74
|
+
2. 直接输入用例描述:
|
|
105
75
|
|
|
106
|
-
```
|
|
107
|
-
|
|
76
|
+
```text
|
|
77
|
+
打开设置,进入“WLAN”页面,验证可用网络列表正常显示
|
|
108
78
|
```
|
|
109
79
|
|
|
110
|
-
|
|
80
|
+
插件将依次执行:设备检查 → 启动任务 → 按约 30 秒间隔查询进度 → 输出终态结果与报告路径。
|
|
111
81
|
|
|
112
82
|
---
|
|
113
83
|
|
|
114
|
-
##
|
|
84
|
+
## 5. 执行流程与输出
|
|
115
85
|
|
|
116
|
-
|
|
86
|
+
插件按「设备检查 → 启动任务 → 轮询进度 → 输出结果」执行,轮询间隔约 30 秒。
|
|
117
87
|
|
|
118
|
-
|
|
119
|
-
工具参数 > 工厂 options > sidecar > 环境变量 > 默认值
|
|
120
|
-
```
|
|
88
|
+
执行过程中会转述当前操作步骤(每轮只列本轮新增行):
|
|
121
89
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
### sidecar:`.deveco/autotest-plugin.json`
|
|
128
|
-
|
|
129
|
-
放在 devco 工程目录的 `.deveco/` 下(固定路径 `.deveco/autotest-plugin.json`):
|
|
130
|
-
|
|
131
|
-
| 字段 | 类型 | 默认值 | 说明 |
|
|
132
|
-
|---|---|---|---|
|
|
133
|
-
| `cliPath` | string | 无 | `dist/autotest-cli.js` 绝对路径(四源之一;**通常无需配置**,包内解析自动命中依赖树里的同版本 CLI;仅四源全失败才报 T3) |
|
|
134
|
-
| `configPath` | string | 无 | AutoTest `config.yaml` 绝对路径(**可选**:模型段由 devco 凭据注入,见 §模型配置;该文件只承载非模型配置) |
|
|
135
|
-
| `reportsRoot` | string | `<devco 工程目录>/autotest-reports` | 报告根目录;非绝对路径按工程目录解析 |
|
|
136
|
-
| `nodePath` | string | `"node"` | 子进程解释器;受限环境兜底 |
|
|
137
|
-
| `timeoutMinutes` | number | `30` | 超时 kill 阈值(分钟);Loop 任务建议调大(见 §生命周期) |
|
|
138
|
-
| `maxConcurrent` | number | `1` | 最大并发任务数;当前版本恒为 1(busy 即拒绝、不排队) |
|
|
139
|
-
| `env` | object | `{}` | 透传给子进程的附加环境变量(合并进宿主环境,同名覆盖) |
|
|
140
|
-
|
|
141
|
-
示例(`cliPath` 通常无需填写;仅当使用自定义 CLI 路径时才加入该字段):
|
|
142
|
-
|
|
143
|
-
```json
|
|
144
|
-
{
|
|
145
|
-
"configPath": "<AUTOTEST_CONFIG_ABS>",
|
|
146
|
-
"reportsRoot": "<AUTOTEST_REPORTS_ABS>",
|
|
147
|
-
"timeoutMinutes": 30,
|
|
148
|
-
"maxConcurrent": 1,
|
|
149
|
-
"env": {}
|
|
150
|
-
}
|
|
90
|
+
```text
|
|
91
|
+
第 1 条用例执行中(RUNNING,已完成 4 步)
|
|
92
|
+
3. 打开设置应用
|
|
93
|
+
4. 点击“WLAN”入口
|
|
151
94
|
```
|
|
152
95
|
|
|
153
|
-
|
|
154
|
-
> `autotest-plugin.json`。`configPath` / `reportsRoot` 若填写须为本机实际绝对路径
|
|
155
|
-
> (示例中的 `<AUTOTEST_CONFIG_ABS>` / `<AUTOTEST_REPORTS_ABS>` 是占位符,机器专属路径不进版本库);
|
|
156
|
-
> 不填 `configPath` 时插件走 devco 凭据注入模型配置。
|
|
157
|
-
|
|
158
|
-
### 模型配置(由 devco 注入)
|
|
159
|
-
|
|
160
|
-
插件的 CLI 子进程需要一个可用的 `model.unified` 段,解析顺序:
|
|
161
|
-
|
|
162
|
-
1. **用户已配置**——`configPath` 指向的文件、工程目录的 `config.local.yaml`、工程目录的 `config.yaml` 任一含有效 `api_key`(非空且非 `YOUR_API_KEY*` 占位符)→ 以用户配置为准,**不做任何注入**;
|
|
163
|
-
2. **用户未配置,devco 凭据可用**——从 devco 登录态(OAuth)或 `UI_VERIFY_BASE_URL` / `UI_VERIFY_API_KEY` / `UI_VERIFY_MODEL_NAME` 取凭据,合成一份临时 config(`model.unified` 三键齐全)写到系统临时目录,任务终态自动删除;用户 `configPath` 的非模型内容会深合并进去,不会丢;
|
|
164
|
-
3. **用户未配置且凭据不可用**——返回确定性错误(含三条修复指引),**不 spawn** 子进程。
|
|
165
|
-
|
|
166
|
-
第 1 条命中但只有非模型配置时,插件会以该文件为基底、把模型段合成进临时 config(用户显式配置不因模型 key 缺失被丢弃)。
|
|
96
|
+
到达终态后输出执行结果、结论摘要与 JSON / HTML / Markdown 报告路径。
|
|
167
97
|
|
|
168
98
|
---
|
|
169
99
|
|
|
170
|
-
##
|
|
100
|
+
## 6. Loop 闭环
|
|
171
101
|
|
|
172
|
-
|
|
102
|
+
Loop 在用例失败后执行「归因 → 改写 → 重执行」,默认最多 2 轮。
|
|
173
103
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
104
|
+
| `max_loops` | 行为 |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `0` | 只执行一次,不做归因与改写 |
|
|
107
|
+
| `1` | 只执行一次 |
|
|
108
|
+
| `2`(默认) | 最多两轮闭环 |
|
|
109
|
+
| `3` | 最多三轮闭环 |
|
|
180
110
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
```jsonc
|
|
184
|
-
{
|
|
185
|
-
"permission": {
|
|
186
|
-
"autotest_run_task": "allow",
|
|
187
|
-
"autotest_get_report": "allow"
|
|
188
|
-
}
|
|
189
|
-
}
|
|
190
|
-
```
|
|
111
|
+
开启 Loop 后,每轮报告隔离在 `iter_N/` 目录,根目录生成 `loop_result.json` 与 `loop_summary.html`。
|
|
191
112
|
|
|
192
113
|
---
|
|
193
114
|
|
|
194
|
-
##
|
|
195
|
-
|
|
196
|
-
无需模型、无需设备——一次性命令即可验证插件加载链路。全部命令在配置了 `plugin: ["@autotest/plugin"]` 的工程目录执行(前提是包已按 §安装 进入 devco 包缓存;工程级 `npm install` 给出的包名 spec 与本地路径 spec 都不生效),**四项同时成立才算验证通过**:
|
|
115
|
+
## 7. 报告
|
|
197
116
|
|
|
198
|
-
|
|
199
|
-
|---|---|---|
|
|
200
|
-
| 1. 插件被发现 | `deveco debug config` | `plugin_origins` 命中 `@autotest/plugin` |
|
|
201
|
-
| 2. permission 注入 | `deveco debug config` | `permission` 段出现 `autotest_run_task`(与 `autotest_get_report`)条目 |
|
|
202
|
-
| 3. Test 模式注入 | `deveco debug agent test` | tools map 中 `autotest_run_task` / `autotest_get_report` 为 `true`,`verify_ui` / `save_ui_screenshot` / `get_ui_verification_log` 为 `false`(`deveco debug agent build` 中五个均为 `false`) |
|
|
203
|
-
| 4. skill 注册 | `deveco debug config` | `skills.paths` 含 `@autotest/plugin/dist/skills` |
|
|
117
|
+
默认报告根目录:
|
|
204
118
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
**直连 CLI 探针**(不经 devco,验证子进程契约):
|
|
208
|
-
|
|
209
|
-
```bash
|
|
210
|
-
node <AutoTest-nodejs>/dist/autotest-cli.js run \
|
|
211
|
-
--task "Open calculator and verify 2+4=6" \
|
|
212
|
-
--report-dir <绝对临时目录> \
|
|
213
|
-
--config <AutoTest-nodejs>/config.yaml \
|
|
214
|
-
--stream-log
|
|
119
|
+
```text
|
|
120
|
+
<工程目录>/autotest-reports/
|
|
215
121
|
```
|
|
216
122
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
---
|
|
220
|
-
|
|
221
|
-
## 日志与可观测性
|
|
222
|
-
|
|
223
|
-
### 插件日志通道:宿主 server logs(TUI 静默)
|
|
224
|
-
|
|
225
|
-
插件自身的诊断日志——版本日志 `loaded, version=<semver>`、CLI 解析结果、模型来源诊断(来源 / 模型名 / baseUrl / 合成配置路径)、配置与凭据链的降级告警等——统一经**宿主日志通道**输出:
|
|
123
|
+
单次任务:
|
|
226
124
|
|
|
227
|
-
```
|
|
228
|
-
|
|
125
|
+
```text
|
|
126
|
+
autotest-reports/
|
|
127
|
+
└── <task_name>/
|
|
128
|
+
├── *.json
|
|
129
|
+
├── *.html
|
|
130
|
+
├── *.md
|
|
131
|
+
├── agent_*.log
|
|
132
|
+
└── screenPath/
|
|
229
133
|
```
|
|
230
134
|
|
|
231
|
-
|
|
232
|
-
- **TUI 静默**:插件不向 devco 前台 TUI 输出日志——前台界面不被插件的诊断文本污染。需要查看插件日志时,请从宿主 server logs 观察。
|
|
233
|
-
- **实现锚点**:`shared/logger.ts` 提供 `pluginLog(msg)` 与模块级 sink 注册 API(`setHostLogSink` / `resetHostLogSink`);`index.ts` 插件工厂在装配首行以 `client.app.log()` 注册 sink。请求体固定 `service: "autotest-plugin"`、`level: "info"`,`message` 为诊断文本,`extra.ts` 为发送时刻的 ISO 时间戳,`query.directory` 为工程目录。
|
|
234
|
-
- **失败不阻塞**:日志发送为 fire-and-forget——发送失败静默丢弃、不重试,也**不回退**到 stdout / 前台 TUI;未注册 sink 时 `pluginLog` 直接丢弃(fail-closed)。
|
|
235
|
-
- **与任务子进程日志区分**:被 spawn 的 AutoTest 子进程诊断仍走 `<reportDir>/plugin_stream.log`(任务自身的事实记录),与上述插件宿主日志通道相互独立。
|
|
135
|
+
Loop 任务:
|
|
236
136
|
|
|
237
|
-
|
|
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
|
+
```
|
|
238
148
|
|
|
239
|
-
|
|
149
|
+
报告内容包含:每步操作与截图、模型判定、耗时与 Token 用量。`plugin_stream.log` 为插件转述数据源,排查执行问题时优先查看。
|
|
240
150
|
|
|
241
151
|
---
|
|
242
152
|
|
|
243
|
-
##
|
|
244
|
-
|
|
245
|
-
### devco 退出后的子进程(孤儿语义)
|
|
246
|
-
|
|
247
|
-
测试任务由插件 spawn 的子进程执行。devco 退出**不会**杀死运行中的子进程——Windows 没有 POSIX 进程组收割机制,子进程会继续运行直到完成并落盘报告。这是**特性而非缺陷**:任务执行对宿主生命周期不敏感;下次启动 devco 后用 `autotest_get_report` 以 `task_id` 或 `report_dir` 查询,纯文件读照常命中。
|
|
248
|
-
|
|
249
|
-
### 取消语义(abort 与超时兜底)
|
|
250
|
-
|
|
251
|
-
devco 宿主在工具 `execute` 返回后立即触发该次工具调用的 `AbortSignal`(真实调用实测语义)。任务已转入后台后,该信号是工具调用生命周期的**收尾信号**而非用户取消意图——`autotest_run_task` 已忽略该信号(返回前移除 abort 监听),**不会** kill 刚启动的子进程(否则每次调用都会误杀后台任务)。
|
|
153
|
+
## 8. 配置
|
|
252
154
|
|
|
253
|
-
|
|
254
|
-
- **execute 返回后**的 abort 被忽略:后台任务继续运行,直到自然完成或超时。
|
|
255
|
-
- **取消后台任务的兜底 = 超时 kill**:`timeoutMinutes`(默认 30 分钟)到期 → kill + `killed`。超时被杀时,已增量落盘的 stream log / 报告部分仍可读取。
|
|
155
|
+
### 8.1 AutoTest 配置
|
|
256
156
|
|
|
257
|
-
|
|
157
|
+
未提供时插件可使用内置配置运行,模型由 devco 登录态提供。建议自行配置模型与设备,保证环境稳定性。
|
|
258
158
|
|
|
259
|
-
|
|
159
|
+
配置文件按以下顺序查找,命中即用:
|
|
260
160
|
|
|
261
|
-
|
|
161
|
+
1. 显式指定的配置文件
|
|
162
|
+
2. `<工程>/.deveco/autotest/config.local.yaml`(工程本地覆盖)
|
|
163
|
+
3. `<工程>/.deveco/autotest/config.yaml`(工程基础配置)
|
|
164
|
+
4. `~/.deveco/autotest/config.yaml`(全局默认)
|
|
262
165
|
|
|
263
|
-
|
|
166
|
+
最小配置示例:
|
|
264
167
|
|
|
265
|
-
|
|
168
|
+
```yaml
|
|
169
|
+
model:
|
|
170
|
+
unified:
|
|
171
|
+
name: "your-vision-model"
|
|
172
|
+
base_url: "https://your-gateway/v1"
|
|
173
|
+
api_key: "..."
|
|
266
174
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
## 升级须知
|
|
270
|
-
|
|
271
|
-
### 版本与缓存
|
|
272
|
-
|
|
273
|
-
插件版本号硬编码在 `integrations/deveco/index.ts` 的 `VERSION` 常量,与 `integrations/deveco/package.json` 的 `version` 必须一致(契约测试断言)——它同时是版本漂移的诊断锚点(宿主 server logs 的 `loaded, version=<semver>`)。
|
|
274
|
-
|
|
275
|
-
devco 的包缓存目录名固定为 `<name>@latest`,**命中即复用,上游发新版不会自动拉取**。本包的缓存目录即 `%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest`——升级必须先手删它,否则重装仍在用旧包:
|
|
276
|
-
|
|
277
|
-
```bash
|
|
278
|
-
# 1. 删缓存(Windows 路径;目录名即 @autotest/plugin@latest)
|
|
279
|
-
rmdir /s /q "%USERPROFILE%\.cache\deveco\packages\@autotest\plugin@latest"
|
|
280
|
-
# 2. 重新安装
|
|
281
|
-
deveco plugin @autotest/plugin
|
|
175
|
+
device:
|
|
176
|
+
device_sn: "YOUR_DEVICE_SN" # 通过 hdc list targets 获取
|
|
282
177
|
```
|
|
283
178
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
本包只依赖 `@autotest/agent` 的 **CLI**(`dist/autotest-cli.js`),不依赖它的插件入口。因此切换顺序是:
|
|
287
|
-
|
|
288
|
-
1. **先发本包** `@autotest/plugin`(0.1.0)——它可与仍带 `exports["./server"]` 的旧主包共存;
|
|
289
|
-
2. **再发主包**——移除 `exports["./server"]` 与插件构建链的版本。
|
|
179
|
+
说明:
|
|
290
180
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
旧工程把插件入口指向 `@autotest/agent`(`"plugin": ["@autotest/agent"]`),或在 `.deveco/plugins/` 下留有一个 re-export 薄壳。新主包移除 `exports["./server"]` 后:
|
|
296
|
-
|
|
297
|
-
- **症状**:Test 模式里两个工具**静默消失**,`deveco` 启动不报错、不提示——宿主无法解析的插件条目会被跳过,没有失败日志指向它。
|
|
298
|
-
- **自检**:`deveco debug config` 的 `plugin_origins` 若仍显示 `@autotest/agent` 或干脆没有插件条目,即命中此情况。
|
|
299
|
-
- **下线旧配置项**:从 `.deveco/deveco.jsonc` 的 `plugin` 数组删掉 `@autotest/agent` 条目(有旧薄壳文件则一并删除),改成 `"plugin": ["@autotest/plugin"]`;删 devco 缓存目录后重新安装本包,再按 §验证 的四项断言复核。
|
|
181
|
+
- 模型必须支持图片输入;纯文本模型在首次截图后会失败
|
|
182
|
+
- 用户配置了有效模型时优先使用用户配置;未配置时插件从 devco 登录态注入模型三键
|
|
183
|
+
- 任务参数 `device_sn` 仅覆盖设备序列号,不修改 `device.ip` / `device.port`
|
|
184
|
+
- 不传 `device_sn` 时,跟随配置文件的 `device.device_sn`;配置为空时可能自动选择首个在线设备,多设备场景建议显式指定
|
|
300
185
|
|
|
301
186
|
---
|
|
302
187
|
|
|
303
|
-
##
|
|
188
|
+
## 9. 故障排查
|
|
304
189
|
|
|
305
|
-
|
|
190
|
+
### Test 模式无法执行用例
|
|
306
191
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
npm run typecheck
|
|
311
|
-
npm pack # 本地检查 tarball 内容(files 只含 dist,README 由 npm 自动收入)
|
|
312
|
-
npm publish # scoped 包,publishConfig.access=public
|
|
313
|
-
```
|
|
192
|
+
- 确认当前为 **Test** 模式
|
|
193
|
+
- 确认插件已在 devco 中启用
|
|
194
|
+
- 确认插件安装后已重启 devco
|
|
314
195
|
|
|
315
|
-
|
|
196
|
+
### 找不到设备
|
|
316
197
|
|
|
317
198
|
```bash
|
|
318
|
-
|
|
319
|
-
npm run check:pack # 主包产物检查:0 fail 0 skip
|
|
320
|
-
npm run release:check # 聚合门:主包 build → check:pack → 本包 npm test
|
|
199
|
+
hdc list targets
|
|
321
200
|
```
|
|
322
201
|
|
|
323
|
-
|
|
202
|
+
确认设备在线且已解锁;多设备时显式传入 `device_sn`。
|
|
324
203
|
|
|
325
|
-
|
|
204
|
+
### 无法启动应用
|
|
326
205
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
## 故障排查
|
|
206
|
+
应用无法按显示名启动(未找到、名称重复或启动了错误应用)时,请在用例中显式给出应用包名:
|
|
330
207
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
| T2 | `configPath` 三源全空的状态描述(**不是报错**:`configPath` 可选) | 无需处理——模型段由 devco 凭据注入;仅当还要携带非模型配置(设备 / Agent / 输出)时才三选一提供 `configPath`:① sidecar 写 `{"configPath": "<绝对路径>/config.yaml"}`;② 环境变量 `AUTOTEST_CONFIG=<绝对路径>`;③ 调用工具时传 `config_path` 参数 |
|
|
335
|
-
| T3 | 未找到 CLI(四源全失败,含包内解析) | 确认 `@autotest/agent` 安装完整(含 `dist/autotest-cli.js` 且版本落在 `>=0.0.25 <0.2.0`);仍失败时在 `.deveco/autotest-plugin.json` 写 `{"cliPath": "<绝对路径>/dist/autotest-cli.js"}` 显式指定 |
|
|
336
|
-
| T4 | 子进程启动失败 | 检查 `node` 是否在 PATH(或 sidecar `nodePath` 指向有效解释器)、CLI 文件是否存在 |
|
|
337
|
-
| T5 | `autotest_get_report` 未传参数 | `task_id` 与 `report_dir` 至少提供一个 |
|
|
338
|
-
| T6 | 任务启动前已被取消 | abort 预检命中,未创建子进程 |
|
|
339
|
-
| T7 | 报告目录发现多个候选 JSON | 传精确的 `report_dir` 重查(单任务报告与目录同名;loop 任务传含 `loop_result.json` 的任务根目录) |
|
|
340
|
-
| T8 | 报告 JSON 解析失败 | 文件可能损坏或为非报告 JSON;可重试或人工检查该文件 |
|
|
341
|
-
| — | 模型凭据不可用(未配置 `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` |
|
|
342
|
-
|
|
343
|
-
busy(T1)时的推荐动作:`autotest_get_report` 传错误信息里的 `task_id`,先查旧任务的进度/结果,完成后再发起新任务——不要反复发起新任务。
|
|
208
|
+
```text
|
|
209
|
+
打开应用(包名 com.example.app),进入“WLAN”页面,验证可用网络列表正常显示
|
|
210
|
+
```
|
|
344
211
|
|
|
345
|
-
|
|
212
|
+
`com.example.app` 替换为实际包名,可通过 `hdc shell bm dump -a` 查看。
|
|
346
213
|
|
|
347
|
-
|
|
214
|
+
### 任务长时间处于 RUNNING
|
|
348
215
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
```
|
|
216
|
+
- 继续轮询任务状态
|
|
217
|
+
- 查看任务目录下 `plugin_stream.log`,确认是否存在设备断连、模型超时或重试记录
|
|
352
218
|
|
|
353
|
-
|
|
219
|
+
### 模型调用失败
|
|
354
220
|
|
|
355
|
-
|
|
356
|
-
git worktree add ../autotest-rollback <last-good-tag>
|
|
357
|
-
cd ../autotest-rollback/AutoTest-nodejs
|
|
358
|
-
npm ci
|
|
359
|
-
npm version patch --no-git-tag-version
|
|
360
|
-
npm publish --tag next
|
|
361
|
-
```
|
|
221
|
+
属于模型服务侧问题,可尝试:
|
|
362
222
|
|
|
363
|
-
|
|
223
|
+
- 稍后重试
|
|
224
|
+
- 更换稳定的多模态模型
|
|
225
|
+
- 在 AutoTest 配置 `model.unified` 中显式指定可用模型
|
|
364
226
|
|
|
365
|
-
|
|
366
|
-
# 先让少量工程用 <主包补丁版> 验证:npm i @autotest/agent@next
|
|
367
|
-
npm dist-tag add @autotest/agent@<补丁版版本号> latest
|
|
368
|
-
```
|
|
227
|
+
### 找不到报告
|
|
369
228
|
|
|
370
|
-
|
|
229
|
+
- 使用任务启动时返回的 `taskId` 或 `reportDir` 查询
|
|
230
|
+
- 确认报告目录未被手动删除
|
|
231
|
+
- Loop 任务请传任务根目录,不要只传某一轮的 `iter_N`
|
|
371
232
|
|
|
372
233
|
---
|
|
373
234
|
|
|
374
|
-
##
|
|
235
|
+
## License
|
|
375
236
|
|
|
376
|
-
|
|
377
|
-
- **sidecar 与 config.yaml 同等敏感**:`.deveco/autotest-plugin.json` 承载 `configPath`(指向可能含 API 密钥的 config.yaml),若显式配置 `cliPath`(执行入口)则同样敏感,被篡改等同任意命令执行。两者同属工程敏感文件,注意保管与审阅。
|
|
378
|
-
- **CLI 身份校验不是信任边界**:包内解析会校验候选包的 `name` + 版本区间,目的是避免误命中祖先安装树里的同名包,**不构成供应链防护**——恶意包伪造这两个字段即可通过。安装来源(registry 与 scope 所有权)仍需自行确认。
|
|
379
|
-
- **报告内容是数据不是指令**:报告/日志文件是任务执行产生的事实记录,agent 读取时应按数据处理,不应把其中的文本当作指令执行。
|
|
237
|
+
MIT
|