ohos-test-graphics3d-static-api-unit-test

Graphics 3D API 单元测试生成器

概述

本指南介绍如何基于 OpenHarmony GTest 框架生成 ETS/ArkTS 静态 API 单元测试，并提供测试生成工作流、命名约定和核心模式。

适用场景

• 为新的 ETS 包装类添加单元测试（例如，CameraETS、MaterialETS）
• 为现有测试用例扩展新的测试场景
• 设置新的测试模块或测试环境

请勿在以下场景中使用：

• 测试 Lume 引擎核心层（请使用其他测试框架）
• 编写集成测试或性能测试（需要使用不同的测试夹具）

快速参考

命名约定

元素	约定	示例
测试类名称	<Module>ETSUnitTest	MaterialETSUnitTest
测试用例名称	<Class>_<Method>_<Number>	MaterialETS_Create_001
测试文件名	<module>_ets_unit_test.cpp	material_ets_unit_test.cpp

测试宏

宏	用途
HWTEST_F	固定测试夹具（所有 ETS 单元测试都必须使用）

测试级别：根据测试复杂度使用适当的 TestSize.Level0-Level4。

选择规则

• 默认：大多数 API 方法测试使用 TestSize.Level1
• 调整：复杂场景（错误处理、性能）使用更高级别

完整的 Level0-Level4 定义请参阅 UNITTEST_GUIDE.md 的“Test Case Macros”章节。

必需的注释模板

/**
 * @tc.name: <TestCaseName>
 * @tc.desc: <Description>
 * @tc.type: FUNC / PERF
 */

核心模式：AAA 测试

使用 Arrange-Act-Assert 模式：

/**
 * @tc.name: MaterialETS_Create_001
 * @tc.desc: Test MaterialETS creation and initialization
 * @tc.type: FUNC
 */
HWTEST_F(MaterialETSUnitTest, MaterialETS_Create_001, TestSize.Level1)
{
    auto material = std::make_shared<MaterialETS>();
    EXPECT_TRUE(material->IsValid());  // EtsTest provides engine context automatically
}

实现工作流

1. 创建测试文件：api_unit_test/<module>_ets_unit_test.cpp
2. 编写测试用例：使用 AAA 模式并添加必需的注解
3. 更新 BUILD.gn：将文件添加到 sources 列表

完整实现详情：UNITTEST_GUIDE.md 提供以下内容：

• EtsTest 测试夹具类的实现
• 完整的 BUILD.gn 模板
• 环境设置和构建命令
• 错误处理示例

加载指南请参阅下文的“When to Load References”章节。

何时加载参考资料

✅ 以下情况请加载 UNITTEST_GUIDE.md：

• 设置新的测试模块（首次设置）
• 为某个类编写第一个测试（需要完整工作流）
• 需要完整的 BUILD.gn 模板（可直接复制粘贴）
• 排查构建/运行错误（需要详细解决方案）
• 需要了解 EtsTest 测试夹具详情（理解引擎生命周期）

❌ 以下情况请勿加载：

• 快速生成测试（SKILL.md 快速参考已足够）
• 简单的命名查询（SKILL.md 中有相关约定）
• 熟悉的场景（已了解标准模式）
• 只需要快速参考表（无需深入了解）

规则：从 SKILL.md 开始。只有遇到阻碍或设置新环境时，才加载 UNITTEST_GUIDE.md。

链接：UNITTEST_GUIDE.md（仅在符合上述条件时加载）

常见错误

问题	解决方案
找不到头文件	检查 BUILD.gn 中的 include_dirs
找不到库	确保已部署 libAGPDLL.z.so
测试相互干扰	使用 SetUp/TearDown 实现隔离

绝对不要这样做

❌ 错误	✅ 正确	原因
MaterialETS_Test	MaterialETSUnitTest	OpenHarmony 要求使用 UnitTest 后缀
MaterialETS_Create	MaterialETS_Create_001	测试命名必须包含 _Number 后缀
跳过 @tc.name	始终添加注解	生成测试报告时必需
直接使用 GTest 宏	使用 HWTEST_F 宏	OpenHarmony 测试框架对此有要求
编写不带注解的测试	添加完整的注解块	缺少注解会导致无法发现测试

实际效果

按照此技能生成的测试：

• 符合 OpenHarmony 测试标准
• 自动管理引擎生命周期
• 具备完整的资源清理机制

参考资料

文档	描述
UNITTEST_GUIDE.md	完整的 BUILD.gn 模板、EtsTest 基类和环境设置