低レベル テストの種類

低レベル テスト (LLT) フレームワークでは、次の 2 つの異なる種類のテストを認識します。

• 明示的：モジュールのビルドとターゲットのペアによって定義される自己完結型のテストです。
• 暗黙的：テストされるモジュール内に存在するテストで、ビルドとターゲットのペアを必要としません。

明示的なテスト

明示的テスト は、モジュールのビルドとターゲットのペアによって定義される自己完結型のテストです。明示的テストは、コンパイル時間と実行時間の面で軽量になるように設計されています。これらは明示的な UE モジュールのビルドおよびターゲット ファイルを必要とするため「明示的」と呼ばれています。反対に、それらを必要としないものが「暗黙的」テストになります。つまり、明示的テストには「.Build.cs」と「.Target.cs」ファイルの両方が必要ですが、暗黙的テストには不要です。明示的テストと暗黙的テストの違いについての詳細は、「暗黙的テスト」セクションを参照してください。

明示的テストを作成する

次の手順に従って明示的テストを作成します。

1. 「Source/Programs」ディレクトリに、テストを行うモジュールと同じ名前で新しいディレクトリを作成し、そのディレクトリに「.Build.cs」ファイルを追加します。

   例を確認するには、ディレクトリ「Engine/Source/Programs/LowLevelTests」に「Foundation Tests」という名前の明示的テスト ターゲットがあります。

2. TestModuleRules からモジュール クラスを継承します。
   • プラグイン用にテストを記述している場合は、プラグインの「Source」ディレクトリと同じレベルにある「Tests」ディレクトリに新しいモジュールを配置してください。
   • Catch2 を使用しないテスト モジュールをビルドしている場合は、ベース コンストラクタの 2 番目のパラメータを false に設定して継承してください (base(Target, false)) 。
3. UpdateBuildGraphPropertiesFile を新しい Metadata オブジェクト引数で呼び出します。
   • この情報は、BuildGraph スクリプトのテスト メタデータを生成するために使用されます。
   • BuildGraph スクリプトの生成についての詳細は、「BuildGraph スクリプトのメタデータを生成する」セクションを参照してください。

4. 「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"));
        }
    }
   Copy full snippet

   public class UEModuleTests : TestModuleRules { public UEModuleTests(ReadOnlyTargetRules Target) : base(Target) { PrivateIncludePaths.AddRange( // すべてのプライベート インクルード パス ); PrivateDependencyModuleNames.AddRange( // リンク先へのすべてのプライベート依存関係 ); // その他のタイプの依存関係またはモジュール固有のロジック UpdateBuildGraphPropertiesFile(new Metadata("UEModule", "UE Module")); } }
5. テスト ターゲット ファイル (.Target.cs) を TestTargetRules から継承するクラスで追加します。
6. 必要に応じて、デフォルトのコンパイル フラグをオーバーライドします。
   • 低レベル テストに値を追加しないデフォルト機能のない、最低限のテスト可能なモジュールを目指します。
   • サポートされているプラットフォームを個別に指定できます。デフォルトのプラットフォームは Win64、Mac、Linux、および Android です。
   • プロジェクト固有のグローバル定義を有効にし、ベンチマークのサポートに必要な Catch2 定義を設定できます。

7. 明示的テストの「.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");
        }
    }
   Copy full snippet

   [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
Copy full snippet

[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 オブジェクトで、次のプロパティを設定できます。

TestModuleRules は、基本クラス ModuleRules の多くのデフォルト UBT フラグをオーバーライドします。これにより、ほとんどのテストですぐにコンパイルの肥大化を軽減し、コンパイル時間を最小限に抑えることができます。これらのデフォルト設定はいつでも TestModuleRules 派生クラスでオーバーライドすることができますが、TestModuleRules で直接変更しないでください。

テスト ターゲット ルールのリファレンス

TestTargetRules クラスは、次を使用して TargetRules を拡張します。

TestModuleRules と同様に、TestTargetRules によってデフォルトの UBT フラグが設定されます。これは特に、UObjects、ローカライゼーション、統計などの UE 機能を無効にします。

エンジン テスト

この種類の明示的テストでは、LLT フレームワークでエンジン モジュールを含む明示的テストをコンパイルして実行します。ほとんどのプラットフォームではアセットのロードにクックが必要になるため、エンジン モジュールを使用することができません。そのため、エンジン テストは .Target.cs ファイルに設定されている次のフラグでのみ機能します。

public UEModuleTestsTarget(TargetInfo Target) : base(Target)
{
  bUsePlatformFileStub = true;
  bMockEngineDefaults = true;
}
Copy full snippet

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
Copy full snippet

. └── 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
Copy full snippet

. └── 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 で低レベル テストを記述する方法について学習してください。