oh-xts-generator-template

SkillDev tools

General template for generating OpenHarmony XTS test cases. Supports test case generation for all subsystems, API definition parsing, test coverage analysis, and code style checks. Trigger keywords: XTS, test generation, use case generation, test cases.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the oh-xts-generator-template skill

What this skill tells your AI

The instructions your AI receives, as published by openharmonyinsight/openharmony-skills in skills/oh-xts-generator-template/SKILL.md and read by ahel’s review.

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 集合

工作方式：

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

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

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

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

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

生成测试时明确声明：

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

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

API 语法类型过滤（新增）

概述

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

自动过滤 API：根据语法类型过滤 API，只生成支持目标语法的测试用例
自动验证：验证生成的测试用例使用的 API 是否支持目标语法类型
防止错误：避免使用不支持目标语法的 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：覆盖率报告驱动（当用户提供覆盖率报告时）

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

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

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

配置扩展

配置文件查找路径：

.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

编译流程：

预编译清理（强制）：
- 使用 ~/.opencode/skills/oh-xts-generator-template/scripts/cleanup_group.sh 脚本
- 清理目的：确保编译结果包含所有最新代码
- ⚠️ 安全注意事项：见第 3.1 节清理操作安全说明
静态测试套预置条件（编译静态套时）：
- 校验 hvigor 版本："6.0.0-arkts1.2-ohosTest-25072102"
- 版本匹配：跳过工具替换；版本不匹配：执行替换流程
- 工具替换：清理 SDK 缓存 → 清理旧工具 → 下载新工具 → 移动到预置目录
编译执行：
- 使用 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