openharmonyinsight/ohos-test-graphics3d-static-api-unit-test

Graphics 3D API Unit Test Generator

Overview

Guide for generating ETS/ArkTS static API unit tests based on OpenHarmony GTest framework. Provides test generation workflow, naming conventions, and core patterns.

When to Use

• Adding unit tests for new ETS wrapper classes (e.g., CameraETS, MaterialETS)
• Extending existing test cases with new test scenarios
• Setting up new test modules or test environment

Do NOT use when:

• Testing Lume engine core layer (use other test frameworks)
• Writing integration tests or performance tests (require different fixtures)

Quick Reference

Naming Conventions

| Element | Convention | Example | |---------|------------|---------| | Test class name | <Module>ETSUnitTest | MaterialETSUnitTest | | Test case name | <Class>_<Method>_<Number> | MaterialETS_Create_001 | | Test file name | <module>_ets_unit_test.cpp | material_ets_unit_test.cpp |

Test Macros

| Macro | Purpose | |-------|---------| | HWTEST_F | Fixed test fixture (required for all ETS unit tests) |

Test Levels: Use appropriate TestSize.Level0-Level4 based on test complexity.

Selection Rule

• Default: TestSize.Level1 for most API method tests
• Adjust: Use higher levels for complex scenarios (error handling, performance)

See UNITTEST_GUIDE.md "Test Case Macros" section for complete Level0-Level4 definitions.

Required Comment Template

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

Core Pattern: AAA Testing

Use Arrange-Act-Assert pattern:

/**
 * @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
}

Implementation Workflow

1. Create test file: api_unit_test/<module>_ets_unit_test.cpp
2. Write test cases: Use AAA pattern with required annotations
3. Update BUILD.gn: Add file to sources list

Complete implementation details: UNITTEST_GUIDE.md provides:

• EtsTest fixture class implementation
• Complete BUILD.gn template
• Environment setup and build commands
• Error handling examples

For loading guidance, see "When to Load References" section below.

When to Load References

✅ Load UNITTEST_GUIDE.md when:

• Setting up new test module (first-time setup)
• Writing first test for a class (need complete workflow)
• Need complete BUILD.gn template (copy-paste ready)
• Troubleshooting build/run errors (detailed solutions)
• Need EtsTest fixture details (engine lifecycle understanding)

❌ Do NOT Load when:

• Quick test generation (SKILL.md Quick Reference sufficient)
• Simple naming queries (conventions in SKILL.md)
• Familiar scenarios (standard patterns known)
• Only need Quick Reference tables (no deep dive required)

Rule: Start with SKILL.md. Load UNITTEST_GUIDE.md only when blocked or setting up new environment.

Link: UNITTEST_GUIDE.md (load only when above conditions apply)

Common Mistakes

| Issue | Solution | |-------|----------| | Header not found | Check BUILD.gn include_dirs | | Library not found | Ensure libAGPDLL.z.so deployed | | Tests interfere | Use SetUp/TearDown for isolation |

NEVER Do This

| ❌ Wrong | ✅ Right | Reason | |----------|----------|--------| | MaterialETS_Test | MaterialETSUnitTest | OpenHarmony requires UnitTest suffix | | MaterialETS_Create | MaterialETS_Create_001 | Test naming MUST include _Number suffix | | Skip @tc.name | Always add annotation | Required for test report generation | | Use GTest macro directly | Use HWTEST_F macro | OpenHarmony test framework requires it | | Write test without annotations | Include complete annotation block | Missing annotations break test discovery |

Real-World Impact

Tests generated following this skill:

• Comply with OpenHarmony testing standards
• Automated engine lifecycle management
• Complete resource cleanup mechanism

References

| Document | Description | |----------|-------------| | UNITTEST_GUIDE.md | Complete BUILD.gn template, EtsTest base class, environment setup |