OpenHarmony XTS test case universal generation template
Skill Overview
oh-xts-generator-template is a universal OpenHarmony XTS test case generation template that adopts a four-layer modular architecture and supports customized configuration for various subsystems.
Core Features
- API Definition Parsing: Parse
.d.tsfiles, extract interfaces, methods, parameters, and return values - API syntax type filtering and validation: Filter APIs according to the task type (dynamic/static), and verify whether the APIs used by test cases support the target syntax type
- Intelligent Test Generation: Automatically generate test cases that comply with XTS specifications according to the test strategy
- Synchronized Generation of Test Design Documents: While generating test cases, synchronously generate structured test design documents
- ⚠️ Formatting and Validation (Mandatory): Check syntax specifications, validate assertion methods, and ensure test case quality
- Test Coverage Analysis: Analyze existing test files and identify covered and uncovered APIs
- Coverage Report-Driven Generation: Generate test cases directly based on the missing items in the coverage report (efficient mode)
- Compilation Verification Support: Provide compilation guides for Linux/Windows environments
Applicable Scenarios
- Generate a complete test suite for a new API
- Analyze the coverage of existing tests
- Customized test generation for various subsystems
- Supplement missing tests based on the coverage report(Recommended - Efficient and Precise)
Prerequisite Configuration
OH_ROOT Path Configuration (Required)
Before using this skill, you must configure the .oh-xts-config.json file in the skill directory with the OH_ROOT path:
Configuration File Location：.opencode/skills/oh-xts-generator-template/.oh-xts-config.json
Configuration Format：
{
"OH_ROOT": "/path/to/openharmony/root"
}
Configuration Description：
OH_ROOT: Absolute path of the OpenHarmony project root directory- This path is used to read project files, API declaration files (
.d.ts), test files, etc. - You must ensure that the path exists and is accessible
⚠️ Important: Before using the skill, be sure to check whether this configuration is set correctly; otherwise, the skill will not work properly.
Quick Start
📖 Detailed Usage: docs/USAGE.md
Overview of Three Usage Methods
| Method | Applicable Scenario | Link |
|---|---|---|
| Method 1: Universal Template | Beginners, simple tasks | USAGE.md |
| Method 2: Subsystem Configuration | Most tasks (recommended) | USAGE.md |
| Method 3: Custom Configuration | Advanced users, special requirements | USAGE.md |
Coverage Report-Driven Mode
When the user provides a test coverage report, the system will automatically switch tocoverage report-driven mode, which has the following characteristics:
Advantages：
- Efficient: Skip the coverage analysis step and generate test cases directly based on the missing items in the report
- Precise: Generate tests strictly according to the uncovered APIs, parameter combinations, and scenarios listed in the coverage report
- Fast: Significantly shorten generation time, especially for large API sets
How It Works：
- Parse the coverage report provided by the user
- Extract the missing test items marked in the report
- Only scan existing test files for code style (no coverage analysis)
- Directly generate test cases for the missing items
Coverage Report Format Requirements: The report should contain the following information:
- Uncovered API names
- Missing parameter combinations
- Missing test scenarios (such as boundary values, error codes, etc.)
- Test types (PARAM, ERROR, RETURN, BOUNDARY)
Specification for Extracting Error Codes from Coverage Reports：
- Read the error code column: for example "401/17000002/17000007"
- Verify from @throws tags: check the @throws tags in the .d.ts file
- Determine the actual error codes: determine the specific error codes according to parameter types and trigger conditions
- Explicitly declare when generating tests：
- **预期结果**: 抛出错误码 401 # 明确 - **断言方法**: `expect(e.code).assertEqual(ErrorCode)` # 正确
💡 Tip: If a coverage report already exists, providing the report content directly will yield the best efficiency and precision
API Syntax Type Filtering (New)
Overview
When the task explicitly states it is an arkts-dynamic or arkts-static syntax task, the system will:
- Automatically filter APIs: filter APIs according to syntax type, and only generate test cases that support the target syntax
- Automatically verify: verify whether the APIs used by the generated test cases support the target syntax type
- Prevent errors: avoid using APIs that do not support the target syntax, and prevent compilation errors
Tools and Documentation
| Tool/Documentation | Path | Description |
|---|---|---|
| API syntax type check script | scripts/check_syntax_type.js |
Verify the APIs used by test cases before compilation |
| API syntax type filtering documentation | modules/L2_Analysis/unified_api_parser.md Chapter 10 |
Detailed description of API syntax type filtering |
| Check script usage guide | scripts/check_syntax_type_usage.md |
Usage examples and common questions for the check script |
Usage Examples
# 编译前检查 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
Core Workflow
Workflow Branches
This skill supports two workflows and automatically selects one based on user input:
Process A: Coverage Report Driven (when the user provides a coverage report)
- Determine subsystem configuration - Load core configuration and subsystem-specific configuration ├─ Check whether a subsystem configuration file exists ├─ Load common configuration (_common.md) ├─ Load subsystem configuration ({Subsystem}/_common.md) └─ Load module configuration ({Subsystem}/{Module}.md) (if needed)
- Parse the coverage report - Extract missing test items from the coverage report provided by the user ├─ Identify uncovered APIs and parameter combinations ├─ Extract missing test scenarios └─ Analyze the test types that need to be supplemented (PARAM, ERROR, RETURN, BOUNDARY)
- API information parsing - Parse the .d.ts file to extract interface, method, and parameter information for missing test items ├─ Read the API declaration file (.d.ts) ├─ Find and parse the API documentation └─ Comprehensive analysis
- Scan code style - Quickly scan existing test files and extract only the code style (skip coverage analysis) └─ [Use analysis-agent subagent - code style only mode]
- Generate test cases and test design documents - Based on the missing items in the coverage report, generate test cases and test design documents at the same time ├─ Apply subsystem-specific rules ├─ Use subsystem-specific templates ├─ Apply the code style of existing cases ├─ Strictly follow the interface definitions in the API declaration file ├─ While generating each test case, output the corresponding test design document entry at the same time └─ Finally output the complete test design document file in a unified manner
- Register test suite - Register the newly added test file in List.test.ets (if needed) ├─ Add the import statement └─ Call it in the testsuite() function
- ⚠️ Formatting and validation (mandatory step) - Check syntax conventions, validate assertion methods, and ensure test case quality
├─ Completion conditions: All syntax errors have been fixed, assertion methods are correct, and the code complies with the conventions
├─ Check items:
│ ├─ ArkTS syntax compliance (dynamic/static)
│ ├─ Completeness of the @tc comment block
│ ├─ Correctness of the hypium import statement
│ ├─ Test case naming conventions
│ └─ Correctness of assertion methods
└─ [Use validation-agent subagent]
├─ When generating dynamic XTS cases, follow the dynamic syntax conventions. Detailed guide:# Complete set of ArkTS dynamic syntax check rules
└─ When generating static XTS cases, follow the static syntax conventions, and you need to call the dedicated
arkts-static-specskill for syntax convention validation: ├─ Usage:请使用 arkts-static-spec 进行语法规范校验└─ Detailed guide:ArkTS static language syntax conventions guide - Compilation validation (important) ├─ Detect the runtime environment (Linux/Windows) ├─ Select the compilation solution according to the environment ├─ Linux environment: use a subagent to perform compilation, monitor the process, and automatically fix syntax errors ├─ Windows environment: automatically select dynamic or static compilation mode according to keywords └─ Detailed compilation process: See Note 7 "Compilation environment detection"
- Output the updated file list, test design documents, and coverage comparison
Process B: Standard process (when the user does not provide a coverage report)
- Determine subsystem configuration - Load the core configuration and subsystem-specific configuration ├─ Check whether a subsystem configuration file exists ├─ Load the common configuration (_common.md) ├─ Load the subsystem configuration ({Subsystem}/_common.md) └─ Load the module configuration ({Subsystem}/{Module}.md) (if needed)
- API information parsing - Parse the .d.ts file to extract interface, method, and parameter information ├─ Read the API declaration file (.d.ts) ├─ Find and parse the API documentation └─ Comprehensive analysis
- Test coverage analysis - Scan existing test files and analyze code style and coverage └─ [Use analysis-agent subagent]
- Generate test cases and test design documents - Apply subsystem-specific rules, and generate both test cases and test design documents ├─ Subsystem-specific rules ├─ Use subsystem-specific templates ├─ Apply the code style of existing test cases ├─ Strictly follow the interface definitions in the API declaration files ├─ While generating each test case, output the corresponding test design document entry at the same time └─ Finally output the complete test design document file in a unified manner
- Register test suite - Register the newly added test file in List.test.ets (if needed) ├─ Add the import statement └─ Call it in the testsuite() function
- ⚠️ Formatting and validation (mandatory step) - Check syntax conventions, validate assertion methods, and ensure test case quality
├─ Completion criteria: All syntax errors have been fixed, assertion methods are correct, and the code complies with the conventions
├─ Check items:
│ ├─ ArkTS syntax compliance (dynamic/static)
│ ├─ Completeness of the @tc comment block
│ ├─ Correctness of hypium import statements
│ ├─ Test case naming conventions
│ └─ Correctness of assertion methods
└─ [Use validation-agent subagent]
├─ When generating dynamic XTS test cases, follow the dynamic syntax conventions. Detailed guide:# Complete set of ArkTS dynamic syntax check rules
└─ When generating static XTS test cases, follow the static syntax conventions, and you need to call the dedicated
arkts-static-specskill for syntax convention validation: ├─ Usage:请使用 arkts-static-spec 进行语法规范校验└─ Detailed guide:ArkTS static language syntax conventions guide - Compilation validation (important) ├─ Detect the runtime environment (Linux/Windows) ├─ Select the compilation scheme according to the environment ├─ Linux environment: use a subagent to execute compilation, monitor the process, and automatically fix syntax errors ├─ Windows environment: automatically select dynamic or static compilation mode according to keywords └─ Detailed compilation process: See Note 7 "Compilation environment detection"
- Output the updated file list, test design document, and coverage comparison
Configuration extension
Configuration file search paths：
.opencode/skills/oh-xts-generator-template/references/subsystems/
Supported subsystems：
testfwk- Test frameworkstorage- Storage managementmultimedia- Multimediaarkts- ArkTS language features- Other custom subsystems
📖 Detailed configuration instructions: docs/CONFIG.md
Configuration priority
用户自定义配置 > 模块配置 > 子系统配置 > 核心配置
Configuration architecture description ⭐ Important
Configuration design principles: Core configuration + minimized differentiation
Configuration hierarchy description
| Level | File | Description |
|---|---|---|
| Core configuration | references/subsystems/_common.md |
Core mandatory conventions + default conventions + extension interfaces |
| Subsystem configuration | references/subsystems/{Subsystem}/_common.md |
Basic information + subsystem differentiation configuration + special rules |
| Module configuration | references/subsystems/{Subsystem}/{Module}.md |
Basic information + subsystem differentiation configuration + module differentiation configuration + special rules |
| User-defined configuration | Configuration provided by the user | Overrides subsystem configuration and core configuration |
Output conventions
Test case number (@tc.number)
Format:SUB_[子系统]_[模块]_[API]_[类型]_[序号]，types include PARAM, ERROR, RETURN, BOUNDARY
Test Design Document Specification
- File naming:
{测试文件名}.design.md
Important Notes
1. ⚠️ Formatting and validation steps (mandatory - cannot be skipped)
Important reminder：Formatting and validation are the testing case generationcore mandatory steps，must never be skipped！
Why can this step not be skipped?
- ✅ Ensure the generated test cases comply with the XTS specification
- ✅ Avoid discovering syntax errors only at the compilation stage
- ✅ Ensure test case quality and maintainability
- ✅ Improve test execution success rate
Completion criteria checklist：
- All syntax errors have been fixed
- @tc comment block is complete and correctly formatted
- hypium import statements are correct
- Test case naming complies with the specification (lower camel case)
- Assertion methods are used correctly
- ArkTS syntax complies with the specification (dynamic/static)
Common issues：
- ❌ Jump directly to the compilation step (compilation will not catch all issues)
- ❌ Consider this step optional
- ❌ Ignore warnings in validation results
- ❌ Do not fully execute the validation-agent check
2. @tc comment block specification (mandatory)
All test cases must add a standard @tc comment block, including fields such as name, number, desc, etc. For details, see:Test Framework Specification
3. hypium import specification (mandatory)
For details, see:Hypium Test Framework Basics - Import Statement Specification
4. Project file modification restrictions (mandatory)
It is strictly prohibited to modify configuration files in the project directory; test files can only be created in the specified test directory
5. Strictly follow API declarations (mandatory)
Test cases must be generated strictly according to the interfaces declared in the .d.ts file; interfaces that are not declared must not be used
6. Compilation related
- The Linux environment must use the
./test/xts/acts/build.shscript for compilation - Before compilation, confirm the compilation target in BUILD.gn
| Environment | Recommended method | Entry document |
|---|---|---|
| Linux | ./test/xts/acts/build.sh script | Linux compilation workflow |
| Windows | DevEco Studio IDE | Windows compilation workflow |
5.1 Linux environment compilation
Basic requirements：
- Use
./test/xts/acts/build.shscript for compilation,Do not usehvigorw - Environment detection:
uname -s
Compilation process：
-
Pre-compilation cleanup(mandatory):
- Use
~/.opencode/skills/oh-xts-generator-template/scripts/cleanup_group.shscript - Purpose of cleanup: ensure the compilation result includes all the latest code
- ⚠️ Safety note: see section 3.1 cleanup operation safety instructions
- Use
-
Static test suite preconditions(when compiling a static suite):
- Verify hvigor version:
"6.0.0-arkts1.2-ohosTest-25072102" - Version match: skip tool replacement; version mismatch: execute replacement process
- Tool replacement: clean SDK cache → clean old tools → download new tools → move to preset directory
- Verify hvigor version:
-
Compile and execute：
- Execute using a general subagent (to avoid interrupting the main workflow)
- Monitor the compilation process until it completes
- Syntax errors: automatically analyze and fix, then retry compilation
- Configuration errors: pause and confirm with the user before making changes
5.2 Windows Environment Compilation
Automatically select the compilation mode based on keywords:
7.2.1 ArkTS Dynamic XTS Compilation (default)
- Compilation method: DevEco Studio IDE or
hvigorw.bat - Compilation target：
Build → Build OhosTest Hap(s) - Reference documentation：
modules/L4_Build/build_workflow_windows.mdChapter 3
7.2.2 ArkTS Static XTS Compilation (arkts-sta)
- Applicable scenarios: XTS test projects based on ArkTS static strongly-typed syntax
- Trigger keywords: automatically enabled when the user mentions any of the following keywords:
- Technical terms：
arkts-sta、ArkTS静态、arkts static、ArkTS static - General expressions：
静态xts、静态 XTS、static arkts、static xts - Operation description：
编译静态、静态编译、静态工程编译、Windows静态编译
- Technical terms：
- Compilation method: PowerShell script or
hvigorw.batcommand-line tool - Java environment：RequiredConfigure the JAVA_HOME environment variable
- Compilation features：
- Strict static type checking
- All types must have explicit annotations
- Use of the any type is prohibited
- All fields must be initialized
- Strict type validation: directly reports a compilation error when the input parameter type does not match, and does not throw a 401 error code at runtime
- Compile-time type verification: all type errors are exposed at the compilation stage, improving code quality
- No runtime type exceptions: eliminates runtime crashes caused by type errors
- Type validation strategy：
- The compiler checks the correctness of all type annotations
- Function parameter types must exactly match the declaration
- Return value types must be consistent with the declaration
- Generic type parameters must be determined at compile time
- Reference documentation：
modules/L4_Build/build_workflow_windows.mdChapter 10
⚠️ Important note：
- Use dynamic compilation mode by default
- Enable static compilation mode only when the user explicitly mentions static-related keywords
- Static compilation requires configuring the Java environment variable (JAVA_HOME)
📖 Detailed compilation documentation: modules/L4_Build/
Troubleshooting
📖 Detailed troubleshooting guide: docs/TROUBLESHOOTING.md
Common questions：
- Q1: The generated test cases cannot be compiled
- Q2: Test case naming does not conform to the specification
- Q3: The test design document is inconsistent with the test cases
- Q4: Compilation fails in the Linux environment
- Q5: Test case execution fails
- Q6: The subsystem configuration file is not found
- Q7: Test coverage analysis is inaccurate
- Q8: ArkTS static syntax validation issues
- Q9: How to invoke the arkts-static-spec skill
- Q10: How to use the coverage report-driven mode
Reference documentation
Detailed documentation
- Configuration extension mechanism: docs/CONFIG.md
- Detailed Usage: docs/USAGE.md
- Troubleshooting: docs/TROUBLESHOOTING.md
Submodule Documentation
- L1_Framework: modules/L1_Framework/
- L2_Analysis: modules/L2_Analysis/
- L3_Generation: modules/L3_Generation/
- L4_Build: modules/L4_Build/
General Configuration
- General Configuration: references/subsystems/_common.md