次のツールを使用して、低レベル テストをビルドして実行できます。
これらのツールのいずれかを使用して、明示的なテストをビルドして実行できます。可能な限り、BuildGraph を使用して明示的なテストをビルドして実行することをお勧めします。現在、暗黙的なテストは Unreal Build Tool でのみビルドして実行することができます。
| 利用可能なテスト タイプ | Visual Studio | Unreal Build Tool | BuildGraph |
|---|---|---|---|
| 暗黙的なテスト | 不可能 | 可能 | 不可能 |
| 明示的なテスト | 可能 | 可能 | 可能 |
このページの最後にある「例：Foundation Tests」セクションでは、Unreal Engine に備わっている低レベル テストのプロジェクトをビルドして実行する方法について説明します。
Visual Studio
明示的なテストを直接デスクトップ プラットフォームの Visual Studio でビルドして実行することができます。
- UnrealVS をインストールします。
- これはオプションですが、テストの発見可能性が向上するため、インストールを強く推奨します。UnrealVS の詳細については、「UnrealVS 拡張」のドキュメントを参照してください。
- Visual Studio でテスト プロジェクトを ビルド して実行可能ファイルを生成します。
- Visual Studio のビルトイン テスト アダプタにより、Catch2 実行可能ファイル内のテストが検出されます。UnrealVS を使用してビルドするか、Visual Studio のインターフェースを介して直接ビルドすることができます。
- テストは テスト エクスプローラー に表示されます。メニューから [Test (テスト)] > [Test Explorer (テスト エクスプローラー)] を選択します。ここからテストを実行して、ソース コードに移動することができます。
- テスト エクスプローラーにテストがない場合、ビルドの手順 2 で実行可能ファイルが更新されていない可能性があります。その場合は、テスト プロジェクトで [Rebuild (再ビルド)] を実行し、この問題を修正します。
Unreal Build Tool
ビルド
明示的なテスト
Unreal Build Tool を使用して明示的なテストをビルドすることができます。ターゲット クラス MyTestsTarget を使用して明示的なテスト ケースをビルドすると、次のようになります。
.\Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe MyTestsTarget Development Win64
上のサンプルで使用されている構成は Development で、プラットフォームは Win64 です。すべての構成およびプラットフォームがサポートされています。
暗黙的なテスト
暗黙的なテストをビルドするには、たとえば UnrealEditor などの既存のターゲットと、指定したターゲットに基づいてプログラム ターゲットをビルドする -Mode=Test を使用します。
.\Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe UnrealEditor Development Win64 -Mode=Test
テスト モードを使用すると、依存関係グラフのすべてのモジュールに含まれているテストが 1 つの実行可能なプログラムに収集されます。Unreal Build Tool は現在、暗黙的なテストをビルドする唯一の方法です。
実行
先ほどの UBT コマンドでテストの実行可能ファイルがビルドされます。テスト実行可能ファイルは通常、ターゲットが出力するものと同じ「Binaries/<PLATFORM>」などのベース フォルダにありますが、これはターゲットと同じ名前のフォルダの下にあります。上述の方法で Unreal Build Tool を使用してビルドした後、コマンドラインから低レベル テストの実行可能ファイルを実行する例を次に示します。
MyTests.exe --log --debug --sleep=5 --timeout=10 -r xml -# [#MyTestFile][Core] --extra-args -stdout
このコマンドラインでは、次の処理が行われます。
LLT 引数：
--log --debug --sleep=5 --timeout=10
- UE のログ記録を有効にします。
- 低レベル テストのデバッグ メッセージ (テストの開始、終了、完了時間) が出力されます。
- テストの実行前に 5 秒待ちます。
- テストごとのタイムアウトを 10 分設定します。
Catch2 引数：
-r xml -# [#MyTestFile][Core]
- XML レポートを有効にします。
- ファイル名をフィルタ タグとして使用し、ファイル「
MyTestFile」から[Core]がタグ付けされているすべてのテストを選択します。
UE 引数：
--extra-args -stdout
-stdoutを UE コマンドラインに設定します。
コマンドラインのリファレンス
ビルドが完了すると、送信前テストの実行や、継続的インテグレーション/継続的デリバリー (CI/CD) パイプラインの一部として、テストの実行可能ファイルを使用することができます。LLT 実行可能ファイルは、数多くのユース ケースをカバーするさまざまなコマンドライン オプションをサポートします。
| 引数 | フラグまたはキー/値のペア | 説明 |
|---|---|---|
--global-setup |
フラグ | UE のコア コンポーネントを初期化するグローバル セットアップを実行します。 |
--no-global-setup |
フラグ | これを使用してグローバル セットアップを無効にします。 |
--log |
フラグ | UE ログ出力を有効にします。 |
--no-log |
フラグ | UE ログ出力を無効にします。 |
--debug |
フラグ | 現在のテストの実行について LowLevelTestsRunner ロガー デバッグ メッセージを有効にします。 |
--mt |
フラグ | bMultiThreaded=true を設定します。これを使用して、マルチスレッドの環境を構成します。 |
--no-mt |
フラグ | bMultiThreaded=false を設定します。これを使用して、シングルスレッドの環境を構成します。 |
--wait |
フラグ | 終了する前にユーザーの入力を待機します。 |
--no-wait |
フラグ | 終了する前にユーザーの入力を待機しません。これはデフォルトの動作です。 |
--attach-to-debugger, --waitfordebugger |
フラグ | アプリケーションは、グローバルなセットアップ フェーズの前にデバッガの接続を待機します。 |
--buildmachine |
フラグ | UE グローバル変数の bIsBuildMachine=true を設定します。CI/CD の動作を制御するため、開発に使用されます。 |
--sleep=<SECONDS> |
キー/値のペア | グローバルなセットアップ フェーズの前に、スリープ期間を秒単位で設定します。同期により、起動の前にテストを待機する必要がある場合に便利です。 |
--timeout=<MINUTES> |
キー/値のペア | テストごとのタイムアウトを分単位で設定します。1 つのテスト ケース中にタイムアウトに達する場合は、エラー メッセージが表示されます。 |
--reporter= xxx -r xxx |
両方 | Catch2 のコマンドライン オプション。上記のいずれにも該当せず、「--extra-args」の後でもないコマンドライン オプションは、自動的に Catch2 に送信されます。 Catch2 コマンドライン オプションの完全なリファレンスについては、外部の Catch2 GitHub リポジトリにある「Catch2 Command-Line」のドキュメントを参照してください。 |
--extra-args |
フラグ | このオプションの後に設定されるすべての引数は、UE の FCommandLine に設定されます。機能をコマンドラインから有効にする場合に便利です。 |
上記の最後の 2 つのエントリで説明したように、--extra-args までのリファレンスに列挙されていない引数はすべて、Catch2 コマンドライン引数リストに直接送信されます。
BuildGraph
テストは、BuildGraph スクリプトでビルドして実行することが推奨されています。基本的なコマンドは次のようになります。
.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Run Low Level Tests"
Windows、Mac および Linux では、同様のコマンドが使用できます。
Engine/Build/LowLevelTests.xml にあるスクリプトは、テスト メタデータ ファイルとともに動作します。メタデータ ファイルを生成するには、「低レベル テストの種類」ドキュメントの「BuildGraph スクリプトのメタデータ ファイルを生成する」セクションを参照してください。このスクリプトが正しく実行されるには、テスト メタデータ スクリプトが正しく生成されていることが条件となるため、ファイルが予想される場所に生成されていることを確認してください。テスト メタデータの .xml ファイルはすべて LowLevelTests.xml に含まれ、このメタデータによってビルド グラフ内のノードの実行が管理されます。
BuildGraph スクリプトの一般的な使用方法を次にいくつか示します。
-
Windows で「
MyTest」という名前のテストを実行します。.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="MyTest Tests Win64" -
デフォルト (Development (開発)) 以外の特定のビルド コンフィギュレーションを設定します。たとえば、次のようにしてコンフィギュレーションを Debug に設定します。
.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Foundation Tests Win64" -set:Configuration="Debug" -
Debug コンフィギュレーションでテストをビルドして起動し、デバッガが接続されるのを待機します。
.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Foundation Tests Win64" -set:Configuration="Debug" -set:AttachToDebugger=true -
プラットフォームのツールが、指定した名前や IP のデバイスへのアプリケーションのデプロイをサポートしている場合、そのデバイス上に起動することができます。また、このコマンドは、プラットフォームにリモート デバッグ ツールがある場合、
AttachToDebuggerとともに使用することができます。.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Foundation Tests Win64" -set:Device="<IP_OR_NAME_OF_DEVICE>" -
ターゲット プラットフォーム用に Catch2 をビルドします。
.\RunUAT.bat BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Catch2 Build Library Win64"
例：Foundation Tests
概要
Foundation Tests プロジェクトは、「Programs/LowLevelTests」フォルダの Visual Studio Solution Explorer にあります。
これは、Core、Cbor、CoreUObjects などのコア UE モジュールからの暗黙的なテストを再統合するために設計されています。これは明示的なテスト スイートとして設定されますが、ターゲット ファイルに bWithLowLevelTestsOverride = true フラグを設定することにより、依存モジュールからの暗黙的なテストを収集することができます。たとえば、Engine/Source/Runtime/Core/Tests から Core の暗黙的なテストを収集します。
新しいテストを Foundation Tests プロジェクトに追加するには、依存モジュールのいずれかに暗黙的なテストを作成します。テストは、.Build.cs ファイルに指定されているモジュールだけでなく、依存関係グラフ全体から選択されます。たとえば Core モジュールは、Engine/Source/Developer/DerivedDataCache/Tests で定義されているテストを含む DerivedDataCache モジュールに依存しています。これらも最終的な実行可能ファイルに収集されます。
Tests/TestGroupEvents.cpp にはライフサイクル イベントが定義されています。これらのイベントはテストの正しい実行に影響を与えるため、実行する順序には注意してください。セットアップが不足していたり、セットアップの配置場所が間違っていたりすると、ランタイム エラーが発生する可能性があります。これはティアダウン イベントも同様です。
ビルドして実行する
Visual Studio から、または BuildGraph を使用してテストをビルドし、実行します。
Visual Studio
次の手順で、Visual Studio から Foundation Tests をビルドします。
- 簡単にテストをビルドできるように、UnrealVS がインストールされていることを確認します。
- 詳細については、「UnrealVS 拡張」のドキュメントを参照してください。
- Visual Studio のメニューに移動して、[Solution Configurations (ソリューション構成)] を見つけます。
- [Solution Configurations] ドロップダウンで [Tests (テスト)] を選択します。
- UnrealVS ツールバーで [Startup Project (スタートアップ プロジェクト)] ドロップダウンを見つけて、[FoundationTests] を選択します。
- Visual Studio メニュー バーで、[Build (ビルド)] > [Build Solution (ソリューションをビルド)] を選択します。
これにより、Foundation Tests とその依存関係がビルドされます。Foundation Tests を実行するには、ターミナルまたはコマンド プロンプトから Engine/Binaries/Win64/FoundationTests ディレクトリに移動して、FoundationTests.exe 実行可能ファイルを ./FoundationTests を使用して実行します。
すべてが正しく動作すると、ターミナル ウィンドウにいくつかのログ テキストが表示され、すべてのテストにパスすると、最後に「All tests passed…」というダイアログが表示されます。
BuildGraph
Foundation Tests をビルドして実行するには、直接プロジェクトに移動し、次のコマンドを実行します。
.\RunUAT BuildGraph -Script="Engine/Build/LowLevelTests.xml" -Target="Foundation Tests Win64"
テストの実行用にさまざまなプラットフォーム、ビルド コンフィギュレーション、デバイス ターゲットを指定したり、デバッガが接続されるまでテストを待機させたりすることができます。
