ohos-test-ut-generation

OpenHarmony 単体テストの生成

OpenHarmony の C/C++ コード向けに、testfwk_developer_test フレームワークの仕様に準拠した単体テストケースを生成します。

---

アンチパターン - 絶対禁止事項

以下の操作は絶対に行わないでください。テストをコンパイルまたは実行できなくなる原因になります。

禁止事項	理由	正しい方法
NEVER 省略 using namespace testing::ext;	HWTEST/HWTEST_Fなどのマクロはこの名前空間で定義されており、省略するとコンパイルに失敗します	ファイルの先頭に必ずこの文を記述します
NEVER GTest標準の TEST() または TEST_F() を使用する	OpenHarmonyのゲートで認識されず、テストレベルのパラメーターもありません	必ず HWTEST または HWTEST_F を使用します
NEVER HWTESTマクロのテストレベルパラメーターを忘れる	TestSize.Level1-4はゲートの判定基準であり、省略すると拒否されます	TestSize.Level1 などを必ず指定します
NEVER import("//build/test.gni") を省略する	ohos_unittestテンプレートはこのファイルで定義されており、省略すると「template not found」エラーになります	BUILD.gnの1行目に必ずimportします
NEVER module_out_pathに絶対パスを使用する	出力パスは サブシステム名/モジュール名 の形式である必要があり、GNパスではエラーになります	hiviewdfx/hiview_test などを使用します
NEVER privateメンバーにアクセスする際にcflags_ccによる回避を忘れる	privateメンバーには直接アクセスできず、「is private」エラーになります	-Dprivate=public -Dprotected=public を追加します
NEVER テストタイプの概念を混同する	OpenHarmonyのFUNC/PERF/RELI/SECU/FUZZタイプはGTestの概念とは異なります	@tc.typeにはOHで定義されたタイプを使用します
NEVER SetUpでテストオブジェクトの初期化を忘れる	ポインターが初期化されていないと、SEGFAULTやNULL pointerエラーが発生します	SetUpでdetector_などのオブジェクトを必ず作成します
NEVER gtest_main依存関係を省略する	省略すると「undefined reference to main」リンクエラーが発生します	depsに //third_party/googletest:gtest_main を必ず含めます

---

実行手順

环境确认 → 分析源码 → 测试策略 → 测试设计 → 用例规划 → 编写测试文件 → BUILD.gn → 验证

---

ステップ0：環境の確認

目標：テストファイルの配置場所とコンパイル環境の設定を確認します。

必須 - ファイル全体を読むこと：環境を確認する前に、test-framework.mdを最後まで読んで、以下を理解する必要があります。

• ohos_unittest/ohos_moduletest/ohos_fuzztestの違いと選択方法
• APIバージョンとの対応関係
• テストフレームワークのディレクトリー構造

必要な場合のみ読み込む：

• framework-quickref.md - テストフレームワークのクイックリファレンス（マクロ＋レベル＋コメント＋命名）

読み込まないこと：build-rules.md、error-matrix.md（このステップでは扱いません）

チェックリスト（必ず完了すること）

チェック項目	仕様	例
テストファイルの場所	モジュールルート/test/unittest/	base/hiviewdfx/hiview/test/unittest/
Mockファイルの場所	test/mock/	base/hiviewdfx/hiview/test/mock/
BUILD.gnの場所	test/ディレクトリー内	base/hiviewdfx/hiview/test/BUILD.gn
BUILD.gnのエントリーポイント	group("unittest") { testonly = true }	--
ソースコードパスの形式	GN形式 //base/xxx	//base/hiviewdfx/hiview

出力形式

確認が完了したら、次のように出力します。

## 环境确认完成
- 模块根目录: base/xxx/yyy
- 测试目录: base/xxx/yyy/test/unittest/
- 测试输出路径: subsystem/module_test
- 源码GN路径: //base/xxx/yyy

---

既存テストの分析（任意）

目標：対象モジュールに既存のテストコードがある場合は、まず既存のスタイルを分析し、新たに生成するテストがそれに準拠するようにします。

analyze-existing-tests.pyスクリプトを使用して既存のテストを分析します。

python scripts/analyze-existing-tests.py <test_directory> --output style_report.md [--encoding utf-8] [--verbose]

パラメーターの説明：

パラメーター	説明
directory	テストケースのディレクトリーパス（必須）
--output, -o	出力レポートのファイルパス（任意。指定しない場合はターミナルに出力）
--encoding, -e	ファイルの読み取りエンコーディング（デフォルトはutf-8）
--verbose, -v	詳細なデバッグ情報を出力

実行するタイミング：

• 対象モジュールの test/unittest/ ディレクトリーにテストファイルがある場合は、このスクリプトを先に実行することを推奨します
• 新規モジュールで既存のコードがない場合は、このステップをスキップします

分析結果の用途：

1. マクロの選択：既存コードで主にHWTESTとHWTEST_Fのどちらが使用されているかを確認します
2. レベルの形式：既存コードで TestSize.Level1 と Level1 のどちらが使用されているかを確認します
3. 命名スタイル：既存コードのテストケースの命名パターン（FuncName_001 と TestSuite_FuncName_001）を確認します
4. コメントのスタイル：既存コードの@tcコメントの形式を確認します

---

ステップ一：テスト対象のソースコードを分析する

目標：ソースコードを解析し、テストに必要な構造化情報を抽出します。

Light Loading（必要な場合のみ読み込みます）：

• test-framework.md - ステップ0で完了していない場合は、読み進めます
• framework-quickref.md - 命名規則を参照する場合
• real-patterns.md - 実際のコード例を参照する必要がある場合

読み込まないでください：build-rules.md、error-matrix.md、assertion-gmock-guide.md（このステップでは扱いません）

解析のポイント

解析カテゴリ	重要な情報	方法
クラス構造	クラス名、継承関係、メンバー変数	class定義ブロックを抽出します
公開メソッド	関数シグネチャ、戻り値の型、パラメーターリスト	publicセクションの関数宣言を分析します
関数ロジック	分岐条件、例外処理、境界チェック	if/try/returnロジックを抽出します
データ型	列挙型、定数、構造体の定義	enum/const/structを抽出します

出力形式（構造化レポート）

## 源码分析报告
### 文件信息
- 源文件: //base/xxx/src/file.cpp
- 头文件: //base/xxx/include/file.h
- 命名空间: OHOS::XXX
### 公开方法列表
| 方法 | 签名 | 分支逻辑 | 边界条件 |
| GetSectionInfo | bool GetSectionInfo(const string&, Info&) | 空字符串返回false | 空字符串 |
| ResetSection | bool ResetSection(const string&) | 空字符串返回false | 空字符串 |

---

ステップ二：テスト戦略を策定する

目標：ソースコードの分析に基づいて、テスト範囲、種類、優先度、カバレッジ目標を策定します。

Light Loading（必要な場合のみ読み込みます）：

• test-strategy-method.md - コード特性からテスト戦略への対応表
• framework-quickref.md - テストレベル選択の決定木を参照します

読み込まないでください：build-rules.md、error-matrix.md、test-case-spec.md

戦略決定表

メソッドの種類	テスト範囲の判定	推奨優先度
publicメソッド	必ずテストします	コア機能P1、補助機能P2
staticメソッド	必ずテストします（単独でテスト可能）	P1
virtualメソッド	必ずテストします（派生クラスをカバー）	P1/P2
privateメソッド	直接テストしません	public経由で間接的にカバーします
ロジックの特性	テストの種類を選択します
----	-----------
計算ロジック	FUNC（機能テスト）
パフォーマンス重視	PERF（パフォーマンステスト）
例外処理	RELI（信頼性テスト）
セキュリティチェック	SECU（セキュリティテスト）

出力形式

## 测试策略
| 方法 | 测试判定 | 测试类型 | 优先级 |
| GetSectionInfo | 必测（核心功能） | FUNC | P1 |
| ResetSection | 必测（含状态处理） | FUNC | P1 |
### 覆盖率目标
- 语句覆盖率: ≥80%
- 分支覆盖率: ≥70%
- 函数覆盖率: 100%

---

ステップ三：テストを設計する

目標：ブラックボックステストとホワイトボックステストの手法を組み合わせ、テスト戦略を具体的なテストシナリオの設計に落とし込みます。

Light Loading（必要な場合のみ読み込みます）：

• test-strategy-method.md - パラメーターの境界値設計を参照します
• framework-quickref.md - テストレベルの割り当てを参照します

読み込まないでください：build-rules.md、error-matrix.md、test-case-spec.md

テストシナリオ設計テンプレート（必ず使用）

各メソッドについて、以下の表に記入します。

## [函数名] 测试场景设计

| 编号 | 场景类型 | 场景描述 | 输入数据 | 预期输出 | 测试等级 |
| T01 | 正常 | [具体场景] | [参数值] | [返回值/状态] | Level1 |
| T02 | 异常 | [错误场景] | [触发错误的输入] | [错误码/false] | Level2 |
| T03 | 边界 | [边界值] | [INT_MAX/空字符串等] | [预期行为] | Level2 |
| T04 | 状态 | [状态依赖] | [前置状态描述] | [状态变化结果] | Level2 |

シナリオ設計のポイント

パラメーターの種類	正常入力の設計	境界テストのポイント
int/long	代表的な正の値、負の値、ゼロ値	INT_MIN, INT_MAX, 0, -1
string	空でない文字列	空文字列、長い文字列
ポインター	有効なオブジェクトポインター	nullptr
コンテナー	空でないコンテナー	空のコンテナー、要素が1つのコンテナー

---

ステップ四：テストケースを計画する

目標：テストシナリオを具体的なテストケースに対応付け、命名とレベルの割り当てを決定します。

必須 - ファイル全体を読む：テストケースを計画する前に、naming-convention.mdを必ず読んで、以下を確認します。

• 新規生成時に推奨されるルール：[FunctionName]_[001-999]
• 既存の過去の形式との互換性（分析時のみ参照）
• @tc.nameの命名規則

Light Loading（必要な場合のみ読み込みます）：

• framework-quickref.md - テストレベル選択の決定木
• real-patterns.md - 既存の過去の命名形式を参照します（分析時）

読み込まないでください：build-rules.md、error-matrix.md

テストケース計画テンプレート（必ず使用）

## [函数名] 用例规划

| 用例编号 | 用例名称 | 对应场景 | 测试等级 | 测试宏 |
| 001 | GetSectionInfo_001 | T01 正常获取 | Level1 | HWTEST_F |
| 002 | GetSectionInfo_002 | T02 空字符串 | Level2 | HWTEST_F |

テストマクロ選択の決定表

状況	テストマクロの選択	理由
初期化／クリーンアップが不要	HWTEST(A, B, TestSize.Level1)	独立したテストで、Setup/Teardownは不要です
テストの前後に初期化が必要	HWTEST_F(A, B, TestSize.Level1)	SetUp/TearDownが必要です
マルチスレッドテスト	HWMTEST_F(A, B, C, D)	Dはスレッド数です
パラメーター化テスト	HWTEST_P(A, B, C)	複数のデータセットをテストします

---

ステップ五：テストファイルを作成する

目標：規則に準拠したテストコードファイルを生成します。

必須 - ファイル全体を読む：コードを作成する前に、以下を必ず読んでください。

• test-case-spec.md - テストファイルの完全な構造、禁止されているアンチパターンの一覧
• framework-quickref.md - HWTESTマクロの使い方、テストレベル、@tcコメントの形式
• assertion-gmock-guide.md - Mockの設定（Mockを使用する場合）

Light Loading（必要な場合のみ読み込みます）：

• real-patterns.md - 実際のコード例を参照する必要がある場合
• naming-convention.md - 命名規則の詳細

読み込まないでください：build-rules.md、error-matrix.md（このステップではBUILD.gnとエラーの調査を扱いません）

テストファイル構造テンプレート

必須 — ファイル全体を読む：完全なテンプレート test-template.cpp（約75行）を参照してください。以下が含まれています。

• 著作権表示、ヘッダーのインクルード、名前空間の宣言
• Testクラスの定義（SetUpTestCase/TearDownTestCase/SetUp/TearDown）
• @tcコメントの形式、HWTEST_Fマクロの例、アサーションの使用方法

重要な要素：

• using namespace testing::ext; → 必ず含めてください（HWTESTマクロはこの名前空間にあります）
• SetUp()でテスト対象を初期化 → 必ず実施してください（実施しない場合、SEGFAULTが発生します）
• 命名形式：[FunctionName]_[001]を推奨します。詳しくはnaming-convention.mdを参照してください

命名のポイント（詳しくはnaming-convention.mdを参照してください）：

• 推奨：[FunctionName]_[001]（例：GetSectionInfo_001）
• 以前の形式：TestSuiteFunction_001（例：BBoxDetectorUnitTest001。新規生成時にこの形式をまねることは推奨しません）

アサーションの使用ルール

test-case-spec.mdのアンチパターン禁止リストを参照してください。

基本原則：

• 前提条件のチェック（ポインターが非NULL、状態の検証）→ 必ず ASSERT_*を使用してください（失敗すると処理を終了します）
• 結果の検証（出力／状態の検証）→ 必ず EXPECT_*を使用してください（失敗しても処理を続行します）

---

ステップ6：BUILD.gnを作成する

目標：テストターゲットのビルドルールを設定します。

必須 — ファイル全体を読む：BUILD.gnを作成する前に、build-rules.mdを必ず読んで、以下を理解してください。

• テストテンプレートの種類の選択（ohos_unittestとohos_moduletest）
• depsとexternal_depsの判断ルール
• cflags_ccによるアクセス制御の回避設定
• 完全なBUILD.gnテンプレート

読み込まないでください：framework-quickref.md、error-matrix.md、real-patterns.md（このステップではテストコードや例を扱いません）

BUILD.gnテンプレート

必須 — ファイル全体を読む：完全なテンプレート build-template.gn（約45行）を参照してください。以下が含まれています。

• import文、module_output_pathの設定
• configブロック、ohos_unittestの定義、groupの定義
• deps／external_deps／cflags_cc／definesの完全な例

重要な設定項目：

設定項目	説明	必須か	よくある間違い
import("//build/test.gni")	テストテンプレートの定義	必須（1行目）	記述漏れ→template not found
module_out_path	出力パス。形式は サブシステム/モジュール	必須	絶対パスを使用→エラー
deps	内部依存関係。gtest_mainを含みます	必須	gtest_mainがない→undefined reference to main
external_deps	サブシステム間の依存関係	必要に応じて	形式が誤っている→リンク失敗
cflags_cc	アクセス制御の回避	必要に応じて（テストでprivateにアクセスする場合）	記述漏れ→'xxx' is private

---

ステップ7：検証とデバッグ

目標：テストケースが正しくコンパイルされ、実行できることを確認します。

必須 — ファイル全体を読む：検証する前に、error-matrix.mdを必ず読んで、以下を理解してください。

• コンパイルエラーの一覧（症状→原因→修正方法）
• 実行エラーの一覧
• ゲートによる拒否エラー
• エラーの調査手順

読み込まないでください：framework-quickref.md、build-rules.md、real-patterns.md（前のステップで読み込み済みです）

コンパイルコマンド

./build.sh --product-name <product> --build-target BBoxDetectorUnitTest

よくあるコンパイルエラーの簡易調査

エラー	原因	解決方法
fatal error: xxx.h: No such file	include_dirsの記述漏れ	configブロックにinclude_dirsを追加します
undefined reference to xxx	depsの記述漏れ	depsとexternal_depsを確認します
'xxx' is private	アクセス制御	cflags_ccに -Dprivate=publicを追加します
template 'ohos_unittest' not found	importの記述漏れ	1行目に import("//build/test.gni")を追加します

---

クイックリファレンス

テストレベル、テストマクロ、コメント形式の完全な早見表はframework-quickref.mdを参照してください。以下が含まれています。

• Level0～Level4のレベル定義、選択用の決定木、よくあるシナリオに応じたレベルの割り当て
• HWTEST/HWTEST_Fマクロの構文とゲートによる必須要件
• @tc.typeテストタイプの早見表（FUNC/PERF/RELI/SECU/FUZZ）
• 命名規則の早見表（新規生成で推奨するルールと、既存の従来形式との互換性）

---

References导航

详细文档位于 references/ 目录，按步骤需求加载：

文件	内容	加载时机
test-framework.md	测试框架概述、API版本对应	步骤0 MANDATORY
framework-quickref.md	测试框架速查表（宏+等级+注释+命名）	步骤0-5 MANDATORY/Light
test-case-spec.md	测试文件完整结构、Anti-Patterns	步骤5 MANDATORY
naming-convention.md	命名规范（推荐新规则vs历史兼容）	步骤4 MANDATORY
build-rules.md	BUILD.gn决策规则、完整模板	步骤6 MANDATORY
error-matrix.md	错误排查矩阵（编译+运行+门禁）	步骤7 MANDATORY
assertion-gmock-guide.md	Mock配置（BUILD.gn集成+真实示例）	步骤5 Light（需Mock时）
real-patterns.md	真实仓库示例（标注历史格式）	步骤1-5 Light Loading
test-strategy-method.md	测试策略设计方法	步骤2-3 Light Loading

---

Examples导航

完整模板示例位于 examples/ 目录：

文件	内容	用途
test-template.cpp	完整测试文件示例（版权+类定义+测试用例）	步骤5参考完整代码结构
build-template.gn	完整BUILD.gn示例（import+config+ohos_unittest）	步骤6参考完整配置结构

加载时机：MANDATORY - READ ENTIRE FILE（步骤5、步骤6）

---

输入信息要求

信息	必需性	说明
源码位置	必需	文件路径或函数名称
需求编号	可选	@tc.require填写内容，无需求编号时则为空
测试等级	可选	默认Level1
是否生成BUILD.gn	可选	默认生成

---

开始使用

当用户请求生成测试时，按工作流程执行：

1. 环境确认 → read test-framework.md + framework-quickref.md
2. 分析源码 → 输出源码分析报告
3. 测试策略 → read test-strategy-method.md + framework-quickref.md → 输出策略表格
4. 测试设计 → 输出场景设计表格
5. 用例规划 → read naming-convention.md + framework-quickref.md → 输出用例规划
6. 编写测试文件 → read test-case-spec.md + framework-quickref.md + assertion-gmock-guide.md → 生成.cpp
7. 编写BUILD.gn → read build-rules.md → 生成.gn
8. 验证 → read error-matrix.md → 提供编译命令