@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-xts-doc/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: arkts-library-xts-doc
+description: 基于XTS覆盖率报告，为未覆盖接口自动判断可测试性并生成XTS用例描述文档。仅生成纯函数（无UI操作、可通过执行结果验证）的XTS用例描述，包含用例序号、名称、描述、预期结果、对应函数接口。当需要对鸿蒙原生库进行XTS覆盖率缺口填补、未覆盖接口测试规划时调用。
+license: Apache-2.0
+compatibility: 需要XTS覆盖率报告（由ArkTsLibraryXTSCoverageSkill生成），需要文件写入权限到输出目录
+metadata:
+  version: "1.0.0"
+  category: ohos-testing
+  language: ArkTS/ETS
+---
+
+# 鸿蒙ArkTs原生库未覆盖接口XTS用例生成
+
+读取XTS覆盖率报告中的未覆盖接口清单，自动判断接口可测试性，为可测试接口生成标准化XTS用例描述文档，100%覆盖所有未覆盖的可测试接口。
+
+> ⚠️ **核心约束**：
+> 1. 仅生成纯函数的XTS用例描述，不生成需要UI操作、无法通过执行结果验证的用例
+> 2. 所有用例内容基于覆盖率报告中真实存在的接口签名和功能描述，严禁捏造
+> 3. 100%覆盖所有未覆盖的可测试接口
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `xtsCoverageReportPath` | string | ✅ | XTS覆盖率报告绝对路径（由ArkTsLibraryXTSCoverageSkill生成，含未覆盖接口清单及签名） |
+| `outputDir` | string | ❌ | 输出目录，默认放置在覆盖率报告所在目录 |
+
+### 输入异常处理
+
+| 异常情况 | 处理方式 |
+|---------|---------|
+| 覆盖率报告不存在或无法读取 | 停止执行，向用户提示错误 |
+| 未覆盖接口清单为空（覆盖率100%） | 生成空文档，标注"所有接口已覆盖，无需补充" |
+| 无法确定库名称 | 使用默认命名 `Unknown未覆盖接口XTS用例描述.md` |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: `arkts-library-xts-coverage`（生成XTS覆盖率报告）
+- **输入文件**: XTS覆盖率报告（`.md`格式，含未覆盖接口清单及签名）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 读取覆盖率报告并提取未覆盖接口
+    ↓
+Phase 2: 接口可测试性判断
+    ↓
+Phase 3: XTS用例规划（正向+空值+异常+大数据）
+    ↓
+Phase 4: 生成XTS用例描述文档
+    ↓
+Phase 5: 文档验证与输出
+```
+
+---
+
+## Phase 1：读取覆盖率报告并提取未覆盖接口
+
+### 1.1 读取覆盖率报告
+
+1. 使用 `read_file` 读取 `xtsCoverageReportPath` 全文
+2. 提取库名称（用于输出文件命名）
+3. 提取当前XTS覆盖率（用于概述中标注补充前后对比）
+
+### 1.2 提取未覆盖接口清单
+
+定位覆盖率报告「未覆盖接口清单」章节，提取每个未覆盖接口：
+
+| 提取字段 | 来源列 | 用途 |
+|---------|--------|------|
+| 接口名称 | `方法/属性` 列 | 用例命名 |
+| 完整签名 | `签名` 列 | 用例预期结果中标注精确调用方式 |
+| 接口类型 | `类型` 列 | 可测试性判断依据 |
+| 功能描述 | `功能描述` 列 | 用例描述的依据 |
+| 所属类 | `### {ClassName}` 子标题 | 分组依据 |
+
+> 覆盖率报告的未覆盖清单用于**索引**（确定要补充的接口及分组）；报告中字段不完整或与规格不一致时，**精确参数类型/返回类型/枚举值一律以 `interface-spec.json` 为权威来源补全**，不得凭报告文本猜测或按函数名推断签名。
+
+---
+
+## Phase 2：接口可测试性判断
+
+### 2.1 判断标准（摘要）
+
+- **✅ 可测试**：纯函数、无UI操作、结果可验证、无不可控外部依赖
+- **❌ 不可测试**：涉及UI操作、依赖不可控外部因素、结果不可验证、纯展示型、`private`/`protected` 成员、`public static readonly` 常量
+- **⚠️ 需额外条件**：依赖Mock/异步等待/前置状态的接口，可测但需在用例中标注前提条件
+
+> 完整判断标准、接口类型测试规则、分类示例参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md)
+
+### 2.2 接口分类标记
+
+对每个未覆盖接口进行分类标记：`✅ 可测试`、`❌ 不可测试`、`⚠️ 可测试（需额外条件）`。
+
+对于 `⚠️ 可测试（需额外条件）` 的接口，在用例描述中注明测试前提条件（如需要Mock网络请求）。
+
+---
+
+## Phase 3：XTS用例规划
+
+### 3.1 设计原则（摘要）
+
+- 每个可测试接口至少有1个**正向用例**
+- 每个可测试接口至少有1个**空值/null输入用例**
+- 每个可测试接口至少有1个**异常/边界值用例**
+- 集合类型参数接口至少有1个**大数据量用例**
+- 一个用例可包含多个关联接口（展示协同使用方式）
+
+### 3.2 多接口用例设计
+
+将多个接口放在同一用例中的条件：
+- 接口之间存在调用依赖关系（如 `init` → `execute` → `getResult`）
+- 接口协同完成一个完整功能流程（如 `create` → `configure` → `start`）
+- 接口之间存在状态变化关系（如 `setConfig` → `getConfig` 验证）
+
+### 3.3 跨接口综合场景设计
+
+正向/空值/异常/大数据之外，还应设计四类**跨接口综合场景**：
+1. **空值/异常边界综合**：将多个接口的空值、异常、边界输入组合进同一用例，验证错误处理的一致性
+2. **大数据综合**：对集合/字符串类接口的数据处理链路（输入→处理→输出）组合验证
+3. **端到端流程综合**：串联存在调用依赖的接口，模拟真实业务流程（初始化→配置→调用→清理）
+4. **状态机综合**：对存在状态流转的接口按状态顺序验证（未初始化→初始化→运行→停止→销毁）
+
+综合场景优先复用 3.2 中已建立关联的接口组，避免为每个接口单独堆叠低价值用例。
+
+### 3.4 用例编号规则
+
+- 用例序号采用三位补零格式：`001`、`002`、`003`...
+- 序号按模块分组递增，便于管理
+
+> 详细的场景设计规范（空值、异常、大数据、Mock、异步等待）参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md) 和 [用例模板与编写规范](references/TEMPLATE.md)
+
+### 3.5 用例计数约束调和
+
+当下游存在「用例场景数 ≥ 接口覆盖数」的计数约束（即报告要求 `用例数 ≥ 已覆盖接口数`）时：
+- **setter/getter 配对接口不合并为单用例**（每个接口各计 1 条用例），以保证接口数与用例数匹配
+- 或通过 **3.3 跨接口综合场景**补足差额（综合场景一条用例计 1，便于补齐接口数）
+- 若接口数明显大于用例场景容量，优先拆分多接口用例，保证每接口至少 1 条用例
+
+---
+
+## Phase 4：生成XTS用例描述文档
+
+### 4.1 文档结构
+
+生成的文档包含以下章节：
+
+1. **概述** — 库名称、生成时间、覆盖率前后对比、用例统计
+2. **接口可测试性分析** — 可测试/不可测试/需额外条件接口列表
+3. **用例索引表** — 全部用例的序号、名称、涉及接口、模块归属
+4. **XTS用例详细描述** — 每个用例的描述、预期结果、对应函数接口
+
+### 4.2 文件命名与存放
+
+```
+文件命名规则：{库名}未覆盖接口XTS用例描述.md
+存放位置：覆盖率报告所在目录（或指定 outputDir）
+```
+
+> 完整文档模板参见 [用例模板与编写规范](references/TEMPLATE.md)
+
+---
+
+## Phase 5：文档验证与输出
+
+### 5.1 验证检查项
+
+1. **内容真实性**：所有接口签名、功能描述与覆盖率报告严格一致；报告中签名不完整或可疑时，对照 `interface-spec.json` 校验
+2. **可测试性判断准确性**：不可测试接口未生成用例
+3. **预期输出可验证性**：每个用例的预期输出具体、可验证
+4. **接口关联合理性**：多接口用例的接口间存在明确关联关系
+5. **签名补全校验**：涉及参数类型、返回类型（含 `| null`/`undefined` 联合）、枚举值时，均已按 `interface-spec.json` 的权威签名补全，无沿用报告缺省/简略签名的用例
+
+### 5.2 输出确认
+
+- 文档末尾标注 `状态: 成功` 或 `状态: 失败`
+- 确认可测试接口覆盖率达到100%
+- 每个用例预期结果必须具体、可验证
+
+---
+
+## 参考资料
+
+- [可测试性判断指南](references/TESTABILITY_GUIDE.md) — 可测试性判断标准、接口类型测试规则、用例设计原则、空值/异常/大数据场景设计规范
+- [用例模板与编写规范](references/TEMPLATE.md) — 文档整体模板、各类用例模板（正向/多接口/反向/空值）、六段式用例结构规范
+- [完整生成示例](references/EXAMPLES.md) — 基于lodash的完整XTS用例描述生成示例
+
+> **接口签名权威来源**：`interface-spec.json` 的 `signature` 字段可能与同对象的 `returnType` 分叉（历史遗留）。二者冲突时以 `returnType` + `params` 为准（`returnType` 完整保留 `| null` / `undefined` 等联合类型细节）。