SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsoh-capi-xts-gen

oh-capi-xts-gen

Coding & development

View repository

Updated 10-16 03:11

About this skill

oh-capi-xts-gen

OpenHarmony CAPI XTS Test Case Generator — Method 2 (N-API Wrapper Testing)

Architecture Overview

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

Quick File Index

What do I want to do Which file to look at
Parse .h header files modules/L1_Analysis/parser/unified_api_parser_c.md
Read documents modules/L1_Analysis/parser/doc_reader.md
Parse project configuration modules/L1_Analysis/parser/project_parser.md
Analyze coverage modules/L1_Analysis/analyzer/coverage_analyzer.md
Generate C++ N-API wrappers modules/L2_Generation/generator/test_generation_c.md
N-API basic patterns modules/L2_Generation/generator/test_patterns_napi_ets.md
N-API advanced patterns modules/L2_Generation/generator/test_patterns_napi_ets_advance.md
N-API API reference modules/L2_Generation/generator/napi_api_reference.md
Project configuration templates modules/L2_Generation/generator/project_config_templates.md
Test suite structure check modules/L2_Generation/generator/test_suite_structure_checklist.md
Triple verification modules/L2_Generation/generator/verification_common.md
Compile test suite modules/L3_Validation/builder/build_workflow_c.md
Compilation environment configuration modules/L3_Validation/builder/linux_compile_env_setup_c.md
Linux compilation process modules/L3_Validation/builder/linux_compile_workflow_c.md
Extract test suite name modules/L3_Validation/builder/quick_reference_extract_suite_name.md

Prerequisites

Read the OH_ROOT path:.opencode/skills/oh-capi-xts-gen/.oh-capi-xts-config.json

CAPI header file path:{OH_ROOT}/interface/sdk_c/

Universal Constraints

  1. Strictly follow the .h interfaces declared in the header file to generate N-API wrappers and test cases
  2. Each test case must include the standard @tc comment block
  3. The hypium import statement must comply with the specification
  4. Test case naming uses lower camelCase camelCase
  5. Modifying non-test files in the project directory is prohibited
  6. The N-API triple verification steps must not be skipped

Test Case Naming Format

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

Types: PARAM / ERROR / RETURN / BOUNDARY / MEMORY

Examples: SUB_HIVIEWDFX_HILOG_OH_LOG_Print_PARAM_001, SUB_BUNDLEMANAGER_BUNDLE_OH_NativeBundle_GetMetadata_RETURN_001

Generation Architecture

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

Workflow

Branch Selection

Branch Trigger Phase 3 Generation Target
Flow A User provides coverage report (trigger: coverage report, supplement tests, missing tests) Style scan only — extract code style from existing tests, do NOT re-analyze coverage Supplement existing project — generate only missing tests per coverage report, never create new project
Flow B No coverage report (default) Full coverage analysis — scan all existing tests, analyze method/param/error-code coverage, generate gap report Prioritize supplementing an existing project > creating a new project (must copy from template_project/capi_test_template/）

Flow A: Coverage-Report-Driven

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. Parse coverage report to extract missing test items
  2. Scan existing test files for code style only (naming patterns, comment style, test structure)
  3. Generate tests directly per report's missing items (do NOT re-analyze existing coverage)
  4. Supplement tests in existing project, never create new project

Flow B: Standard Process (Default)

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 performs full coverage analysis in Phase 3 (scans all existing test files, generates gap report). Flow A only performs style scan when coverage report already exists.

Phase Details

Phase Name Key Module Mandatory
1 Determine Subsystem Config references/subsystems/_common.md + subsystem config Yes
2 Header File Parsing modules/L1_Analysis/parser/unified_api_parser_c.md Yes
3 Coverage Analysis / Style Scan modules/L1_Analysis/analyzer/coverage_analyzer.md Yes
4 Generate Test Cases modules/L2_Generation/generator/test_generation_c.md + test_patterns_napi_ets.md Yes
5 N-API Triple Verification modules/L2_Generation/generator/verification_common.md MANDATORY — NEVER SKIP
6 Build Verification modules/L3_Validation/builder/build_workflow_c.md Recommended
7 Output Results — Yes

Phase 1 config loading order: Core → Subsystem → Module (priority: User Custom > Module Config > Subsystem Config > Core Config)

Phase 2 info source priority: .h header (highest) → subsystem config → reference examples

Phase 4 generated artifacts:

Artifact Path
C++ N-API wrapper entry/src/main/cpp/NapiTest.cpp
TypeScript declaration entry/src/main/cpp/types/libentry/index.d.ts
ETS test cases entry/src/ohosTest/ets/test/*.test.ets
Build config BUILD.gn, Test.json, etc.

Module Loading (Reference Injection Map)

Load modules based on the triggered usage pattern. Only load what's needed for the current phase.

Phase Always Load Conditionally Load
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(callback/async/handle-type APIs), modules/L2_Generation/generator/project_config_templates.md(new project), modules/L2_Generation/generator/napi_api_reference.md(less commonly used napi functions)
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(environment configuration), modules/L3_Validation/builder/linux_compile_workflow_c.md(Linux detailed process), modules/L3_Validation/builder/quick_reference_extract_suite_name.md(extract test suite name)
7 — —
Error handling references/error_handling.md All phases

Configuration Architecture

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)

Key Constraints

  1. Verification is mandatory — Phase 5 (N-API triple verification) can never be skipped
  2. Strict API adherence — Only use interfaces declared in .h header files
  3. Module name must be entry — nm_modname = "entry", ETS imports from libentry.so
  4. No project config modification — Only create test files in designated directories
  5. Template copy required — Creating new test suite must copy from template_project/capi_test_template/
  6. @tc annotation required — Every test case must have standard @tc block
  7. Error handling uses napi_throw_error — Do not return error objects from N-API functions

Mandatory Phase 5: N-API Triple Verification

This phase is the core quality gate. Skipping it will cause runtime crashes, missing function registrations, and type mismatches between C++, TypeScript, and ETS.

Self-Verification Method (perform after generating all files)

After generating NapiTest.cpp, index.d.ts, and .test.ets files, you MUST perform the following cross-checks before considering generation complete. For each check, list the extracted items and confirm they match.

Check 1: C++ Registration Completeness

Extract all static napi_value function definitions from NapiTest.cpp, then verify each one appears in the napi_property_descriptor desc[] array in Init. Report any missing registrations.

Check 2: TypeScript ↔ C++ Consistency

Extract all JS function names (the first string parameter) from napi_property_descriptor desc[], then verify each one has a matching export const in index.d.ts. Report any missing declarations.

Check 3: ETS ↔ TypeScript Consistency

Extract all testNapi.xxx calls from .test.ets files, then verify each xxx has a matching export const in index.d.ts. Report any undefined references.

Output Format

After completing all checks, output a summary:

=== 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

If any check fails, fix the generated files immediately before proceeding.

Automated Verification Scripts (run if target path exists)

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

Generation Strategy

Priority:Supplement existing project > create new project

  1. User specifies a target test suite → directly supplement test cases in that project
  2. After analysis, it is found that it can be added to an existing project → supplement test cases in the existing project
  3. The user does not specify one and there is no suitable existing project → create a new project (must first copy the template)

Supported Subsystems

Subsystem Config Path Key Notes
multimedia references/subsystems/multimedia/ Camera include uses <ohcamera/xxx.h>
bundlemanager references/subsystems/bundlemanager/
ability references/subsystems/ability/
hilog references/subsystems/hilog/

Test Suite Structure

{测试套名称}/
├── 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

Version: 2.2.0 | Update date: 2026-04-08 | Compatibility: OpenHarmony API 10+