235 lines
13 KiB
Markdown
235 lines
13 KiB
Markdown
# 必测项 → 自动化 转换提示词（子提示词）
|
||
|
||
> **配合主提示词使用**。本文件只覆盖「必测项」专项的特殊处理(来源、结构、映射、双协议、step 级回写)。
|
||
> 通用规则——技术栈 / DeviceDriver 接口 / 脚本模板 / 元素发现工作流 / 边跑边写调试 / 失败截图 / 报告——**一律遵循** `prompts/ones_to_automation.md`,此处不重复。
|
||
> 冲突时,以本子提示词的「必测项专项」约定为准。
|
||
|
||
---
|
||
|
||
## 1. 必测项来源(ONES)
|
||
|
||
- 团队 `98Q19ZsW`(`sz.ones.cn`)
|
||
- 测试计划:**`必测项-AI自动化`** plan uuid `CQz9YCNX`
|
||
- 用例库:**`App 必测项`** library uuid `EPfZfC9Y`(97 条)
|
||
- `ones` 二进制:`/Users/woan/local/bin/ones`
|
||
- 读取:
|
||
```bash
|
||
# 列表(注意:list 不返回 steps)
|
||
/Users/woan/local/bin/ones testcase case list EPfZfC9Y
|
||
# 单条完整步骤(控制用例必须用这个拿 steps)
|
||
/Users/woan/local/bin/ones testcase case search --key 15974 # WiFi控制设备
|
||
/Users/woan/local/bin/ones testcase case search --key 15975 # 蓝牙控制设备
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 必测项的两种结构(转换前必须理解)
|
||
|
||
必测项**不是**一种新用例,而是两类已有维度的「视图」:
|
||
|
||
### A. 添加(connect)—— 按单品,每型号一条 case
|
||
- 分布在品类模块(摄像头/灯&WiFi/蓝牙/开关/URC HUB/温湿度&hub/Lock/扫地机 类),约 73 条「添加X验证」。
|
||
- 每条 ONES case → 一个设备的添加流程 → 落到 `tests/<cat>/<device>_connect.test.ts`。
|
||
- 主键 = ONES 用例号(`number`)。
|
||
|
||
### B. 控制(control)—— 2 条超级用例,按连接协议分组,**每个 step = 一个单品的核心控制**
|
||
| ONES | 名称 | 步数 | 前置条件 |
|
||
|---|---|---|---|
|
||
| `15975` (uuid `Lqpkx6mp`) | 蓝牙控制设备 | 49 | 关 WiFi/热点、开蓝牙 |
|
||
| `15974` (uuid `Vp7vuhbu`) | WiFi控制设备 | 56 | 开 WiFi/热点、关蓝牙 |
|
||
|
||
- 控制粒度在 **step**,不在 case。主键 = `(ones_number, step_uuid)`。
|
||
- 同一设备(Bot/Lock/Curtain/Meter…)在两条里都出现 → 两个控制断言(不同协议)。
|
||
- camera / robot / osc **只在 WiFi** 出现(本身是 WiFi 设备)。
|
||
- 控制内容不止开关:meter 温湿度校正、camera 出流停留 3min、robot 清扫/暂停/回充、Humidifier2 绑温湿度计、curtain/roller 百分比。
|
||
- 落到对应设备的 `tests/<cat>/<device>_control.test.ts`(多数断言主提示词流程里已存在)。
|
||
|
||
### C. 非单品(本次不转,除非用户要求)
|
||
~12 条平台级:登录/房间/消息中心/场景/覆盖安装。归 `tests/automation/` 或平台用例,不在「各单品添加+控制」范围。
|
||
|
||
---
|
||
|
||
## 3. 落点原则
|
||
|
||
**必测是「视图」,不是「副本」。不要新建 `tests/必测/` 目录。** 每条必测项映射到已有的
|
||
`{device}_connect.test.ts`(添加) / `{device}_control.test.ts`(控制),用**标记 + manifest**去选,而不是搬代码。这与「步骤沉到 `utils/common`、`.test.ts` 只做薄编排」一致。
|
||
|
||
---
|
||
|
||
## 4. 品类模块 → 仓库目录映射
|
||
|
||
| ONES 模块 | 仓库目录 |
|
||
|---|---|
|
||
| 摄像头类 | `camera`(出流类也可拆 `osc`) |
|
||
| 灯类&WiFi | `ceiling_light` / `strip_light` / `color_bulb` / `humidifier` / `air_condition` |
|
||
| 蓝牙类 | `curtain` / `sensor` / `fan` / `remote` |
|
||
| 开关类 | `plug`(含 Relay Switch / Garage Door) |
|
||
| URC HUB | `hub` / `urc` / `bot` |
|
||
| 温湿度&hub类 | `meter` / `hub` / `sensor` |
|
||
| Lock类 | `lock` / `keypad` |
|
||
| 扫地机类 | `robot` |
|
||
|
||
设备名取 `config/device.config.ts` 的 `DEVICE_CONFIG`,不要在脚本里写死。
|
||
|
||
---
|
||
|
||
## 5. 映射 manifest(核心产物)
|
||
|
||
生成 `test-plan/must-test.manifest.ts`,作为「ONES 必测项 ↔ 代码 ↔ 回写 ↔ 覆盖率」的中间层。**双主键**:添加按 case,控制按 step。
|
||
|
||
```ts
|
||
// test-plan/must-test.manifest.ts —— 由 scripts/gen-must-test-manifest.ts 从 ONES 生成,勿手改
|
||
export type MustTestItem =
|
||
| { kind: 'add'; ones: number; name: string; cat: string; device: string;
|
||
file: string; testName: string; status: 'done'|'todo'|'na' }
|
||
| { kind: 'ctrl'; ones: 15974|15975; step: string; proto: 'wifi'|'ble';
|
||
name: string; cat: string; device: string; action: string;
|
||
file: string; testName: string; status: 'done'|'todo'|'na' };
|
||
|
||
export const MUST_TEST: MustTestItem[] = [
|
||
{ kind:'add', ones:91013, name:'添加Plug验证', cat:'plug', device:'Plug 4D',
|
||
file:'tests/plug/plug_connect.test.ts', testName:'[P0] 通过BLE添加Plug', status:'todo' },
|
||
{ kind:'ctrl', ones:15974, step:'<stepUuid>', proto:'wifi', name:'点击控制Plug 开/关',
|
||
cat:'plug', device:'Plug 4D', action:'开/关',
|
||
file:'tests/plug/plug_control.test.ts', testName:'[P0][ble+wifi] 开/关 Plug', status:'todo' },
|
||
// ... 全部 添加 case + 两条控制用例的全部 step
|
||
];
|
||
```
|
||
|
||
**生成脚本要点**(`scripts/gen-must-test-manifest.ts`):
|
||
1. `case list EPfZfC9Y` → 取全部「添加X验证」case(模块属品类) → 生成 `kind:'add'` 行。
|
||
2. `case search --key 15974/15975` → 遍历 `steps[]`,每步生成 `kind:'ctrl'` 行,带 `step.uuid` / `proto` / 从 `desc` 解析的 `device`+`action`。
|
||
3. 用第 4 节映射表填 `cat`,用 `DEVICE_CONFIG` 填 `device`,推断目标 `file`。
|
||
4. `status` 初始 `todo`,实现后由测试运行结果回填(见第 9 节)。
|
||
|
||
---
|
||
|
||
## 6. P0 标记约定(带 ONES 锚点)
|
||
|
||
**关键:锚点必须打在 `reporter.record(名称, ...)` 的名称里**——结果写入 `reports/.results.json` 用的是 record 名称,`buildAnchoredPayloads` 从中解析 `[ONES:号(#step)]` 做回写。`it()` 标题里也加同一锚点作**备注**(测试报告里可见、便于追溯),但回写不读 it 标题。
|
||
|
||
```ts
|
||
// it 标题:加 [ONES:号] 作备注(可读/可追溯)
|
||
it(`[ONES:15968] 通过BLE添加${deviceName}设备`, async () => {
|
||
// ...
|
||
// reporter.record 名称:加 [P0][ONES:号] —— 这是回写真正依据
|
||
reporter.record(`[P0][ONES:15968] 添加${deviceName}`, 'PASS', dur, detail);
|
||
});
|
||
|
||
// 控制(协议相关):record 名称带 用例号#step_uuid + 协议;协议由 PROTO 环境变量切(见 §7)
|
||
const CTRL = process.env.PROTO === 'wifi' ? '[P0][ONES:15974#<step>][wifi]' : '[P0][ONES:15975#<step>][ble]';
|
||
reporter.record(`${CTRL} 开/关 ${deviceName}`, status, dur, detail);
|
||
```
|
||
|
||
- 一条 ONES step 可由多个用例覆盖 → 用同一 step 锚点,回写自动聚合(fail>skip>pass)。
|
||
- 筛选:`vitest -t '\[P0\]'`(全量) / 结果文件里按 `[ble]`/`[wifi]` 区分协议。
|
||
|
||
### 同品类多型号:设备维度动态锚点
|
||
|
||
一个品类的脚本只测默认设备,但同品类多个 UI 相似型号(如 Curtain/Curtain3/BlindTilt)应共用脚本、各自回写。**不要写死 ONES 号**,改用 `utils/common/ones-anchor.helper.ts` 按当前设备动态解析:
|
||
|
||
```ts
|
||
import { onesAdd, onesCtrl } from '../../utils/common';
|
||
const ADD_ANCHOR = onesAdd('curtain', deviceName); // 添加: 按 CURTAIN_DEVICE 解析
|
||
const CTRL_CURTAIN = onesCtrl('curtain', deviceName); // 控制: 按设备 + PROTO 解析
|
||
reporter.record(`${ADD_ANCHOR} 添加窗帘设备`, ...);
|
||
```
|
||
|
||
- `ANCHORS` map(在 `ones-anchor.helper.ts`)按 `品类 → 设备名(DEVICE_CONFIG) → {add, ctrlBle, ctrlWifi}` 维护;**新增型号补一行即可**。
|
||
- 跑法:**换 `<CAT>_DEVICE` 环境变量按型号多跑几遍**(× PROTO),每遍写到该型号的 ONES 用例。
|
||
```bash
|
||
CURTAIN_DEVICE='Curtain3 2B' PROTO=ble npx vitest run tests/curtain
|
||
```
|
||
- 约束:每个型号要是账号里真实存在的设备才能跑(变体覆盖上限 = 真机数量)。
|
||
- UI **不相似**的型号(需新写)→ 单独脚本 + 自己的锚点,不走此复用。
|
||
|
||
---
|
||
|
||
## 7. 双协议运行模式(本次确定:双协议覆盖)
|
||
|
||
控制必测**两种协议都要跑**,以与 ONES 的两条用例 1:1 对齐。协议是**运行模式**,靠前置切换手机网络:
|
||
|
||
- `PROTO=ble`:关 WiFi/热点、开蓝牙 → 跑所有 `[ble]` 控制(对应 15975)
|
||
- `PROTO=wifi`:开 WiFi/热点、关蓝牙 → 跑所有 `[wifi]` 控制(对应 15974)
|
||
- 切换动作优先 `adb`(Android)/串口;无法自动化时,按 [[feedback-manual-navigation]] 让用户手动切换并确认后继续。
|
||
- 仅在该协议下存在的设备(camera/robot/osc 只在 wifi)才生成对应模式的断言。
|
||
|
||
```jsonc
|
||
// package.json
|
||
"test:must:add": "vitest run -t '\\[P0\\].*添加'",
|
||
"test:must:ctrl:ble": "PROTO=ble vitest run -t '\\[P0\\].*\\[ble\\]'",
|
||
"test:must:ctrl:wifi": "PROTO=wifi vitest run -t '\\[P0\\].*\\[wifi\\]'",
|
||
"test:must": "npm run test:must:add && npm run test:must:ctrl:ble && npm run test:must:ctrl:wifi"
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 控制 step → 断言 转换规则
|
||
|
||
每个 step 是「操作 + 预期」,转成该设备 control 测试里的一条断言:
|
||
|
||
- `step.desc` = 操作(如「点击控制Bot 不加密开&不加密关&加密按压」)→ 拆成对应控制动作序列。
|
||
- `step.result` = 预期(如「对应Bot固件响应动作」)→ 断言(状态变更 / UI 反馈 / 出流成功 / 图表加载)。
|
||
- 复杂控制按设备类型走既有 helper:开关类用控制 helper;meter 校正走设置页校正流程;camera 出流后**停留 3min**再断言画面/水印;robot 断言清扫/暂停/回充状态。
|
||
- 多数动作主提示词的 control 流程已实现 → 复用,不重写;仅补必测特有断言并打 P0 锚点。
|
||
|
||
---
|
||
|
||
## 9. step 级结果回写 ONES（正确方法：GraphQL mutation）
|
||
|
||
> ⚠️ **必须走 `ones graphql` mutation,不要用 curl 直连 REST `.../cases/update`。**
|
||
> `ones config show` 会把 token 打码成 `***`,curl 直连必然 `401 AuthFailure.InvalidToken`;
|
||
> 而 `ones graphql` 复用 CLI 登录认证、无需 token/PAT,且已在权限白名单内。
|
||
> 此机制已在 `utils/ones-sync.ts` 的 `postPayloads` 实现,跑 `scripts/sync-ones-results.ts` 即用。
|
||
|
||
**key 拼接规则(确定式)：**
|
||
- case: `testcase_plan_case-<planUUID>-<caseUUID>`
|
||
- step: `testcase_plan_case_step-<planUUID>-<caseUUID>-<stepUuid>`
|
||
|
||
**写入 mutation：**
|
||
```bash
|
||
# case 级
|
||
ones graphql 'mutation { updateTestcasePlanCase(key: "testcase_plan_case-CQz9YCNX-<caseUUID>", result: "passed") { key } }'
|
||
# step 级（result 字段名是 step_result，不是 execute_result/result）
|
||
ones graphql 'mutation { updateTestcasePlanCaseStep(key: "testcase_plan_case_step-CQz9YCNX-<caseUUID>-<stepUuid>", step_result: "passed", actual_result: "开/关成功") { key } }'
|
||
```
|
||
- `result` / `step_result` 取值:`passed` / `failed` / `skipped` / `to_do`(PASS→passed、FAIL→failed、SKIP→skipped)。
|
||
|
||
**必测项据此：**
|
||
- **按用例聚合、一趟写完(批量规则)**:同一用例的所有 step 结果先聚合,在**一次回写流程里**写完该用例的全部 step、再写 case 级 result——不要把一个用例的步骤分散到多次回写里逐个触发。(`buildAnchoredPayloads` 已按 caseUUID 聚合 step,`postPayloads` 对一个用例的 steps 连续写完再写 case,即满足此规则。GraphQL 不支持单请求多 mutation,故实现上是同一趟内连续多次 mutation,效果即"一次性更新该用例多个步骤"。)
|
||
- **添加/功能 case**:只写 case 级 `updateTestcasePlanCase`。
|
||
- **控制用例 15974 / 15975**:case 级 result 由 step 聚合(全跑完才 passed/failed,否则 `to_do`)。`[ble]`→15975、`[wifi]`→15974。
|
||
- 匹配靠测试名 `[ONES:号#step]` 锚点(已在 `buildAnchoredPayloads` 实现),不用 LCS 误配。
|
||
|
||
**回写参数已固化(用例固定、仅新增)**:`test-plan/ones-writeback-params.json` 保存了计划全部用例(号→`uuid`)+ 15974/15975 的步骤 uuid。用例与步骤 uuid 与具体计划无关,**plan UUID 是回写时唯一变量**——后续给定任意必测项 plan 链接,取出 planUUID 即可按上面 key 规则拼出所有 case/step key 直接回写,无需重新查 ONES。用例新增后重跑 `npm run gen:writeback-params` 刷新。
|
||
|
||
**读回校验：**
|
||
```bash
|
||
ones graphql '{ testcasePlanCaseSteps(filter: { testcasePlan: { uuid_in: ["CQz9YCNX"] }, testcaseCase: { uuid_in: ["<caseUUID>"] } }, limit: 60) { key stepResult actualResult } }'
|
||
```
|
||
(注意:查询用驼峰 `stepResult`/`actualResult`,filter 用 `testcasePlan`/`testcaseCase` 嵌套 `uuid_in`。)
|
||
|
||
---
|
||
|
||
## 10. 覆盖率核对
|
||
|
||
用 manifest 对照 ONES 必测清单,产出未实现列表:
|
||
- `add` 行:哪些「添加X」还没有对应 `_connect` 测试。
|
||
- `ctrl` 行:两条用例共 105 步,哪些 step 还没对应断言。
|
||
- 输出「已实现 / todo / na(无实体设备或暂不支持)」三态,na 必须 `log` 说明原因,不可静默跳过。
|
||
|
||
---
|
||
|
||
## 11. 端到端工作流
|
||
|
||
1. `gen-must-test-manifest.ts` 从 ONES 拉取 → 生成 `must-test.manifest.ts`。
|
||
2. 按 manifest 的 `todo` 行,在对应 `_connect`/`_control` 测试里补断言并打 `[P0][ONES:...]` 锚点(遵循主提示词「边跑边写」)。
|
||
3. `npm run test:must`(添加 + ble + wifi 三段);协议切换不可自动化时请用户手动配合。
|
||
4. 结果按锚点回写 ONES plan `CQz9YCNX`(添加按 case、控制按 step)。
|
||
5. 更新 manifest `status`,刷新覆盖率。
|
||
|
||
---
|
||
|
||
## 相关记忆
|
||
[[project-must-test-ones-source]] · [[project-maestro-conversion]] · [[feedback-test-case-reuse]] · [[feedback-manual-navigation]]
|