oh-xts-generator-template

oh-xts-generator-template

OpenHarmony XTS 测试用例通用生成模板

技能概述

oh-xts-generator-template 是一个通用的 OpenHarmony XTS 测试用例生成模板，采用四层模块化架构，支持各子系统定制化配置。

核心功能

• API 定义解析：解析 .d.ts 文件，提取接口、方法、参数、返回值
• API 语法类型过滤和验证：根据任务类型（动态/静态）过滤 API，验证测试用例使用的 API 是否支持目标语法类型
• 智能测试生成：根据测试策略自动生成符合 XTS 规范的测试用例
• 测试设计文档同步生成：在生成测试用例的同时，同步生成结构化的测试设计文档
• ⚠️ 格式化和验证（强制）：检查语法规范，验证断言方法，确保测试用例质量
• 测试覆盖分析：分析现有测试文件，识别已覆盖和未覆盖的API
• 覆盖率报告驱动生成：直接基于覆盖率报告中的缺失项生成测试用例（高效模式）
• 编译验证支持：提供 Linux/Windows 环境下的编译指南

适用场景

• 为新 API 生成完整的测试套件
• 分析现有测试的覆盖情况
• 各子系统定制化测试生成
• 基于覆盖率报告补充缺失测试（推荐 - 高效精准）

前置配置

OH_ROOT 路径配置（必需）

在使用本技能前，必须在技能目录下的 .oh-xts-config.json 文件中配置 OH_ROOT 路径：

配置文件位置：.opencode/skills/oh-xts-generator-template/.oh-xts-config.json

配置格式：

{
  "OH_ROOT": "/path/to/openharmony/root"
}

配置说明：

• OH_ROOT：OpenHarmony 工程根目录的绝对路径
• 该路径用于读取工程文件、API 声明文件（.d.ts）、测试文件等
• 必须确保路径存在且可访问

⚠️ 重要：使用技能前务必检查该配置是否正确设置，否则技能将无法正常工作。

快速开始

📖 详细使用方式: docs/USAGE.md

三种使用方式概览

方式	适用场景	链接
方式1：通用模板	新手、简单任务	USAGE.md
方式2：子系统配置	大多数任务（推荐）	USAGE.md
方式3：自定义配置	高级用户、特殊需求	USAGE.md

覆盖率报告驱动模式

当用户提供测试覆盖率报告时，系统将自动切换到覆盖率报告驱动模式，此模式具有以下特点：

优势：

• 高效：跳过覆盖率分析步骤，直接基于报告中的缺失项生成用例
• 精准：严格按照覆盖率报告中列出的未覆盖 API、参数组合和场景生成测试
• 快速：显著缩短生成时间，特别是对于大型 API 集合

工作方式：

1. 解析用户提供的覆盖率报告
2. 提取报告中标记的缺失测试项
3. 仅扫描现有测试文件以获取代码风格（不进行覆盖率分析）
4. 直接生成缺失项的测试用例

覆盖率报告格式要求： 报告应包含以下信息：

• 未覆盖的 API 名称
• 缺失的参数组合
• 缺失的测试场景（如边界值、错误码等）
• 测试类型（PARAM、ERROR、RETURN、BOUNDARY）

从覆盖率报告提取错误码的规范：

1. 读取错误码列：例如 "401/17000002/17000007"
2. 从 @throws 标记验证：检查 .d.ts 文件中的 @throws 标记
3. 确定实际的错误码：根据参数类型和触发条件确定具体错误码
4. 生成测试时明确声明：

   - **预期结果**: 抛出错误码 401  # 明确
   - **断言方法**: `expect(e.code).assertEqual(ErrorCode)`  # 正确
   

💡 提示：如果已有覆盖率报告，直接提供报告内容将获得最佳的效率和精准度

API 语法类型过滤（新增）

概述

当任务明确说明是 arkts-dynamic 或 arkts-static 语法任务时，系统会：

1. 自动过滤 API：根据语法类型过滤 API，只生成支持目标语法的测试用例
2. 自动验证：验证生成的测试用例使用的 API 是否支持目标语法类型
3. 防止错误：避免使用不支持目标语法的 API，防止编译错误

工具和文档

工具/文档	路径	说明
API 语法类型检查脚本	scripts/check_syntax_type.js	编译前验证测试用例使用的 API
API 语法类型过滤文档	modules/L2_Analysis/unified_api_parser.md 第十章	API 语法类型过滤详细说明
检查脚本使用指南	scripts/check_syntax_type_usage.md	检查脚本的使用示例和常见问题

使用示例

# 编译前检查 API 语法类型
cd /mnt/data/c00810129/oh_0130/test/xts/acts/testfwk/uitest_errorcode_static/entry/src/main/src/test/

node ~/.opencode/skills/oh-xts-generator-template/scripts/check_syntax_type.js \
  --syntax-type static \
  --test-dir ./

# 检查通过后再编译
if [ $? -eq 0 ]; then
  echo "检查通过，开始编译..."
  ./test/xts/acts/build.sh product_name=rk3568 system_size=standard suite=ActsUiTestErrorCodeStaticTest
fi

核心工作流程

工作流程分支

本技能支持两种工作流程，根据用户输入自动选择：

流程 A：覆盖率报告驱动（当用户提供覆盖率报告时）

1. 确定子系统配置 - 加载核心配置和子系统差异化配置 ├─ 检查是否存在子系统配置文件 ├─ 加载通用配置 (_common.md) ├─ 加载子系统配置 ({Subsystem}/_common.md) └─ 加载模块配置 ({Subsystem}/{Module}.md)（如需）
2. 解析覆盖率报告 - 从用户提供的覆盖率报告中提取缺失测试项 ├─ 识别未覆盖的 API 和参数组合 ├─ 提取缺失的测试场景 └─ 分析需补充的测试类型（PARAM、ERROR、RETURN、BOUNDARY）
3. API 信息解析 - 解析 .d.ts 文件，提取缺失测试项的接口、方法、参数信息 ├─ 读取 API 声明文件 (.d.ts) ├─ 查找并解析 API 文档 └─ 综合分析
4. 扫描代码风格 - 快速扫描现有测试文件，仅提取代码风格（跳过覆盖率分析） └─ [使用 analysis-agent subagent - 仅代码风格模式]
5. 生成测试用例和测试设计文档 - 基于覆盖率报告的缺失项，同时生成测试用例和测试设计文档 ├─ 应用子系统特有规则 ├─ 使用子系统特有模板 ├─ 应用已有用例的代码风格 ├─ 严格遵循 API 声明文件中的接口定义 ├─ 在生成每个测试用例的同时，同步输出对应的测试设计文档条目 └─ 最后统一输出完整的测试设计文档文件
6. 注册测试套 - 在 List.test.ets 中注册新增测试文件（如需） ├─ 添加 import 语句 └─ 在 testsuite() 函数中调用
7. ⚠️ 格式化和验证（强制步骤） - 检查语法规范，验证断言方法，确保测试用例质量 ├─ 完成条件：所有语法错误已修复，断言方法正确，代码符合规范 ├─ 检查项： │ ├─ ArkTS 语法规范性（动态/静态） │ ├─ @tc 注释块完整性 │ ├─ hypium 导入语句正确性 │ ├─ 测试用例命名规范 │ └─ 断言方法正确性 └─ [使用 validation-agent subagent] ├─ 生成动态 XTS 用例时遵循动态语法规范，详细指南：# ArkTS动态语法检查规则全集 └─ 生成静态 XTS 用例时遵循静态语法规范，需要调用专门的 arkts-static-spec 技能进行语法规范校验： ├─ 使用方式：请使用 arkts-static-spec 进行语法规范校验 └─ 详细指南：ArkTS 静态语言语法规范指南
8. 编译验证（重要） ├─ 检测运行环境（Linux/Windows） ├─ 根据环境选择编译方案 ├─ Linux 环境：使用 subagent 执行编译，监听进程，自动修复语法错误 ├─ Windows 环境：根据关键词自动选择动态或静态编译模式 └─ 详细编译流程：参见注意事项第7条"编译环境检测"
9. 输出更新文件列表、测试设计文档和覆盖率对比

流程 B：标准流程（用户未提供覆盖率报告时）

1. 确定子系统配置 - 加载核心配置和子系统差异化配置 ├─ 检查是否存在子系统配置文件 ├─ 加载通用配置 (_common.md) ├─ 加载子系统配置 ({Subsystem}/_common.md) └─ 加载模块配置 ({Subsystem}/{Module}.md)（如需）
2. API 信息解析 - 解析 .d.ts 文件，提取接口、方法、参数信息 ├─ 读取 API 声明文件 (.d.ts) ├─ 查找并解析 API 文档 └─ 综合分析
3. 测试覆盖分析 - 扫描现有测试文件，分析代码风格和覆盖率 └─ [使用 analysis-agent subagent]
4. 生成测试用例和测试设计文档 - 应用子系统特有规则，同时生成测试用例和测试设计文档 ├─ 应用子系统特有规则 ├─ 使用子系统特有模板 ├─ 应用已有用例的代码风格 ├─ 严格遵循 API 声明文件中的接口定义 ├─ 在生成每个测试用例的同时，同步输出对应的测试设计文档条目 └─ 最后统一输出完整的测试设计文档文件
5. 注册测试套 - 在 List.test.ets 中注册新增测试文件（如需） ├─ 添加 import 语句 └─ 在 testsuite() 函数中调用
6. ⚠️ 格式化和验证（强制步骤） - 检查语法规范，验证断言方法，确保测试用例质量 ├─ 完成条件：所有语法错误已修复，断言方法正确，代码符合规范 ├─ 检查项： │ ├─ ArkTS 语法规范性（动态/静态） │ ├─ @tc 注释块完整性 │ ├─ hypium 导入语句正确性 │ ├─ 测试用例命名规范 │ └─ 断言方法正确性 └─ [使用 validation-agent subagent] ├─ 生成动态 XTS 用例时遵循动态语法规范，详细指南：# ArkTS动态语法检查规则全集 └─ 生成静态 XTS 用例时遵循静态语法规范，需要调用专门的 arkts-static-spec 技能进行语法规范校验： ├─ 使用方式：请使用 arkts-static-spec 进行语法规范校验 └─ 详细指南：ArkTS 静态语言语法规范指南
7. 编译验证（重要） ├─ 检测运行环境（Linux/Windows） ├─ 根据环境选择编译方案 ├─ Linux 环境：使用 subagent 执行编译，监听进程，自动修复语法错误 ├─ Windows 环境：根据关键词自动选择动态或静态编译模式 └─ 详细编译流程：参见注意事项第7条"编译环境检测"
8. 输出更新文件列表、测试设计文档和覆盖率对比

配置扩展

配置文件查找路径：

.opencode/skills/oh-xts-generator-template/references/subsystems/

支持的子系统：

• testfwk - 测试框架
• storage - 存储管理
• multimedia - 多媒体
• arkts - ArkTS 语言特性
• 其他自定义子系统

📖 详细配置说明: docs/CONFIG.md

配置优先级

用户自定义配置 > 模块配置 > 子系统配置 > 核心配置

配置架构说明 ⭐ 重要

配置设计原则：核心配置 + 最小化差异化

配置层级说明

层级	文件	说明
核心配置	references/subsystems/_common.md	核心强制规范 + 默认规范 + 扩展接口
子系统配置	references/subsystems/{Subsystem}/_common.md	基础信息 + 子系统差异化配置 + 特殊规则
模块配置	references/subsystems/{Subsystem}/{Module}.md	基础信息 + 子系统差异化配置 + 模块差异化配置 + 特殊规则
用户自定义配置	用户提供的配置	覆盖子系统配置和核心配置

输出规范

测试用例编号(@tc.number)

格式：SUB_[子系统]_[模块]_[API]_[类型]_[序号]，类型包括 PARAM、ERROR、RETURN、BOUNDARY

测试设计文档规范

• 文件命名：{测试文件名}.design.md

重要注意事项

1. ⚠️ 格式化和验证步骤（强制 - 不可跳过）

重要提示：格式化和验证是测试用例生成的核心强制步骤，绝不可跳过！

为什么此步骤不可跳过？

• ✅ 确保生成的测试用例符合 XTS 规范
• ✅ 避免编译阶段才发现语法错误
• ✅ 保证测试用例质量和可维护性
• ✅ 提高测试执行成功率

完成条件检查清单：

• 所有语法错误已修复
• @tc 注释块完整且格式正确
• hypium 导入语句正确
• 测试用例命名符合规范（小驼峰）
• 断言方法使用正确
• ArkTS 语法符合规范（动态/静态）

常见问题：

• ❌ 直接跳到编译步骤（编译不会捕获所有问题）
• ❌ 认为此步骤是可选的
• ❌ 忽略验证结果中的警告
• ❌ 不完整执行 validation-agent 检查

2. @tc 注释块规范（强制）

所有测试用例必须添加标准的 @tc 注释块，包括 name、number、desc 等字段。详见：测试框架规范

3. hypium 导入规范（强制）

详见：Hypium 测试框架基础 - 导入语句规范

4. 工程文件修改限制（强制）

严格禁止修改工程目录中的配置文件，只能在指定测试目录创建测试文件

5. API 声明严格遵循（强制）

必须严格按照 .d.ts 文件声明的接口生成测试用例，禁止使用未声明的接口

6. 编译相关

• Linux 环境必须使用 ./test/xts/acts/build.sh 脚本编译
• 编译前确认 BUILD.gn 中的编译目标

环境	推荐方式	入口文档
Linux	./test/xts/acts/build.sh 脚本	Linux 编译工作流
Windows	DevEco Studio IDE	Windows 编译工作流

5.1 Linux 环境编译

基础要求：

• 使用 ./test/xts/acts/build.sh 脚本编译，不要使用 hvigorw
• 环境检测：uname -s

编译流程：

1. 预编译清理（强制）：

   • 使用 ~/.opencode/skills/oh-xts-generator-template/scripts/cleanup_group.sh 脚本
   • 清理目的：确保编译结果包含所有最新代码
   • ⚠️ 安全注意事项：见第 3.1 节清理操作安全说明

2. 静态测试套预置条件（编译静态套时）：

   • 校验 hvigor 版本："6.0.0-arkts1.2-ohosTest-25072102"
   • 版本匹配：跳过工具替换；版本不匹配：执行替换流程
   • 工具替换：清理 SDK 缓存 → 清理旧工具 → 下载新工具 → 移动到预置目录

3. 编译执行：

   • 使用 general subagent 执行（避免主流程中断）
   • 监听编译进程直至完成
   • 语法错误：自动分析并修复，重试编译
   • 配置错误：暂停并向用户确认后才修改

5.2 Windows 环境编译

根据关键词自动选择编译模式：

7.2.1 ArkTS 动态 XTS 编译（默认）

• 编译方式：DevEco Studio IDE 或 hvigorw.bat
• 编译目标：Build → Build OhosTest Hap(s)
• 参考文档：modules/L4_Build/build_workflow_windows.md 第三章

7.2.2 ArkTS 静态 XTS 编译（arkts-sta）

• 适用场景：基于 ArkTS 静态强类型语法的 XTS 测试 工程
• 触发关键词：当用户提到以下任一关键词时自动启用：
  • 技术术语：arkts-sta、ArkTS静态、arkts static、ArkTS static
  • 通用表述：静态xts、静态 XTS、static arkts、static xts
  • 操作描述：编译静态、静态编译、静态工程编译、Windows静态编译
• 编译方式：PowerShell 脚本或 hvigorw.bat 命令行工具
• Java 环境：必需配置 JAVA_HOME 环境变量
• 编译特点：
  • 严格的静态类型检查
  • 所有类型必须有显式注解
  • 禁止使用 any 类型
  • 所有字段必须初始化
  • 类型强校验：入参类型不匹配时直接编译报错，不会运行时抛出401错误码
  • 编译时类型验证：所有类型错误在编译阶段暴露，提高代码质量
  • 无运行时类型异常：消除了因类型错误导致的运行时崩溃
• 类型校验策略：
  • 编译器检查所有类型注解的正确性
  • 函数参数类型必须与声明完全匹配
  • 返回值类型必须与声明一致
  • 泛型类型参数必须在编译时确定
• 参考文档：modules/L4_Build/build_workflow_windows.md 第十章

⚠️ 重要提示：

• 默认使用动态编译模式
• 仅在用户明确提到静态相关关键词时启用静态编译模式
• 静态编译需要配置 Java 环境变量（JAVA_HOME）

📖 详细的编译文档: modules/L4_Build/

故障排除

📖 详细故障排除指南: docs/TROUBLESHOOTING.md

常见问题：

• Q1: 生成的测试用例无法编译
• Q2: 测试用例命名不符合规范
• Q3: 测试设计文档与测试用例不一致
• Q4: Linux 环境编译失败
• Q5: 测试用例执行失败
• Q6: 子系统配置文件未找到
• Q7: 测试覆盖率分析不准确
• Q8: ArkTS 静态语法校验问题
• Q9: 如何调用 arkts-static-spec 技能
• Q10: 如何使用覆盖率报告驱动模式

参考文档

详细文档

• 配置扩展机制: docs/CONFIG.md
• 使用方式详解: docs/USAGE.md
• 故障排除: docs/TROUBLESHOOTING.md

子模块文档

• L1_Framework: modules/L1_Framework/
• L2_Analysis: modules/L2_Analysis/
• L3_Generation: modules/L3_Generation/
• L4_Build: modules/L4_Build/

通用配置

• 通用配置: references/subsystems/_common.md