oh-xts-generator-template

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

技能概述

oh-xts-generator-template 是一个通用的 OpenHarmony XTS 测试用例生成模板，设计为可配置、可扩展的通用框架，适用于各个子系统的测试用例生成。

核心特性

1. 通用测试生成流程 – 提供完整的测试用例生成工作流
2. 模块化架构 – 三层模块化设计（L1/L2/L3），按需加载
3. 分层配置系统 – 通用配置 + 子系统特有配置
4. 灵活扩展机制 – 支持各子系统添加特有配置和模板

核心功能

适用场景

• ✅ 为新 API 生成完整的测试套件
• ✅ 分析现有测试的覆盖情况
• ✅ 补充缺失的测试用例
• ✅ 验证测试代码规范性
• ✅ 各子系统定制化测试生成

快速开始

方式1：使用通用模板（推荐新手）

请使用 oh-xts-generator-template 为以下 API 生成测试用例：

子系统: ArkUI
API: Component.onClick()
定义文件: interface/sdk-js/api/@ohos.arkui.d.ts

方式2：使用子系统配置（推荐）

请使用 oh-xts-generator-template 为 ArkUI 子系统生成测试用例：

子系统: ArkUI
配置文件: references/subsystems/ArkUI/_common.md
API: Component.onClick()

方式3：自定义配置

请使用 oh-xts-generator-template 生成测试用例，使用自定义配置：

子系统: MySubsystem
自定义配置:
  Kit包: @kit.MyKit
  测试路径: test/xts/acts/mysubsystem/
  API声明: interface/sdk-js/api/@ohos.mysubsystem.d.ts

API: myAPI.method()

核心工作流程

1. 确定子系统配置
   ├─ 检查是否存在子系统配置文件
   ├─ 加载通用配置 (_common.md)
   └─ 加载子系统配置 ({Subsystem}/_common.md)

2. 解析 API 定义 (.d.ts + 文档)
   ├─ 读取 API 声明文件 (.d.ts)
   ├─ 查找并解析 API 文档
   └─ 综合分析

3. 参考已有用例（强制）
   ├─ 扫描指定路径的已有测试文件
   ├─ 分析代码风格和规范
   └─ 提取共性模式

4. 分析现有测试（可选）
   ├─ 扫描测试文件
   ├─ 识别已覆盖的API
   └─ 计算测试覆盖率

5. 生成测试用例
   ├─ 应用子系统特有规则
   ├─ 使用子系统特有模板
   └─ 应用已有用例的代码风格

6. 添加 @tc 注释块（强制）
   ├─ @tc.name：小驼峰命名，与 it() 参数一致
   ├─ @tc.number：{describe名}_{序号}
   ├─ @tc.desc：{API名} {错误码} test.
   └─ 验证字段值与 it() 参数的一致性

7. 检查 hypium 导入（强制）
   ├─ 基本导入：describe, it, expect
   ├─ 类型导入：TestType, Level, Size
   └─ 条件导入：beforeAll, afterAll, beforeEach, afterEach（根据需要）

8. 格式化和验证
   ├─ 应用代码模板
   ├─ 检查语法规范
   └─ 验证断言方法

9. 注册测试套（新增文件时必须）
   ├─ 查找 List.test.ets 文件
   ├─ 添加 import 语句
   └─ 在 testsuite() 函数中调用

10. 编译验证（重要）
    ├─ 检测运行环境（Linux/Windows）
    ├─ 根据环境选择编译方案
    └─ 处理编译错误

11. 输出更新文件列表和覆盖率对比

📖 详细的工作流程说明请查看: docs/ARCHITECTURE.md

配置扩展

配置优先级

用户自定义配置 > 子系统配置 > 通用配置

配置文件组织

references/subsystems/
├── _common.md           # 全局通用配置
├── {Subsystem}/        # 子系统文件夹
│   ├── _common.md       # 子系统通用配置
│   └── {Module}.md      # 模块配置

📖 详细的配置说明请查看: docs/CONFIG.md

输出规范

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

格式: SUB_[子系统]_[模块]_[API]_[类型]_[序号]

类型标识：
- PARAM    参数测试
- ERROR    错误码测试
- RETURN   返回值测试
- BOUNDARY 边界值测试

任务完成输出

每次完成任务后，必须输出：

## 任务完成摘要

### 新增文件
- `path/to/file1.ets` - 文件说明

### 修改文件
- `path/to/file2.ets` - 修改说明

### 测试覆盖统计
- 新增测试用例数：XX 个
- 覆盖的 API：XX 个

📖 完整的使用方式请查看: docs/USAGE.md

重要注意事项

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

• 所有测试用例（it() 函数）必须在前面添加标准的 @tc 注释块
• @tc.name：必须使用小驼峰命名（camelCase），必须与 it() 第一个参数完全一致
• @tc.number：格式为 {describe名}_{序号}，序号从001开始补零对齐
• @tc.desc：格式为 {API名} {错误码/场景} test.，必须以 . 结尾
• @tc.type、@tc.size、@tc.level：必须与 it() 第二个参数中的值一致

2. hypium 导入规范（强制）

• 基本导入：describe, it, expect（必需）
• 类型导入：TestType, Level, Size（必需）
• 条件导入：beforeAll, afterAll（根据代码需要）
• 自动检测并补充缺失的导入

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

• 严格禁止修改工程目录中的配置文件
• 仅允许修改：entry/src/ohosTest/ets/test/ 目录中的测试文件
• 违反限制的后果：可能导致工程结构被破坏、编译失败

4. XTS Wiki 文档参考（强制）

• 生成 XTS 测试用例时，必须参考 Wiki 文档中的规范
• Wiki 文档规范 > Template 配置 > 通用模板

5. ArkTS 语法类型识别（重要）

• API 类型判断：必须读取 .d.ts 文件中最后一段 JSDOC 的 @since 标签
• 工程类型识别：读取 build-profile.json5 检查 arkTSVersion 字段
• 兼容性检查：生成测试用例前，必须检查工程语法类型与 API 类型是否匹配

6. 编译环境检测（强制）

• Linux 环境：必须使用 build.sh 脚本编译，不要使用 hvigorw
• Windows 环境：使用 DevEco Studio 或 hvigorw.bat
• 环境检测方法：uname -s（Linux）或 $env:OS（Windows）

编译模块化架构（v2.0.0+）：

• 主工作流：modules/L2_Analysis/build_workflow_linux.md（365 行）
• 环境准备：modules/L2_Analysis/linux_compile_env_setup.md（按需加载）
• 预编译清理：modules/L2_Analysis/linux_prebuild_cleanup.md（按需加载）
• BUILD.gn 配置：modules/L2_Analysis/build_gn_config.md（按需加载）
• 问题排查：modules/L2_Analysis/linux_compile_troubleshooting.md（按需加载）

📖 完整的注意事项请查看: references/subsystems/_common.md 第七章和第八章

版本信息

• 当前版本: 1.12.0
• 创建日期: 2025-01-31
• 最后更新: 2026-02-06
• 兼容性: OpenHarmony API 10+
• 基于: OH_XTS_GENERATOR v1.7.0

v1.12.0 更新内容（2026-02-06）

编译工作流模块化重构：

• Linux 编译工作流升级到 v2.0.0：大规模模块化拆分
  • 拆分为 5 个独立模块（主文件 + 4 个功能模块）
  • 主文件大小减少 49%（716 行 → 365 行）
  • 新增工作流程图和快速参考表
  • 提高可维护性和用户体验
• 新增编译模块：
  • linux_compile_env_setup.md – 编译环境准备（476 行）
  • linux_prebuild_cleanup.md – 预编译清理指南（278 行）
  • build_gn_config.md – BUILD.gn 配置指南（521 行）
  • linux_compile_troubleshooting.md – 编译问题排查指南（418 行）
• 按需加载机制：根据用户需求动态加载相应模块
• 完整的模块文档：每个模块都有完整的说明和使用指南

📖 详细的版本更新记录请查看: CHANGELOG.md

参考文档

详细文档

• 模块化架构详解: docs/ARCHITECTURE.md
• 配置扩展机制: docs/CONFIG.md
• 使用方式详解: docs/USAGE.md

子模块文档

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

通用配置

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