android2harmony 0.1.5 → 0.1.6

package/skills/hmos-integration-test/README.md

@@ -0,0 +1,341 @@
+# Self-Test 使用文档
+
+## 简介
+
+**Self-Test** 是 HomeTrans 的端到端真机自测能力——你把一份 Markdown 测试用例和一个 HAP 交给我，我帮你把用例跑在鸿蒙真机或模拟器上，产出可读的测试报告。如果测试失败，我还能**自动分析原因、修改代码、重建 HAP、重新测试**，直到全部通过。测试和修复不是两个功能拼在一起，而是一条统一的工作流：你只需要说一句话，剩下的事情系统自动完成。
+
+---
+
+## 我能做什么
+
+- **把 Markdown 测试用例变成机器可读的 JSON**：解析你写的 `test_case.md`，自动提取包名、替换应用名，生成 AutoTest 可执行的 `testcases.json`。
+- **在鸿蒙真机或模拟器上跑自动化测试**：连接真机或启动模拟器，安装 HAP，逐条执行用例，生成带通过率和失败详情的报告。
+- **测试失败后自动修复并重测**：读到失败报告 → 白盒审查源码 → 修改代码 → 重新编译 HAP → 重新测试 → 如果还有失败则继续循环，默认最多 3 轮（可通过 `max-rounds` 参数配置）。
+
+---
+
+## 快速开始
+
+你说一句话，系统跑完全程。最简写法：
+
+> 跑自测，自动修复
+
+更完整的写法（指定所有路径）：
+
+> 跑自测，测试用例在 `D:\project\test_case.md`，HAP 在 `D:\project\entry-default.hap`，输出到 `D:\project\output`
+
+**然后会发生什么：**
+
+1. **测试与修复循环** — 默认最多 3 轮（可通过 `max-rounds` 参数配置），每轮跑完后产物快照到 `output-path/round-{n}/`：
+   - 首轮：解析 `test_case.md` → 写出 `output-path/testcases.json` 与 `app-metadata.json` → 连接真机或模拟器、安装 HAP、跑 AutoTest → 产出 `output-path/self-test-report.md`
+   - 测试完成后，SKILL 把当轮的 `self-test-report.md`、`task/`、`_extracted.json`（若有）快照到 `output-path/round-{n}/`
+   - Fix：白盒审查代码 → 修改源码 → 产出 `round-{n}/self-test-fix-report.md`
+   - Build：调用 `hmos-fix-build-errors` 重新编译 → 从构建输出重新收集包集合并更新下一轮使用的 HAP/HSP
+   - 后续轮：跳过解析阶段，直接读首轮已生成的 `testcases.json` + `app-metadata.json`，用新 HAP 跑测试 → 同样快照到对应轮 `round-{n}/`
+2. **HAP 镜像** — 循环结束后，最后一轮的 HAP 复制到 `output-path/entry-default.hap`，方便直接取用
+
+**最终产物**：都在 `output-path/` 下——`testcases.json` / `app-metadata.json`（根目录，跨轮共享）、`self-test-report.md` 与 `task/`（根目录，最新一轮）、`entry-default.hap`（循环结束后镜像），以及每轮历史快照 `round-{n}/`。完整清单见下方 [输出产物](#输出产物) 一节。
+
+---
+
+## 输入参数
+
+### 测试参数
+
+| 参数 | 是否必填 | 说明 |
+|------|----------|------|
+| `hap-path` | 必填 | 包路径，支持**一个或多个**（用逗号分隔）。每一项可以是 `.hap`/`.hsp` 文件，也可以是目录。所有项汇总起来要凑齐完整包集合：恰好一个 entry HAP + 其余 feature HAP / 应用内 HSP。**entry HAP 和 HSP 可以放在不同目录**——系统会把所有列出路径里的 `.hap`/`.hsp` 收集到一起，一次事务安装（应用内 HSP 不能单独装，必须和主包同一事务）。例：`D:\out\entry-default.hap, D:\hsp_out` |
+| `output-path` | 可选，默认 = `test-case-path` 所在目录 | 所有产物输出到这个目录（`testcases.json`、`app-metadata.json`、`self-test-report.md`、`task/` 都写在此根目录）。不指定时直接写在用例文件同目录 |
+| `project-dir` | 可选（自动从 `hap-path` / `test-case-path` 向上查找 `AppScope/app.json5` 推导；推导失败才询问） | HarmonyOS 工程根目录（含 `AppScope/app.json5`），用于解析 `bundle_name` / `app_name` |
+| `test-case-path` | 必填 | `test_case.md` 的路径 |
+| `pre-test-case-path` | 可选 | 前置用例 `pre_test_case.md` 的路径。不传会自动在 `test-case-path` 同目录查找 `pre_test_case.md` |
+| `max-rounds` | 可选，默认 `3` | 测试修复循环的最大迭代轮数。必须为正整数（`>= 1`）。仅在启用修复循环时生效 |
+
+> 首轮（round 1）解析 `test_case.md`（及发现的 `pre_test_case.md`）写出 `testcases.json` + `app-metadata.json` 再跑测试；后续轮（round 2+）跳过解析阶段，直接复用首轮写出的两个 JSON。两个 JSON 都不存在或为空时硬失败，需重跑首轮。
+
+### 自动修复参数
+
+以下参数仅在进入修复循环时使用，由 Skill 自动从 `app-metadata.json` 获取，你通常不需要手动指定：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `harmony-project-dir` | 是 | 自动从 `app-metadata.json` 的 `project_root` 字段读取 |
+| `android-project-path` | 否 | Android 参考项目路径。提供后 fixer 会参考 Android 实现来修 bug，质量更高 |
+
+---
+
+## 输出产物
+
+`testcases.json` 和 `app-metadata.json` 在首轮（round 1）写入 `output-path/` 根目录，后续轮直接复用，不再重新生成。`self-test-report.md` 与 `task/` 每轮都会在根目录覆盖更新，跑完每轮后由 SKILL 快照到 `output-path/round-{n}/`。循环结束后，最后一轮的 HAP 镜像到根目录。
+
+| 文件 | 写入位置 | 内容 |
+|------|----------|------|
+| `testcases.json` | `output-path/` 根目录（首轮写入，跨轮共享） | 结构化的用例列表，供 AutoTest 逐条执行 |
+| `app-metadata.json` | `output-path/` 根目录（首轮写入，跨轮共享） | `{ bundle_name, app_name, project_root }` |
+| `_extracted.json` | `output-path/` 根目录（首轮写入，跨轮快照保留） | 用例提取的中间文件，排查问题时有用，通常不需要关注 |
+| `self-test-report.md` | `output-path/` 根目录（每轮覆盖，跨轮快照保留） | 可读的测试报告，含通过率、失败原因、每条用例的 AutoTest 任务路径 |
+| `task/task_<时间戳>/` | `output-path/task/`（每轮覆盖，跨轮快照保留） | 每条用例的 HTML 报告、截图、Agent 日志 |
+| `self-test-fix-report.md` | `output-path/round-{n}/`（Fix 步骤，有失败的轮次） | 白盒审查结论、根因分析、修改内容、修复结果 |
+| `self-test-fix-commit-info.md` | `output-path/round-{n}/`（Fix 步骤） | `commit_id: <hash>` 或 `commit_id: none` |
+| `entry-default.hap` | 构建输出目录（Build 步骤）；循环结束后可镜像到 `output-path/` 根目录 | 修复后重新编译的 entry HAP |
+
+> **提示**：`output-path/` 根目录下的报告和 task 始终是最近一轮的最新产物；要查看某一轮的历史快照，进入对应的 `round-{n}/` 目录即可。
+
+---
+
+## 工作流程
+
+一次完整的 Self-Test 跑下来会经历下面这些阶段，简化的流程示意：
+
+```
+你提供: test_case.md + HAP
+  │
+  ▼
+┌─ 解析阶段（仅首轮）─────────────────────────────────────────┐
+│                                                              │
+│  读取 test_case.md → LLM 提取动作/预期结果 → 替换应用名为包名  │
+│  → testcases-tool 生成 testcases.json + 写入 app-metadata.json │
+│                                                              │
+└──────────────────────────────┬───────────────────────────────┘
+                               │
+                               ▼
+┌─ 测试与修复循环（每轮跑完后快照到 output-path/round-{n}/）──┐
+│                                                              │
+│  ┌── Test ─────────────────────────────────────────────┐    │
+│  │ 检测真机/模拟器连接 → 安装 HAP → AutoTest 批量执行用例   │    │
+│  │ → 每 60 秒轮询 → 产出至 output-path/ → 快照 round-{n}/   │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│                  全部通过?                                    │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            是(退出循环)    否(进入修复)                         │
+│                             │                                  │
+│  ┌── Fix ──────────────────────────────────────────────┐    │
+│  │ self-test-fixer 读报告 → 白盒审查代码                 │    │
+│  │ → 区分 confirmed(真bug) / false_positive(误报)       │    │
+│  │ → 只修改 confirmed → git commit                      │    │
+│  │ → 产出 round-{n}/self-test-fix-report.md             │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│                  有确认缺陷?                                   │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            否(退出循环)    是(进入编译)                         │
+│                             │                                  │
+│  ┌── Build ────────────────────────────────────────────┐    │
+│  │ 调 `hmos-fix-build-errors` 重新编译 → 从构建输出重新收集 entry/HSP │    │
+│  │ → 组装到 round-{n}/package-set/ 供下一轮安装           │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│              未达上限? n++; 回到 Test                          │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            是(下一轮)     否(退出循环)                         │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+               循环结束 → 仅镜像最终轮的签名安装包 (HAP/HSP) 到 output-path/；
+               self-test-report.md 已位于 output-path/ 根目录，无需镜像
+```
+
+### 循环停止条件
+
+满足以下任一条件，循环立即停止：
+
+| 条件 | stop_reason | 说明 |
+|------|-------------|------|
+| 全部通过 | `all_passed` | 报告 `failed == 0`，所有用例通过 |
+| 无确认缺陷 | `no_confirmed_defects` | fixer 判定所有失败都是测试误报（false positive），没有需要修改的代码缺陷 |
+| 达到最大轮数 | `max_rounds_reached` | 已完成配置的最大轮数循环（`max-rounds`，默认 3），仍有失败未解决 |
+| 编译未产出 HAP（异常） | `no_hap` | 重建后在构建输出中找不到 entry HAP，无法继续测试 |
+| 用例列表为空（异常） | `no_testcases` | `testcases.json` 里 0 条用例，没有可跑的内容。常见原因：解析阶段没识别到 `### Scenario:` 区块 |
+| 自测 agent 早退（异常） | `agent_early_exit` | 集成测试 skill 在跑用例之前就退出了（设备没连、模型 api_key 没配（`HOMETRANS_MODEL_API_KEY` 环境变量或 `~/.hometrans/autotest.yaml`）、`@autotest/agent` 未找到且自动安装失败、batch 启动失败 / 超时 / 崩溃、前置条件不满足但所需 JSON 缺失等），或根本没生成 `self-test-report.md`（skill 在产出报告前就失败退出）。报告首行会是 `status: FAIL`，第二行 `reason: <原因>`。**这种情况下不会进入 fix 循环**——这些是环境/前置条件问题，不是应用缺陷 |
+
+---
+
+## 前置用例（Pre-Cases）
+
+如果 `test_case.md` 同目录下有 `pre_test_case.md`，系统会自动把它作为前置用例合并进去。前置用例是一些**环境准备操作**——比如授权弹窗、跳过引导、导入素材、授予权限。
+
+- 前置用例在 `testcases.json` 中排在最前面，`case_name` 会自动加 `[PRE] ` 前缀
+- 跑测试时最先执行，为后续用例准备环境
+- **前置用例失败不代表应用有 bug**——通常是没素材、没权限、系统弹窗没弹等环境问题
+- 测试报告会单独标注**常规通过率**（排除前置用例），这才是衡量应用质量的主要指标
+
+---
+
+## 报告解读
+
+### 测试报告（self-test-report.md）
+
+每份报告包含以下部分：
+
+- **测试概览**：测试套件名、测试时间、设备序列号、应用名（含 bundle_name）、HAP 文件名、总用例数（前置+常规拆分）、通过/失败数（均拆分子项）、常规通过率、含前置通过率
+- **前置用例**：`[PRE]` 开头的用例，与常规用例分开列出，各自从 1 开始编号（Pre 1、Pre 2... / Case 1、Case 2...）
+- **用例详情**：每条用例的动作、预期结果、AutoTest 判定结果、失败原因
+- **测试总结**：总计用例、常规通过率（反映需求质量）、前置通过率、总计通过/未通过、未通过用例列表、建议
+- **每条用例都标注了 `**AutoTest 任务路径**`**：指向该用例的原始执行目录（HTML 报告、截图、日志）
+
+**PASS / FAIL / UNKNOWN 的含义：**
+
+- `PASS` — 测试通过
+- `FAIL` — 测试失败或超时/崩溃，`reason` 字段说明原因
+- `UNKNOWN` — 有产出报告但无法明确判定结果
+
+`FAIL` 和 `UNKNOWN` 都应视为未通过。
+
+### 修复报告（self-test-fix-report.md）
+
+- **概览**：失败数 → 确认 bug 数 → 误报数 → 修复成功/失败数
+- **白盒审查结果**：每条失败用例逐一分析，结论为 `confirmed`（代码真有问题）或 `false_positive`（测试误判）
+- **修复计划**：按依赖关系排序的修复列表
+- **修复详情**：每条修复的 Android 参考、根因、具体修改、有效尝试次数、结果
+- **误报说明**：为什么判定为误报，测试 agent 出了什么问题
+- **编译验证**：编译结果及 `hmos-fix-build-errors` 触发的编译修复情况（如有）
+- **所有修改文件汇总**：文件路径、修改类型、关联 Scenario 的汇总表
+
+### 编译阶段
+
+编译阶段的关键结果是：项目是否重新编过、是否成功得到新的 entry HAP、以及下一轮测试使用的包集合是否已从构建输出重新收集完成。
+
+---
+
+## test_case.md 怎么写
+
+完整格式定义见 `hmos-test-case-generation/references/contract.md`（`hmos-test-case-generation` skill 产出的就是该完整格式）。集成测试的解析器只从中提取 `### Scenario` 的 `动作`/`预期结果`，其余字段（`- 前置条件：`、`## 编号映射表`、`- 测试点：` 等）会被忽略——所以你既可以手写完整格式，也可以手写下面的最小子集。
+
+完整格式（`hmos-test-case-generation` 产出，contract.md 节选）：
+
+```markdown
+# 测试套件名
+
+## 编号映射表
+| 功能名称 | SPEC 编号 | REQ 编号 |
+|---------|-----------|----------|
+| 新建歌单 | SPEC-01   | REQ      |
+
+## Scenario List
+
+### Scenario 1-1: 新建歌单输入空白名称点击确定时提示名称不得为空 [P0]
+- 前置条件：
+  - 条件1: 已安装 被测应用 并授予存储权限（AutoTest 自动处理）
+- 动作：打开 被测应用 -> 进入歌单页面 -> 点击「新建歌单」按钮 -> 输入空白名称 -> 点击确定按钮
+- 预期结果：弹出 toast「歌单名称不得为空」，且新建歌单对话框关闭
+- 测试点：
+  - TP-1: 弹出 toast「歌单名称不得为空」
+  - TP-2: 新建歌单对话框关闭
+```
+
+最小手写子集（解析器同样接受，只提取动作/预期结果）：
+
+```markdown
+# 测试套件名
+
+### Scenario: 新建歌单
+- 动作：点击新建歌单按钮
+- 预期结果：弹出新建歌单对话框
+- 动作：输入歌单名称"测试歌单"
+- 预期结果：歌单创建成功，出现在列表顶部
+```
+
+字段说明：
+- `# 标题` → 测试套件名，会出现在报告里
+- `### Scenario N-M:` → 一条用例（`N` = SPEC 号，`M` = 该 SPEC 内流水号；手写子集可省略编号写成 `### Scenario:`）
+- `- 动作：` → 测试操作（多步用 ` -> ` 分隔）
+- `- 预期结果：` → 期望结果（多行用中文逗号连接）
+- `- 前置条件：` / `## 编号映射表` / `- 测试点：` → 仅供人工阅读，解析时忽略
+
+**不需要手动替换应用名**。动作里写的显示名称（如"简单图库"、"Tuku"）系统会自动替换成包名（如 `com.example.tuku`），确保 AutoTest 能正确识别目标应用。
+
+---
+
+## 环境要求
+
+### 基础环境
+
+- 操作系统：**Windows** 是主要测试目标；macOS/Linux 上的核心命令（`hdc`、POSIX 工具链）也能跑，Skill 里涉及到的复制操作会按可用 shell 自适应
+- `hdc` 已安装并在 PATH 中
+- 模型已配置：`ht init` 导出 `HOMETRANS_MODEL_API_KEY` / `HOMETRANS_MODEL_NAME` / `HOMETRANS_MODEL_BASE_URL` 环境变量。集成测试首次运行时，skill 自动从这些环境变量生成 `~/.hometrans/autotest.yaml`（AutoTestAgent 原生格式），后续运行直接读取，不重复生成。用户可手动编辑此文件启用 layered 模式。
+- **layered 多模型模式**（可选）：编辑 `~/.hometrans/autotest.yaml`，将 `agent.mode` 改为 `"layered"`，并添加 `execute` 和 `decision` 模型槽位。此模式下 AutoTest 使用 Planner + Executor 双 Agent 架构。两个槽位都需配置真实的 `name` / `api_key` / `base_url` / `provider`，否则 AutoTestAgent 启动时会报错。
+- 鸿蒙真机或模拟器已连接，`npx --yes devecocli device list` 能看到设备
+- `.hap` 文件（多模块应用：把 entry HAP + 应用内 HSP / feature HAP 一并传入；可以放进一个目录整目录传，也可以用逗号列出多个文件/目录，entry HAP 和 HSP 不在同一目录也行）
+
+### 自动修复附加条件
+
+- `app-metadata.json` 存在（round 1 解析阶段自动产出，内含 `project_root`）
+- 建议项目在 Git 仓库中（不在也可以修复，但不会自动 commit；`commit_id: none`）
+
+---
+
+## 常见问题
+
+**Q: 报 "No HarmonyOS device connected"？**
+
+A: 检查设备/模拟器连接，跑 `npx --yes devecocli device list` 看看有没有设备 SN。真机请重新插拔 USB 并在设备上重新授权 USB 调试；模拟器请确认已启动。
+
+**Q: 报 autotest 配置缺失 或 api_key 没填？**
+
+A: 确认 `ht init` 已完成模型配置（导出 `HOMETRANS_MODEL_API_KEY` 等环境变量）。集成测试首次运行时会自动生成 `autotest.yaml`，如果环境变量缺失会提示先跑 `ht init`。
+
+**Q: 启用 layered 模式后报模型配置不完整？**
+
+A: layered 模式需要 `execute` 和 `decision` 两个模型槽位。编辑 `~/.hometrans/autotest.yaml`，在 `model:` 下添加：
+```yaml
+  execute:
+    name: "gui-plus-2026-02-26"
+    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    api_key: "sk-xxx"
+    provider: "mai-ui"
+  decision:
+    name: "qwen3.7-plus"
+    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    api_key: "sk-xxx"
+    provider: "openai"
+```
+并将 `agent.mode` 改为 `"layered"`。
+
+**Q: 前置用例失败了要不要修代码？**
+
+A: 不用。前置用例是环境准备脚本，失败意味着环境条件不满足（没素材、没权限、引导弹窗等），不影响应用的常规通过率。
+
+**Q: PASS / FAIL / UNKNOWN 有什么区别？**
+
+A: `PASS` — 通过；`FAIL` — 失败/超时/崩溃，有原因说明；`UNKNOWN` — 有报告但无法判定。后面两个都算未通过。
+
+**Q: 测试跑多久？**
+
+A: 每条用例约 6-10 分钟（含 Agent 决策和执行时间）。整体超时上限 = 用例数 × 12 分钟（`--timeout auto` = N×720 秒，CLI 自动从用例数推导），超过后自动终止并产出部分报告。
+
+**Q: 怎么只重跑失败的用例？**
+
+A: 目前每次都跑 `testcases.json` 的全部用例。你可以手动删掉已通过的条目，只保留失败的，然后重跑（round 2+ 会跳过解析阶段，直接读取 `<output-path>/testcases.json`）。
+
+**Q: 产物在哪个目录？**
+
+A: `testcases.json` 和 `app-metadata.json` 在 `output-path/` 根目录。测试和修复的每轮产物在 `output-path/round-1/`、`output-path/round-2/`... 子目录中。循环结束后，最终轮的关键文件（报告、HAP）会镜像到 `output-path/` 根目录，方便直接查看。
+
+**Q: 怎么启用自动修复？**
+
+A: 说"跑自测，自动修复"；或者跑完测试后看到有失败，Skill 会主动问你要不要启用，回复"是"就进去了。默认最多 3 轮，需要更多/更少可以加一句"最多 N 轮"（对应 `max-rounds` 参数）。
+
+**Q: 自动修复会改我的代码吗？**
+
+A: 会修改鸿蒙源码来修 bug，但只在**白盒审查确认是真问题**（`confirmed`）的情况下才会改。误报（`false_positive`）不改，测试用例不改。所有修改会 git commit，可随时 revert。如果不在 Git 仓库中，修改照常进行但不 commit。
+
+**Q: 自动修复一轮多久？**
+
+A: Fix（白盒分析 + 改代码）约 5-10 分钟，Build（编译）约 2-5 分钟，Retest（重新跑用例）约 N×12 分钟。可以随时中断。
+
+**Q: 什么情况下循环会停？**
+
+A: 正常退出 3 种：① 全部通过（`all_passed`）；② 所有失败都是误报，无代码缺陷需要修复（`no_confirmed_defects`）；③ 跑满 `max-rounds` 轮（默认 3）仍有失败（`max_rounds_reached`）。异常退出 3 种：编译未产出 HAP（`no_hap`）；`testcases.json` 为空（`no_testcases`）；自测 agent 早退，写出首行 `status: FAIL` 的 sentinel 报告（`agent_early_exit`，常见原因：设备没连、api_key 没填、batch 崩溃 / 超时）。异常退出不会进入 fix 循环——那些是环境问题，不是代码缺陷。
+
+**Q: 需要提供 Android 项目路径吗？**
+
+A: 不必须。提供了 fixer 会参考 Android 实现来修 bug，质量更高。不提供也能独立完成，基于白盒代码分析和 HarmonyOS API 文档修复。
+
+**Q: 报 "Build did not produce a HAP"？**
+
+A: 通常是编译失败或构建配置有误。检查 `hmos-fix-build-errors` 的编译输出，确认项目能正常构建后继续循环。