Agent-Skills.md

Agent Skills: oh-xts-generator-template

OpenHarmony XTS 测试用例通用生成模板。支持各子系统测试用例生成，API 定义解析，测试覆盖率分析，代码规范检查。触发关键词：XTS、测试生成、用例生成、测试用例。

UncategorizedID: openharmonyinsight/openharmony-skills/oh-xts-generator-template

Repository

openharmonyinsight/openharmony-skills
openharmonyinsight
133

Install this agent skill to your local

pnpm dlx add-skill https://github.com/openharmonyinsight/openharmony-skills/tree/HEAD/skills/oh-xts-generator-template

Skill Files

Browse the full folder contents for oh-xts-generator-template.

Download Skill

Loading file tree…

skills/oh-xts-generator-template/SKILL.md

Skill Metadata

Name
oh-xts-generator-template
Description
OpenHarmony XTS 测试用例通用生成模板。支持各子系统测试用例生成，API 定义解析，测试覆盖率分析，代码规范检查。触发关键词：XTS、测试生成、用例生成、测试用例。

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: 如何使用覆盖率报告驱动模式

参考文档

详细文档

子模块文档

通用配置