低レベル テスト (LLT) フレームワークでは、次の 2 つの異なる種類のテストを認識します。
- 明示的:モジュールのビルドとターゲットのペアによって定義される自己完結型のテストです。
- 暗黙的:テストされるモジュール内に存在するテストで、ビルドとターゲットのペアを必要としません。
明示的なテスト
明示的テスト は、モジュールのビルドとターゲットのペアによって定義される自己完結型のテストです。明示的テストは、コンパイル時間と実行時間の面で軽量になるように設計されています。これらは明示的な UE モジュールのビルドおよびターゲット ファイルを必要とするため「明示的」と呼ばれています。反対に、それらを必要としないものが「暗黙的」テストになります。つまり、明示的テストには「.Build.cs」と「.Target.cs」ファイルの両方が必要ですが、暗黙的テストには不要です。明示的テストと暗黙的テストの違いについての詳細は、「暗黙的テスト」セクションを参照してください。
明示的テストを作成する
次の手順に従って明示的テストを作成します。
-
「
Source/Programs」ディレクトリに、テストを行うモジュールと同じ名前で新しいディレクトリを作成し、そのディレクトリに「.Build.cs」ファイルを追加します。例を確認するには、ディレクトリ「
Engine/Source/Programs/LowLevelTests」に「Foundation Tests」という名前の明示的テスト ターゲットがあります。 TestModuleRulesからモジュール クラスを継承します。- プラグイン用にテストを記述している場合は、プラグインの「
Source」ディレクトリと同じレベルにある「Tests」ディレクトリに新しいモジュールを配置してください。 - Catch2 を使用しないテスト モジュールをビルドしている場合は、ベース コンストラクタの 2 番目のパラメータを false に設定して継承してください (
base(Target, false)) 。
- プラグイン用にテストを記述している場合は、プラグインの「
UpdateBuildGraphPropertiesFileを新しいMetadataオブジェクト引数で呼び出します。- この情報は、BuildGraph スクリプトのテスト メタデータを生成するために使用されます。
- BuildGraph スクリプトの生成についての詳細は、「BuildGraph スクリプトのメタデータを生成する」セクションを参照してください。
-
「
UEModuleTests」という名前の明示的テスト モジュールがあるとすると、明示的テスト「.Build.cs」ファイルは次のようになります。UEModuleTests/UEModuleTests.Build.cs
public class UEModuleTests : TestModuleRules { public UEModuleTests(ReadOnlyTargetRules Target) : base(Target) { PrivateIncludePaths.AddRange( // すべてのプライベート インクルード パス ); PrivateDependencyModuleNames.AddRange( // リンク先へのすべてのプライベート依存関係 ); // その他のタイプの依存関係またはモジュール固有のロジック UpdateBuildGraphPropertiesFile(new Metadata("UEModule", "UE Module")); } } - テスト ターゲット ファイル (
.Target.cs) をTestTargetRulesから継承するクラスで追加します。 - 必要に応じて、デフォルトのコンパイル フラグをオーバーライドします。
- 低レベル テストに値を追加しないデフォルト機能のない、最低限のテスト可能なモジュールを目指します。
- サポートされているプラットフォームを個別に指定できます。デフォルトのプラットフォームは Win64、Mac、Linux、および Android です。
- プロジェクト固有のグローバル定義を有効にし、ベンチマークのサポートに必要な Catch2 定義を設定できます。
-
明示的テストの「
.Target.cs」ファイルは、次のようになります。UEModuleTests/UEModuleTests.Target.cs
[SupportedPlatforms(UnrealPlatformClass.All)] public class UEModuleTestsTarget : TestTargetRules { public UEModuleTestsTarget(TargetInfo Target) : base(Target) { // 他のターゲットと同じようにセットアップします。コンパイル フラグ、グローバル定義などを設定します。 GlobalDefinitions.Add("CATCH_CONFIG_ENABLE_BENCHMARKING=1"); } }
次のステップ
モジュールの「Private」フォルダに C++ テスト ファイルを作成し、それらのファイルに Catch2 テストを記述できるようになりました。テストのヒントとベスト プラクティスについては、「低レベル テストを記述する」のドキュメントを参照してください。最後に、テストをビルドして実行する方法について説明します。低レベル テストをビルドして実行するには、複数の方法があります。「低レベル テストをビルドして実行する」のドキュメントを参照し、開発のニーズに合った最適なメソッドを選択してください。
BuildGraph スクリプトのメタデータ ファイルを生成する
BuildGraph を使用してテストをビルドして実行する場合は、明示的テスト用に BuildGraph スクリプトのメタデータ ファイルの生成を有効にする必要があります。GenerateProjectFiles.bat を介して IDE ソリューションを生成する場合、明示的テスト モジュールによって BuildGraph の .xml ファイルが生成されます。
エンジン構成の設定が、この生成の条件となります。この構成は、Engine/Config/BaseEngine.ini で設定できます。
[LowLevelTestsSettings]
bUpdateBuildGraphPropertiesFile=true
GenerateProjectFiles.bat を実行する場合、テスト メタデータの .xml ファイルがテスト ターゲットごとに「Build/LowLevelTests/<TEST_NAME>.xml」フォルダに生成されます。ここで「<TEST_NAME>」はテスト ターゲットの名前です。NDA プラットフォームの場合、これらのファイルは「Platforms/<PLATFORM_NAME>/Build/LowLevelTests/<TEST_NAME>.xml」に生成されます。追加の「General.xml」ファイルは、オプションでグローバル プロパティを含むテスト ファイルの隣に存在します。
ファイルがすでに存在する場合は、C# で記述された Metadata オブジェクトに従って更新されます。プロジェクト ファイルの生成によってアクセスされるフォルダとファイルは、書き込み可能である必要があります。通常、これらのファイルがソース コントロール下にある場合は読み込み専用であるため、生成前にチェックアウトするか書き込み可能にしてください。
例を確認するには、ディレクトリ「Engine/Build/LowLevelTests」に「Foundation」という名前の .xml ファイルがあります。これは、Foundation Tests 用に生成された BuildGraph のメタデータです。
明示的テストのリファレンス
テスト モジュール ルールのリファレンス
TestModuleRules クラスは、UpdateBuildGraphPropertiesFile を使用して ModuleRules を拡張します。UpdateBuildGraphPropertiesFile は Metadata オブジェクトを受け入れますが、これは BuildGraph のテスト メタデータ .xml ファイルを生成します。Metadata オブジェクトで、次のプロパティを設定できます。
| フィールド | 説明 |
|---|---|
TestName |
テスト固有のプロパティを生成するために BuildGraph スクリプトによって使用されるテストの名前。このフィールドにはスペースを含めないでください。 |
TestShortName |
ビルド システムに表示される際に使用されるテストの短い名前。このフィールドにはスペースを含めることができます。 |
ReportType |
Catch2 のレポート タイプ。最も一般的なレポート タイプはコンソールおよび xml です。Catch2 のレポート タイプの詳細については、Catch2 の外部ドキュメントを参照してください。 |
Disabled |
テストを無効にするかどうかを指定します。true の場合、このテストは BuildGraph グラフから除外されます。 |
InitialExtraArgs |
RunLowLevelTests Gauntlet コマンドの他の引数の前に付加されるコマンドライン引数。これらは通常、一部のテストにのみ適用される Gauntlet 機能が有効な引数です。たとえば、-printreport では、テスト実行の終了時にレポートを stdout に出力します。 |
HasAfterSteps |
true の場合、テストは BuildGraph Macro を「<TEST_NAME>AfterSteps」という名前で提供する必要があります。これにはテスト実行後に必要となるクリーンアップやステップが含まれます。これは残っているテスト データをクリーンアップするデータベース スクリプトを実行することなどが該当します。 |
UsesCatch2 |
このプロパティを使用して、テスト フレームワークを選択できます。一部のテストでは Catch2 を使用せず、GoogleTest などを使用する場合があります。独自のテスト フレームワークを選択する場合は、RunLowLevelTests Gauntlet コマンドにレポートや他の機能のサポートを実装していることを確認してください。 |
PlatformTags |
プラットフォーム固有のタグのリスト。たとえば、これを使用して特定のプラットフォーム上でサポートされていないテストを除外します。 |
PlatformCompilationExtraArgs |
プラットフォームで必要となる可能性がある追加のコンパイル引数。 |
PlatformsRunUnsupported |
例外を追加し、実行サポートが実装されるまで BuildGraph スクリプトでコンパイルのセーフティ ネットとして機能します。たとえば、プラットフォームがコンパイルのみをサポートし、低レベル テストの実行機能が欠如している場合です。 |
TestModuleRules は、基本クラス ModuleRules の多くのデフォルト UBT フラグをオーバーライドします。これにより、ほとんどのテストですぐにコンパイルの肥大化を軽減し、コンパイル時間を最小限に抑えることができます。これらのデフォルト設定はいつでも TestModuleRules 派生クラスでオーバーライドすることができますが、TestModuleRules で直接変更しないでください。
テスト ターゲット ルールのリファレンス
TestTargetRules クラスは、次を使用して TargetRules を拡張します。
| フラグ | 説明 |
|---|---|
bUsePlatformFileStub |
これにより、プラットフォームに依存する FPlatformFile ランタイム インスタンスが IO 操作を無効にするモックに置き換えられます。これを使用して、エンジン モジュールのテスト時におけるアセットのロードを無効にします。このプロパティを設定すると、テストによって追加の IO 模倣を実行するために使用できる |
bMockEngineDefaults |
エンジン モジュールを使用してテストする場合、特定のリソースはデフォルトによって管理されるか、アセット ファイルからロードされます。これらの操作にはアセットのクックが必要です。これをアセットのロードを必要としないテストに使用します。それにより、エンジンのデフォルト マテリアル、ワールド オブジェクト、その他のリソースが模倣されます。 このプロパティを設定すると、 |
bNeverCompileAgainstEngine |
LLT フレームワークのデフォルトの動作では、エンジン モジュールがビルド依存関係グラフにある場合は必ず自動的に bCompileAgainstEngine = true に設定されます。このプロパティは、エンジン モジュールがグラフ内にある場合にもエンジンを使用してコンパイルしないなど、この動作を停止させることができます。 |
bNeverCompileAgainstCoreUObject |
bNeverCompileAgainstEngine と同じですが、CoreUObject 用です。 |
bNeverCompileAgainstApplicationCore |
bNeverCompileAgainstEngine と同じですが、ApplicationCore 用です。 |
bNeverCompileAgainstEditor |
bNeverCompileAgainstEngine と同じですが、UnrealEd 用です。 |
bWithLowLevelTestsOverride |
依存関係モジュールの暗黙的テストを含めるようにこれを設定します。強制的に WITH_LOW_LEVEL_TESTS マクロを true にします。これは通常、暗黙的テスト用に予約済みです。 |
TestModuleRules と同様に、TestTargetRules によってデフォルトの UBT フラグが設定されます。これは特に、UObjects、ローカライゼーション、統計などの UE 機能を無効にします。
エンジン テスト
この種類の明示的テストでは、LLT フレームワークでエンジン モジュールを含む明示的テストをコンパイルして実行します。ほとんどのプラットフォームではアセットのロードにクックが必要になるため、エンジン モジュールを使用することができません。そのため、エンジン テストは .Target.cs ファイルに設定されている次のフラグでのみ機能します。
public UEModuleTestsTarget(TargetInfo Target) : base(Target)
{
bUsePlatformFileStub = true;
bMockEngineDefaults = true;
}
暗黙的テスト
暗黙的テストは、テスト対象と同じモジュールに存在します。すべての暗黙的テストは、WITH_LOW_LEVEL_TESTS 定義を介して条件付きでコンパイルされます。これらは「Private」フォルダなど、モジュール内のどこにでも配置することができますが、モジュールのソース コードとの区別が難しくなることがあります。確実にテストを検出できるようにするには、次の規則に従います。
- 「Tests」フォルダを「Public」および「Private」フォルダと同じレベルのモジュールに作成します。
- ソースファイルと一致するテストがある場合は、「Tests」内にモジュールのフォルダ構造をミラーリングします。
明示的テストで必要とするような明示的なターゲットがないため、これらのテストにはビルドする際に既存のターゲットが必要となります。これには暗黙的テストで Unreal Build Tool を使用して、暗黙的テスト用のテスト実行可能ファイルを生成する必要があります。詳細については、「低レベル テストをビルドして実行する」ドキュメントの「暗黙的なテストをビルドする」セクションを参照してください。
ディレクトリの構造
「SampleModule」という名前で次のようなディレクトリ構造をしたモジュールのサンプルについて検討します。
.
└── SampleModule/
├── Public/
│ └── SampleCode.h
└── Private/
├── SampleCode.cpp
└── SampleModuleSubDirectory/
├── MoreSampleCode.h
└── MoreSampleCode.cpp
暗黙的テストをこのモジュールに追加するには、「Tests」という名前のディレクトリを「Public」および「Private」ディレクトリと同じレベルに作成し、「Private」ディレクトリのディレクトリ構造をミラーリングします。C++ ファイルごとに、対応するテスト ファイルを同じ相対する位置に作成します。その結果、構造は次のようになります。
.
└── SampleModule/
├── Public/
│ └── SampleCode.h
├── Private/
│ ├── SampleCode.cpp
│ └── SampleModuleSubDirectory/
│ ├── MoreSampleCode.h
│ └── MoreSampleCode.cpp
└── Tests/
├── SampleCodeTests.cpp
└── SampleModuleSubDirectory/
└── MoreSampleCodeTests.cpp
この構造では、ファイル「SampleCodeTests.cpp」には「SampleCode.cpp」ファイル用のテストが含まれ、「MoreSampleCodeTests.cpp」には「MoreSampleCode.cpp」ファイル用のテストが含まれています。
次のステップ
どのテストがニーズに適しているかが決まったら、「低レベル テストを記述する」のドキュメントを参照して Unreal Engine で低レベル テストを記述する方法について学習してください。