oh-capi-xts-gen

oh-capi-xts-gen

OpenHarmony CAPI XTS テストケース生成器 — 方式2（N-API ラッパーによるテスト）

アーキテクチャの概要

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

ファイル早見表

何をするか	参照するファイル
.h ヘッダーファイルを解析する	modules/L1_Analysis/parser/unified_api_parser_c.md
ドキュメントを読み取る	modules/L1_Analysis/parser/doc_reader.md
プロジェクト設定を解析する	modules/L1_Analysis/parser/project_parser.md
カバレッジを分析する	modules/L1_Analysis/analyzer/coverage_analyzer.md
C++ N-API ラッパーを生成する	modules/L2_Generation/generator/test_generation_c.md
N-API の基本パターン	modules/L2_Generation/generator/test_patterns_napi_ets.md
N-API の高度なパターン	modules/L2_Generation/generator/test_patterns_napi_ets_advance.md
N-API API リファレンス	modules/L2_Generation/generator/napi_api_reference.md
プロジェクト設定テンプレート	modules/L2_Generation/generator/project_config_templates.md
テストスイート構造チェックリスト	modules/L2_Generation/generator/test_suite_structure_checklist.md
三重検証	modules/L2_Generation/generator/verification_common.md
テストスイートをコンパイルする	modules/L3_Validation/builder/build_workflow_c.md
コンパイル環境を設定する	modules/L3_Validation/builder/linux_compile_env_setup_c.md
Linux コンパイル手順	modules/L3_Validation/builder/linux_compile_workflow_c.md
テストスイート名を抽出する	modules/L3_Validation/builder/quick_reference_extract_suite_name.md

前提条件

OH_ROOT のパスを読み取ります：.opencode/skills/oh-capi-xts-gen/.oh-capi-xts-config.json

CAPI ヘッダーファイルのパス：{OH_ROOT}/interface/sdk_c/

共通制約

1. .h ヘッダーファイルで宣言されたインターフェースに厳密に従って、N-API ラッパーとテストケースを生成します
2. すべてのテストケースに標準の @tc コメントブロックを含める必要があります
3. hypium のインポート文は規則に従う必要があります
4. テストケース名には小文字始まりの camelCase を使用します
5. プロジェクトディレクトリ内のテスト以外のファイルを変更してはいけません
6. N-API の三重検証手順を省略してはいけません

テストケースの命名形式

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

種類：PARAM / ERROR / RETURN / BOUNDARY / MEMORY

例：SUB_HIVIEWDFX_HILOG_OH_LOG_Print_PARAM_001、SUB_BUNDLEMANAGER_BUNDLE_OH_NativeBundle_GetMetadata_RETURN_001

生成アーキテクチャ

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

ワークフロー

分岐の選択

分岐	トリガー	フェーズ3	生成対象
Flow A	ユーザーがカバレッジレポートを提供する（トリガー：カバレッジレポート、テストの追加、テストの不足）	スタイルスキャンのみ — 既存テストからコードスタイルを抽出し、カバレッジは再分析しません	既存プロジェクトへの追加 — カバレッジレポートに基づき不足しているテストのみを生成し、新しいプロジェクトは作成しません
Flow B	カバレッジレポートがない（デフォルト）	全面的なカバレッジ分析 — 既存テストをすべてスキャンし、メソッド／パラメーター／エラーコードのカバレッジを分析して、不足項目のレポートを生成します	既存プロジェクトへの追加を優先 > 新しいプロジェクトの作成（template_project/capi_test_template/ からコピーする必要があります）

Flow A：カバレッジレポートに基づく生成

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. カバレッジレポートを解析して、不足しているテスト項目を抽出します
2. 既存のテストファイルをスキャンし、コードスタイルのみを確認します（命名パターン、コメントスタイル、テスト構造）
3. レポートに記載された不足項目に従ってテストを直接生成します（既存のカバレッジを再分析しません）
4. 既存プロジェクトにテストを追加し、新しいプロジェクトは作成しません

Flow B：標準プロセス（デフォルト）

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 ではフェーズ3で全面的なカバレッジ分析を実施し、既存のテストファイルをすべてスキャンして、不足項目のレポートを生成します。Flow A では、カバレッジレポートがすでにある場合、スタイルスキャンのみを実施します。

フェーズの詳細

フェーズ	名前	主要モジュール	必須
1	サブシステム設定の特定	references/subsystems/_common.md + サブシステム設定	はい
2	ヘッダーファイルの解析	modules/L1_Analysis/parser/unified_api_parser_c.md	はい
3	カバレッジ分析／スタイルスキャン	modules/L1_Analysis/analyzer/coverage_analyzer.md	はい
4	テストケースの生成	modules/L2_Generation/generator/test_generation_c.md + test_patterns_napi_ets.md	はい
5	N-API の三重検証	modules/L2_Generation/generator/verification_common.md	必須 — 絶対に省略しない
6	ビルド検証	modules/L3_Validation/builder/build_workflow_c.md	推奨
7	結果の出力	—	はい

フェーズ 1 の設定読み込み順序：コア → サブシステム → モジュール（優先順位：ユーザーによるカスタマイズ > モジュール設定 > サブシステム設定 > コア設定）

フェーズ 2 の情報源の優先順位：.h ヘッダー（最優先） → サブシステム設定 → リファレンス例

フェーズ 4 で生成する成果物：

成果物	パス
C++ N-API ラッパー	entry/src/main/cpp/NapiTest.cpp
TypeScript 宣言	entry/src/main/cpp/types/libentry/index.d.ts
ETS テストケース	entry/src/ohosTest/ets/test/*.test.ets
ビルド設定	BUILD.gn、Test.json など

モジュールの読み込み（リファレンス注入マップ）

トリガーされた使用パターンに基づいてモジュールを読み込みます。現在のフェーズに必要なものだけを読み込んでください。

フェーズ	常に読み込む	条件付きで読み込む
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（コールバック／非同期／ハンドルクラス API）、modules/L2_Generation/generator/project_config_templates.md（新規プロジェクト）、modules/L2_Generation/generator/napi_api_reference.md（あまり使用されない napi 関数）
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（環境設定）、modules/L3_Validation/builder/linux_compile_workflow_c.md（Linux の詳細な手順）、modules/L3_Validation/builder/quick_reference_extract_suite_name.md（テストスイート名の抽出）
7	—	—
エラー処理	references/error_handling.md	すべてのフェーズ

設定アーキテクチャ

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)

主な制約事項

1. 検証は必須です — フェーズ 5（N-API の三重検証）は絶対に省略できません
2. API を厳守します — .h ヘッダーファイルで宣言されたインターフェースのみを使用してください
3. モジュール名は entry でなければなりません — nm_modname = "entry"、ETS は libentry.so からインポートします
4. プロジェクト設定は変更しません — 指定されたディレクトリにテストファイルのみを作成してください
5. テンプレートのコピーが必要です — 新しいテストスイートを作成する場合は、template_project/capi_test_template/ からコピーしてください
6. @tc アノテーションが必要です — すべてのテストケースに標準の @tc ブロックを含めてください
7. エラー処理には napi_throw_error を使用します — N-API 関数からエラーオブジェクトを返さないでください

必須のフェーズ 5：N-API の三重検証

このフェーズは品質を担保するための重要なゲートです。省略すると、実行時クラッシュ、関数登録の欠落、C++、TypeScript、ETS 間の型の不一致が発生します。

自己検証方法（すべてのファイルを生成した後に実施）

NapiTest.cpp、index.d.ts、.test.ets ファイルを生成した後、生成完了とする前に、必ず以下の相互チェックを行ってください。各チェックでは、抽出した項目を列挙し、一致していることを確認してください。

チェック 1：C++ 登録の完全性

NapiTest.cpp からすべての static napi_value 関数定義を抽出し、それぞれが Init 内の napi_property_descriptor desc[] 配列に含まれていることを確認します。登録漏れがあれば報告します。

チェック 2：TypeScript と C++ の整合性

napi_property_descriptor desc[] からすべての JS 関数名（最初の文字列パラメーター）を抽出し、それぞれに対応する export const が index.d.ts にあることを確認します。宣言漏れがあれば報告します。

チェック 3：ETS と TypeScript の整合性

.test.ets ファイルからすべての testNapi.xxx 呼び出しを抽出し、それぞれの xxx に対応する export const が index.d.ts にあることを確認します。未定義の参照があれば報告します。

出力形式

すべてのチェックが完了したら、次の要約を出力します。

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

いずれかのチェックに失敗した場合は、続行する前に生成されたファイルをすぐに修正します。

自動検証スクリプト（対象パスが存在する場合に実行）

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

生成方針

優先順位：既存のプロジェクトへの追加 > 新しいプロジェクトの作成

1. ユーザーが対象のテストスイートを指定した場合 → そのプロジェクトにテストケースを追加します
2. 分析の結果、既存のプロジェクトに追加できる場合 → 既存のプロジェクトにテストケースを追加します
3. ユーザーが指定しておらず、適切な既存のプロジェクトもない場合 → 新しいプロジェクトを作成します（必ず最初にテンプレートをコピーします）

サポート対象のサブシステム

サブシステム	設定パス	主な注意事項
multimedia	references/subsystems/multimedia/	Camera のインクルードには <ohcamera/xxx.h> を使用します
bundlemanager	references/subsystems/bundlemanager/
ability	references/subsystems/ability/
hilog	references/subsystems/hilog/

テストスイートの構成

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

---

バージョン: 2.2.0 | 更新日: 2026-04-08 | 互換性: OpenHarmony API 10+