oh-xts-generator-template

Universal Generation Template for OpenHarmony XTS Test Cases

Skill Overview

oh-xts-generator-template is a universal OpenHarmony XTS test case generation template, designed as a configurable and extensible general framework suitable for test case generation in various subsystems.

Core Features

Universal Test Generation Workflow - Provides a complete test case generation workflow
Modular Architecture - Four-layer modular design (L1/L2/L3/L4), loaded on demand
Layered Configuration System - General configuration + subsystem-specific configuration
Flexible Extension Mechanism - Supports adding subsystem-specific configurations and templates

Core Functions

Function	Description
API Definition Parsing	Parse `.d.ts` files, extract interfaces, methods, parameters, return values, and error codes
Test Coverage Analysis	Analyze existing test files, identify covered and uncovered APIs
Intelligent Test Generation	Automatically generate test cases compliant with XTS specifications based on test strategies
Test Design Document Generation	Simultaneously generate structured test design documents, including test case descriptions, expected results, etc.
ArkTS Static Language Syntax Specification Validation	Validate ArkTS static language syntax specifications, including type annotations, field initialization, syntax compatibility, etc.
Code Specification Checking	Ensure generated code complies with XTS test specifications
Compilation Issue Resolution	Use subagent to execute compilation, automatically fix syntax errors, and monitor compilation completion status

Applicable Scenarios

✅ Generate complete test suites for new APIs
✅ Generate test cases and test design documents simultaneously
✅ Analyze coverage of existing tests
✅ Supplement missing test cases and test designs
✅ Verify test code standardization
✅ Customized test generation for each subsystem

Quick Start

📖 Detailed Usage: docs/USAGE.md

Overview of Three Usage Methods

Method	Applicable Scenario	Link
Method 1: General 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

Core Workflow

1. Determine Subsystem Configuration
    ├─ Check if subsystem configuration file exists
    ├─ Load general configuration (_common.md)
    └─ Load subsystem configuration ({Subsystem}/_common.md)

2. Parse API Definitions (.d.ts + Documentation)
    ├─ Read API declaration files (.d.ts)
    ├─ Find and parse API documentation
    └─ Comprehensive analysis

3. Reference Existing Cases (Mandatory)
    ├─ Scan specified paths for existing test files
    ├─ Analyze code style and specifications
    └─ Extract common patterns

4. Analyze Existing Tests (Optional)
    ├─ Scan test files
    ├─ Identify covered APIs
    └─ Calculate test coverage

5. Generate Test Cases
    ├─ Apply subsystem-specific rules
    ├─ Use subsystem-specific templates
    └─ Apply code style from existing cases

6. Synchronously Generate Test Design Documents (Mandatory)
    ├─ Generate detailed design descriptions for each test case
    ├─ Include test scenarios, test steps, and expected results
    ├─ Generate structured Markdown documents
    └─ Use corresponding naming with test case files

7. Add @tc Comment Block (Mandatory)
    ├─ @tc.name: camelCase naming, consistent with the it() parameter
    ├─ @tc.number: {describe_name}_{sequence_number}
    ├─ @tc.desc: {API_name} {error_code/scenario} test.
    └─ Verify consistency between field values and it() parameters

 8. Formatting and Validation
     ├─ Apply code templates
     ├─ Check syntax specifications
     │   ├─ 8.1 Dynamic Syntax Check (when generating dynamic XTS cases)
     │   │   └─ Reference specification document: `references/ArkTS_Dynamic_Syntax_Rules.md`
     │   └─ 8.2 Static Syntax Check (when generating static XTS cases)
     │       └─ Reference specification document: `references/arkts-static-spec/`
     ├─ Validate assertion methods
     └─ Output validation results and modification suggestions

9. Register Test Suite (Mandatory for New Files)
    ├─ Find List.test.ets file
    ├─ Add import statement
    └─ Call in testsuite() function

 10. Compilation Validation (Important)
     ├─ Detect runtime environment (Linux/Windows)
     ├─ Select compilation scheme based on environment
     ├─ Linux environment: Use subagent to execute compilation, monitor process, automatically fix syntax errors
     ├─ Windows environment: Automatically select dynamic or static compilation mode based on keywords
     └─ **Detailed Compilation Process**: See Note 7 "Compilation Environment Detection"

11. Output updated file list, test design documents, and coverage comparison

> 📖 **Detailed Workflow Description**: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)

## Configuration Extension

> 📖 **Detailed Configuration Instructions**: [docs/CONFIG.md](./docs/CONFIG.md)

### Configuration Priority

User-defined Configuration > Subsystem Configuration > General Configuration


## Output Specifications

### Test Case Number(`@tc.number`)

Format: SUB_[subsystem][module][API][type][sequence_number]

Type Identifiers：

PARAM Parameter Test
ERROR Error Code Test
RETURN Return Value Test
BOUNDARY Boundary Value Test


### Test Design Document Specifications (Mandatory)

**File Naming Rule**：

Format: {test_file_name}.design.md Example: Component.onClick.test.ets -> Component.onClick.test.design.md


**Document Templates and Generation Rules**：
- Standard Template: `modules/L3_Generation/design_doc_generator.md`
- Simplified Template: `modules/L3_Generation/design_doc_templates.md`


### Test Design Document Generation Rules

**1. Synchronous Generation Principle**
- When generating each test case, must synchronously generate corresponding test design document
- Test design documents correspond one-to-one with test cases
- Document content must be consistent with test case implementation

**2. Document Content Completeness**
- Must include detailed descriptions of all test scenarios
- Must include test steps and expected results
- Must explain test environment and preconditions
- Must record change history

**3. Document Format Standardization**
- Use Markdown format
- Follow unified template structure
- Use tables to organize key information
- Keep version information updated

**4. Document Update Mechanism**
- When modifying test cases, must synchronously update test design documents
- Document version number must be incremented
- Changes must be recorded in the change log

### Task Completion Output

After each task is completed, **must** output：

```markdown
## Task Completion Summary

### New Test Files
- `path/to/file1.test.ets` - File description

### New Test Design Documents
- `path/to/file1.test.design.md` - Design document description

### Modified Files
- `path/to/file2.ets` - Modification description

### Test Coverage Statistics
- Number of new test cases: XX
- Number of new test design documents: XX
- Covered APIs: XX

📖 Complete Usage Guide: docs/USAGE.md

Important Notes

1. @tc Comment Block Specifications (Mandatory)

All test cases (
```
it()
```
functions) must have a standard
```
@tc
```
comment block before them
```
@tc.name
```
: Must use camelCase naming, must be exactly the same as the first parameter of
```
it()
```
- See: Naming specifications in references/subsystems/_common.md
```
@tc.number
```
: Format is
```
{describe_name}_{sequence_number}
```
, sequence numbers start from 001 with zero padding

@tc.desc

: Format is

{API_name} {error_code/scenario} test.

, must end with

```
@tc.type
```
,
```
@tc.size
```
,
```
@tc.level
```
: Must be consistent with the values in the second parameter of
```
it()
```

2. hypium Import Specifications (Mandatory)

Basic imports:
```
describe, it, expect
```
(required)
Type imports:
```
TestType, Level, Size
```
(required)
Conditional imports:
```
beforeAll, afterAll
```
(based on code needs)
Automatically detect and supplement missing imports

3. Project File Modification Restrictions (Mandatory)

Strictly prohibited from modifying configuration files in the project directory
Only allowed to modify: Test files in the
```
entry/src/ohosTest/ets/test/
```
directory
Consequences of violation: May cause project structure damage, compilation failure

4. Cleanup Operation Safety Notes (Mandatory)

⚠️ Critical Warning: Pre-compilation cleanup operations must be performed carefully to avoid accidental deletion of the system compilation environment.

Safety Cleanup Requirements:

Confirm Current Directory: Must confirm the current working directory before executing cleanup commands
bash
```
cd {OH_ROOT}/test/xts/acts/testfwk/{test_suite}
pwd  # Must confirm current directory
```

Use Explicit Path for Deletion: Delete commands must use explicit paths (prefix with

./

or absolute path)

bash

# ✅ Correct: Use explicit relative path
rm -rf ./.hvigor ./build ./entry/build ./oh_modules
rm -f ./oh-package-lock.json5 ./local.properties

# ❌ Incorrect: No path prefix (may accidentally delete OH_ROOT/build)
rm -rf build

Step-by-Step Cleanup and Validation:
- Step 1: Clean test suite cache and validate
- Step 2: Clean OH_ROOT/out directory
- Step 3: Validate safety of OH_ROOT/build directory
Prohibited Operations:
- ❌ Execute
```
rm -rf build
```
  in OH_ROOT directory
- ❌ Clean multiple directories at once
- ❌ Execute deletion without verifying current directory

Reference Document: Section 1.3 of

modules/L4_Build/linux_prebuild_cleanup.md

5. XTS Wiki Document Reference (Mandatory)

When generating XTS test cases, must refer to specifications in Wiki documents
Wiki document specifications > Template configuration > General template

6. ArkTS Syntax Type Identification (Important)

API Type Judgment: Must read the
```
@since
```
tag in the last JSDOC section of the
```
.d.ts
```
file
Project Type Identification: Read
```
build-profile.json5
```
to check the
```
arkTSVersion
```
field
Compatibility Check: Must check if project syntax type matches API type before generating test cases

7. ArkTS Static Language Syntax Specification Validation (Optional)

Trigger Condition: Automatically enabled when user explicitly requests static XTS case generation

Specification Document:

references/arkts-static-spec/

8. Compilation Environment Detection (Mandatory)

7.1 Linux Environment Compilation

Basic Requirements:

Use
```
build.sh
```
script for compilation, do not use
hvigorw
Environment detection:
```
uname -s
```

Compilation Process:

Pre-compilation Cleanup (Mandatory):
- Use
```
cleanup_group.sh
```
  script
- Cleanup purpose: Ensure compilation results include all latest code
- ⚠️ Safety Notes: See Section 3.1 Cleanup Operation Safety Instructions
Preconditions for Static Test Suites (when compiling static suites):
- Validate 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
Compilation Execution:
- Use general subagent for execution (avoid main process interruption)
- Monitor compilation process until completion
- Syntax errors: Automatically analyze and fix, retry compilation
- Configuration errors: Pause and confirm with user before modification

7.2 Windows Environment Compilation

Automatically select 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 Document: Chapter 3 of

modules/L4_Build/build_workflow_windows.md

7.2.2 ArkTS Static XTS Compilation (arkts-sta)

Applicable Scenario: XTS test projects based on ArkTS static strong-type syntax

Trigger Keywords: Automatically enabled when user mentions any of the following:

Technical Terms:

arkts-sta

ArkTS static

arkts static

ArkTS static

General Expressions:

static xts

static XTS

static arkts

static xts

Operation Descriptions:

compile static

static compilation

static project compilation

Windows static compilation

Compilation Method: PowerShell script or
```
hvigorw.bat
```
command-line tool
Java Environment: Must configure JAVA_HOME environment variable
Compilation Features:
- Strict static type checking
- All types must have explicit annotations
- Prohibit use of any type
- All fields must be initialized

Reference Document: Chapter 10 of

modules/L4_Build/build_workflow_windows.md

⚠️ Important Note:

Dynamic compilation mode is used by default

Static compilation mode is only enabled when user explicitly mentions static-related keywords

Static compilation requires configuring Java environment variable (JAVA_HOME)

📖 Detailed Compilation Documents: modules/L4_Build/

Troubleshooting

📖 Detailed Troubleshooting Guide: docs/TROUBLESHOOTING.md

Common Questions:

Q1: Generated test cases cannot be compiled
Q2: Test case naming does not comply with specifications
Q3: Test design documents are inconsistent with test cases
Q4: Compilation fails in Linux environment
Q5: Test case execution fails
Q6: Subsystem configuration file not found
Q7: Test coverage analysis is inaccurate

Version Information

Current Version: 1.20.2
Creation Date: 2025-01-31
Last Updated: 2026-02-12
Compatibility: OpenHarmony API 10+
Based On: OH_XTS_GENERATOR v1.7.0

Version History

Detailed version history can be found in CHANGELOG.md

Recent Updates:

v1.20.2 (2026-02-12): Simplified duplicate content, optimized document structure
v1.20.1 (2026-02-12): Optimized core workflow and duplicate content in notes
v1.20.0 (2026-02-11): Enhanced safety notes for cleanup operations
v1.19.0 (2026-02-11): Enhanced mandatory pre-compilation cleanup
v1.18.0 (2026-02-11): Added hvigor tool version validation mechanism

Reference Documents

Detailed Documents

Modular Architecture Details: docs/ARCHITECTURE.md
Configuration Extension Mechanism: docs/CONFIG.md
Usage Details: docs/USAGE.md
Troubleshooting: docs/TROUBLESHOOTING.md

Submodule Documents

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

oh-xts-generator-template

NPX Install

Tags

SKILL.md Content (Chinese)

oh-xts-generator-template

Skill Overview

Core Features

Core Functions

Applicable Scenarios

Quick Start

Overview of Three Usage Methods

Core Workflow

Important Notes

1. @tc Comment Block Specifications (Mandatory)

2. hypium Import Specifications (Mandatory)

3. Project File Modification Restrictions (Mandatory)

4. Cleanup Operation Safety Notes (Mandatory)

5. XTS Wiki Document Reference (Mandatory)

6. ArkTS Syntax Type Identification (Important)

7. ArkTS Static Language Syntax Specification Validation (Optional)

8. Compilation Environment Detection (Mandatory)

7.1 Linux Environment Compilation

7.2 Windows Environment Compilation

7.2.1 ArkTS Dynamic XTS Compilation (Default)

7.2.2 ArkTS Static XTS Compilation (arkts-sta)

Troubleshooting

Version Information

Version History

Reference Documents

Detailed Documents

Submodule Documents

General Configuration