oh-capi-xts-gen

oh-capi-xts-gen

OpenHarmony CAPI XTS 测试用例生成器 — 方式 2（N-API 封装测试）

架构概览

用户输入(.h) → L1_Analysis（解析头文件）→ L2_Generation（生成N-API封装+ETS测试）→ L3_Validation（三重校验+编译）→ 输出
                ↑                              ↑
          references/subsystems/        modules/conventions/（测试框架规范）

快速文件索引

我要做什么	看哪个文件
解析 .h 头文件	modules/L1_Analysis/parser/unified_api_parser_c.md
读取文档	modules/L1_Analysis/parser/doc_reader.md
解析工程配置	modules/L1_Analysis/parser/project_parser.md
分析覆盖率	modules/L1_Analysis/analyzer/coverage_analyzer.md
生成 C++ N-API 封装	modules/L2_Generation/generator/test_generation_c.md
N-API 基础模式	modules/L2_Generation/generator/test_patterns_napi_ets.md
N-API 高级模式	modules/L2_Generation/generator/test_patterns_napi_ets_advance.md
N-API API 参考	modules/L2_Generation/generator/napi_api_reference.md
工程配置模板	modules/L2_Generation/generator/project_config_templates.md
测试套结构检查	modules/L2_Generation/generator/test_suite_structure_checklist.md
三重校验	modules/L2_Generation/generator/verification_common.md
编译测试套	modules/L3_Validation/builder/build_workflow_c.md
编译环境配置	modules/L3_Validation/builder/linux_compile_env_setup_c.md
Linux 编译流程	modules/L3_Validation/builder/linux_compile_workflow_c.md
提取测试套名称	modules/L3_Validation/builder/quick_reference_extract_suite_name.md

前置条件

读取 OH_ROOT 路径：.opencode/skills/oh-capi-xts-gen/.oh-capi-xts-config.json

CAPI 头文件路径：{OH_ROOT}/interface/sdk_c/

通用约束

1. 严格按照 .h 头文件声明的接口生成 N-API 封装和测试用例
2. 每个测试用例必须包含标准 @tc 注释块
3. hypium 导入语句必须符合规范
4. 测试用例命名使用小驼峰 camelCase
5. 禁止修改工程目录中的非测试文件
6. N-API 三重校验步骤不可跳过

测试用例命名格式

SUB_[Subsystem]_[Module]_[API]_[Type]_[Sequence]

类型：PARAM / ERROR / RETURN / BOUNDARY / MEMORY

示例：SUB_HIVIEWDFX_HILOG_OH_LOG_Print_PARAM_001、SUB_BUNDLEMANAGER_BUNDLE_OH_NativeBundle_GetMetadata_RETURN_001

生成架构

C API (.h) → N-API 封装 (C++) → JS 接口 (index.d.ts) → ETS/ArkTS 测试 (.test.ets)

工作流

分支选择

分支	触发条件	阶段 3	生成目标
Flow A	用户提供覆盖率报告（触发词：覆盖率报告、补充测试、缺失测试）	仅扫描风格 — 从现有测试中提取代码风格，不重新分析覆盖率	补充已有工程 — 根据覆盖率报告仅生成缺失的测试，不创建新工程
Flow B	未提供覆盖率报告（默认）	全面分析覆盖率 — 扫描所有现有测试，分析方法／参数／错误码覆盖率，并生成缺口报告	优先补充已有工程 > 创建新工程（必须从 template_project/capi_test_template/ 复制）

Flow A：基于覆盖率报告

Phase 1 (Config) → Phase 2 (Header Parse) → Phase 3 (Style Scan Only) → Phase 4 (Generate) → Phase 5 (Verify) → Phase 6 (Build) → Phase 7 (Output)

1. 解析覆盖率报告，提取缺失的测试项
2. 仅扫描现有测试文件以了解代码风格（命名模式、注释风格、测试结构）
3. 直接根据报告中的缺失项生成测试（不要重新分析现有覆盖率）
4. 在现有工程中补充测试，不创建新工程

Flow B：标准流程（默认）

Phase 1 (Config) → Phase 2 (Header Parse) → Phase 3 (Full Coverage) → Phase 4 (Generate) → Phase 5 (Verify) → Phase 6 (Build) → Phase 7 (Output)

Flow B 在阶段 3 进行全面覆盖率分析（扫描所有现有测试文件并生成缺口报告）。如果已有覆盖率报告，Flow A 仅扫描风格。

阶段详情

阶段	名称	关键模块	必需
1	确定子系统配置	references/subsystems/_common.md + 子系统配置	是
2	头文件解析	modules/L1_Analysis/parser/unified_api_parser_c.md	是
3	覆盖率分析 / 风格扫描	modules/L1_Analysis/analyzer/coverage_analyzer.md	是
4	生成测试用例	modules/L2_Generation/generator/test_generation_c.md + test_patterns_napi_ets.md	是
5	N-API 三重校验	modules/L2_Generation/generator/verification_common.md	必需 — 绝不跳过
6	构建验证	modules/L3_Validation/builder/build_workflow_c.md	建议
7	输出结果	—	是

阶段 1 配置加载顺序：Core → Subsystem → Module（优先级：用户自定义 > 模块配置 > 子系统配置 > Core 配置）

阶段 2 信息来源优先级：.h 头文件（最高）→ 子系统配置 → 参考示例

阶段 4 生成的产物：

产物	路径
C++ N-API 包装器	entry/src/main/cpp/NapiTest.cpp
TypeScript 声明	entry/src/main/cpp/types/libentry/index.d.ts
ETS 测试用例	entry/src/ohosTest/ets/test/*.test.ets
构建配置	BUILD.gn、Test.json 等

模块加载（引用注入映射）

根据触发的使用模式加载模块。仅加载当前阶段所需的模块。

阶段	始终加载	有条件加载
1	references/subsystems/_common.md	references/subsystems/{Subsystem}/_common.md、{Module}.md
2	modules/L1_Analysis/parser/unified_api_parser_c.md	modules/L1_Analysis/parser/doc_reader.md、modules/L1_Analysis/parser/project_parser.md
3	modules/L1_Analysis/analyzer/coverage_analyzer.md	—
4	modules/L2_Generation/generator/test_generation_c.md、modules/L2_Generation/generator/test_patterns_napi_ets.md	modules/L2_Generation/generator/test_patterns_napi_ets_advance.md（回调/异步/句柄类 API）、modules/L2_Generation/generator/project_config_templates.md（新建工程）、modules/L2_Generation/generator/napi_api_reference.md（不常用的 napi 函数）
5	modules/L2_Generation/generator/verification_common.md	modules/L2_Generation/generator/test_suite_structure_checklist.md
6	modules/L3_Validation/builder/build_workflow_c.md	modules/L3_Validation/builder/linux_compile_env_setup_c.md（环境配置）、modules/L3_Validation/builder/linux_compile_workflow_c.md（Linux 详细流程）、modules/L3_Validation/builder/quick_reference_extract_suite_name.md（提取测试套名称）
7	—	—
错误处理	references/error_handling.md	所有阶段

配置架构

Priority: User Custom > Module Config > Subsystem Config > Core Config

Core:      references/subsystems/_common.md          (shared mandatory + default rules)
Subsystem: references/subsystems/{Subsystem}/_common.md  (differential rules)
Module:    references/subsystems/{Subsystem}/{Module}.md  (module-specific rules)

关键约束

1. 必须进行校验 — 阶段 5（N-API 三重校验）绝不能跳过
2. 严格遵循 API — 仅使用 .h 头文件中声明的接口
3. 模块名称必须为 entry — nm_modname = "entry"，ETS 从 libentry.so 导入
4. 不得修改项目配置 — 仅在指定目录中创建测试文件
5. 必须复制模板 — 创建新的测试套时，必须从 template_project/capi_test_template/ 复制
6. 必须添加 @tc 注解 — 每个测试用例都必须包含标准的 @tc 块
7. 错误处理使用 napi_throw_error — 不要从 N-API 函数返回错误对象

必需阶段 5：N-API 三重校验

此阶段是核心质量门禁。跳过此阶段会导致运行时崩溃、函数注册缺失，以及 C++、TypeScript 和 ETS 之间的类型不匹配。

自检方法（生成所有文件后执行）

生成 NapiTest.cpp、index.d.ts 和 .test.ets 文件后，在确认生成完成之前，必须执行以下交叉检查。对于每项检查，列出提取的条目并确认它们相符。

检查 1：C++ 注册完整性

从 NapiTest.cpp 中提取所有 static napi_value 函数定义，然后验证每个函数是否出现在 Init 中的 napi_property_descriptor desc[] 数组里。报告所有缺失的注册项。

检查 2：TypeScript ↔ C++ 一致性

从 napi_property_descriptor desc[] 中提取所有 JS 函数名（第一个字符串参数），然后验证每个名称是否在 index.d.ts 中有对应的 export const。报告所有缺失的声明。

检查 3：ETS ↔ TypeScript 一致性

从 .test.ets 文件中提取所有 testNapi.xxx 调用，然后验证每个 xxx 是否在 index.d.ts 中有对应的 export const。报告所有未定义的引用。

输出格式

完成所有检查后，输出摘要：

=== N-API Triple Verification ===
C++ functions defined: N
C++ functions registered: N (missing: none)
TypeScript declarations: N (missing: none)
ETS testNapi calls: N (undefined: none)
Result: PASS

如果任一检查失败，请立即修复生成的文件，然后再继续。

自动验证脚本（如果目标路径存在，则运行）

bash scripts/verify_napi_triple.sh ${TARGET_PATH}
bash scripts/check_test_suite_structure.sh ${TARGET_PATH}

生成策略

优先级：补充已有工程 > 创建新工程

1. 用户指定目标测试套 → 直接在该工程中补充用例
2. 分析后发现可添加到已有工程 → 在已有工程中补充用例
3. 用户未指定且无合适已有工程 → 创建新工程（必须先复制模板）

支持的子系统

子系统	配置路径	关键说明
multimedia	references/subsystems/multimedia/	Camera 导入使用 <ohcamera/xxx.h>
bundlemanager	references/subsystems/bundlemanager/
ability	references/subsystems/ability/
hilog	references/subsystems/hilog/

测试套结构

{测试套名称}/
├── AppScope/app.json5
├── BUILD.gn
├── Test.json
├── build-profile.json5
├── oh-package.json5
├── signature/openharmony.p7b
├── entry/
│   └── src/
│       ├── main/
│       │   ├── cpp/
│       │   │   ├── NapiTest.cpp
│       │   │   ├── CMakeLists.txt
│       │   │   └── types/libentry/index.d.ts
│       │   ├── ets/entryability/EntryAbility.ts
│       │   ├── module.json5
│       │   └── syscap.json
│       └── ohosTest/
│           └── ets/test/*.test.ets

---

版本：2.2.0 | 更新日期：2026-04-08 | 兼容性：OpenHarmony API 10+