2022.03.10

【Unity2020対応】CLIから単体テスト(Edit Mode Test)を実行する

はじめに

こんにちは、バーチャルキャストクライアント開発のドロシアです。
先日、バーチャルキャストのクライアント開発プロジェクトのUnityバージョンをUnity2019からUnity2020に移行しました。3/10にリリースしたバージョン2.2.1b以降は、Unity2020でビルドされています。

移行した理由は下記の通りです。

Unity2019のサポートが2022年内に終了予定であること。
Unity2020の新機能を利用できるようになること。(例：C#8.0対応など)

Unity2020への移行にあたり、下記の対応を行いました。

全シェーダーのSingle Pass Instanced対応
Legacy XRからXR Plugin Managementへの移行
各種外部ライブラリのUnity2020対応バージョンへの更新および利用コードの修正
UnityAPIの仕様変更への対応

CLIからEdit Mode Testを実行する

本記事ではその対応のうちの1つである、Unity2020でCLIからEdit Mode Testを実行する方法について解説します。UnityAPIの仕様変更への対応作業の中でも、特に思わぬ躓き方をした作業でした。

Edit Mode Testとは

Unity検証済みパッケージの1つであるUnity TestFramework（Unity Test Runner）で実行できる2種類のテストのうち、エディタ上で実行できるテストです。バーチャルキャストではEdit Mode Testを自動で行うことで、バグの抑止に役立てています。詳細はUnity TestFrameworkのページをご確認ください。

JenkinsでEdit Mode Testを実行するときはCLIを使う

バーチャルキャストではGitHubのPull Request作成時に、Jenkinsからプロジェクトのコンパイルチェック及びEdit Mode Testを行っています。Edit Mode TestはUnityエディタのGUI上で Window/General/Test Runner から実行できますが、Jenkinsから実行したい場合はCLIが使えると便利です。
ここではCLIからEdit Mode Testを実行する2通りの方法と、躓いた点を紹介します。

方法1: コマンドライン引数 `-runTests` から実行する

Unity2020でCLIからEdit Mode Testを実行する方法の1つは、コマンドライン引数 -runTests を用いることです。方法2と比較すると準備が簡単です。

コマンドライン引数の例

'C:\Program Files\Unity\Hub\Editor\2020.3.28f1\Editor\Unity.exe' -batchmode -runTests -projectPath {projectPath}

exeファイルのパス、{projectPath}は各々の環境に合わせて読み替えてください。

-runTests を与えることでテストを実行することができます。また、テストの終了後は自動でエディタが終了します。結果はxml形式でプロジェクトフォルダ直下に生成されます。 -testResults {path} を与えることで任意のパスに出力することもできます。
その他のコマンドライン引数について詳しく知りたい場合はこちらをご参照ください。

方法2：Edit Mode Testを実行するメソッドを用意して、コマンドライン引数 `-executeMethod` から呼び出す

Unity2020でCLIからEdit Mode Testを実行するもう1つの方法は、コマンドライン引数 -executeMethod を用いることです。この方法のメリットはログの出力方法や失敗条件などを細かくカスタマイズできることです。バーチャルキャストクライアントではこちらを採用しました。

スクリプト例

public static class EditorTestExecutor
{
    public static void RunEditorTest()
    {
        var testRunnerApi = ScriptableObject.CreateInstance<TestRunnerApi>();
        var filter = new Filter()
        {
            testMode = TestMode.EditMode
        };

        // 独自に定義したテスト実行時のコールバックを登録する
        testRunnerApi.RegisterCallbacks(new LogCallBacks());

        // runSynchronously をtrueにすることで全てのテストの終了を待機できる
        var settings = new ExecutionSettings(filter)
        {
            runSynchronously = true
        };
        // テスト実行
        testRunnerApi.Execute(settings);
    }
}

sealed class LogCallBacks : ICallbacks
{
    private StackTraceLogType _currentStackTraceLogType;

    // テスト（全体）開始時
    public void RunStarted(ITestAdaptor testsToRun)
    {
        // 現在のスタックトレース出力形式を記憶する
        _currentStackTraceLogType = Application.GetStackTraceLogType(LogType.Log);

        // テスト中はスタックトレースをなくす
        Application.SetStackTraceLogType(LogType.Log, StackTraceLogType.None);
        Debug.Log("EditorTestExecutor started tests.");
    }

    // テスト（全体）終了時
    public void RunFinished(ITestResultAdaptor result)
    {
        Debug.Log($"EditorTestExecutor finished tests. Result: {result.TestStatus}");
        Application.SetStackTraceLogType(LogType.Log, _currentStackTraceLogType);

        // アプリケーションを正常終了する
        EditorApplication.Exit(0);
    }

    // テスト（単体）開始時
    public void TestStarted(ITestAdaptor test)
    {
    }

    // テスト（単体）終了時
    public void TestFinished(ITestResultAdaptor result)
    {
        Debug.Log($"EditorTestExecutor Test {result.TestStatus}: {result.Name}");
        // 出力例: EditorTestExecutor Test Passed: リップシンク不許可のときはリップシンクしない
        if (result.TestStatus == TestStatus.Failed)
        {
            // テストが失敗した場合はエラーを出してアプリケーションを終了する
            EditorApplication.Exit(1);
        }
    }
}

public static class EditorTestExecutor

{

public static void RunEditorTest()

{

var testRunnerApi = ScriptableObject.CreateInstance<TestRunnerApi>();

var filter = new Filter()

{

testMode = TestMode.EditMode

};

// 独自に定義したテスト実行時のコールバックを登録する

testRunnerApi.RegisterCallbacks(new LogCallBacks());

// runSynchronously をtrueにすることで全てのテストの終了を待機できる

var settings = new ExecutionSettings(filter)

{

runSynchronously = true

};

// テスト実行

testRunnerApi.Execute(settings);

}

sealed class LogCallBacks : ICallbacks

{

private StackTraceLogType _currentStackTraceLogType;

// テスト（全体）開始時

public void RunStarted(ITestAdaptor testsToRun)

{

// 現在のスタックトレース出力形式を記憶する

_currentStackTraceLogType = Application.GetStackTraceLogType(LogType.Log);

// テスト中はスタックトレースをなくす

Application.SetStackTraceLogType(LogType.Log, StackTraceLogType.None);

Debug.Log("EditorTestExecutor started tests.");

}

// テスト（全体）終了時

public void RunFinished(ITestResultAdaptor result)

{

Debug.Log($"EditorTestExecutor finished tests. Result: {result.TestStatus}");

Application.SetStackTraceLogType(LogType.Log, _currentStackTraceLogType);

// アプリケーションを正常終了する

EditorApplication.Exit(0);

}

// テスト（単体）開始時

public void TestStarted(ITestAdaptor test)

{

}

// テスト（単体）終了時

public void TestFinished(ITestResultAdaptor result)

{

Debug.Log($"EditorTestExecutor Test {result.TestStatus}: {result.Name}");

// 出力例: EditorTestExecutor Test Passed: リップシンク不許可のときはリップシンクしない

if (result.TestStatus == TestStatus.Failed)

{

// テストが失敗した場合はエラーを出してアプリケーションを終了する

EditorApplication.Exit(1);

}

コマンドライン引数例

'C:\Program Files\Unity\Hub\Editor\2020.3.28f1\Editor\Unity.exe' -batchmode -projectPath {projectPath} -executeMethod {namespace}.EditorTestExecutor.RunEditorTest"

exeファイルのパス、{projectPath}、{namespace}は各々の環境に合わせて読み替えてください。

Jenkinsでのコンソール出力例

下記はEdit Mode Testに失敗した場合の例です。

（テスト名をモザイク処理しています）
このように、どの単体テストで失敗したかを簡単に確認できるようになりました。

ポイント1 `EditorApplication.Exit(1)` による異常終了

EditorApplication.Exit(int returnValue) に 0 を渡すことでUnityEditorを正常終了し、 1 を渡すことでエラーを返しながら終了することができます。上記のスクリプト例では、単体テストに失敗したときに 1 を渡すことでJenkinsでジョブをエラー扱いにできるようにしています。

ポイント2 `runSynchronously` フラグによる同期実行

ExecutionSettingsのrunSynchronouslyフラグを true にしましょう。このフラグが未指定もしくは false だとテスト終了時のコールバックが別スレッドで実行され、EditorApplication.Exit(0)でエディタを終了することができません。

躓いた点: `-runEditorTests` が使えなくなった

Unity2019まで使えたEdit Mode Testを実行するコマンドライン引数 -runEditorTests は廃止されたようです。Unity2020環境でこのコマンドライン引数を与えて実行し、エディターが起動したまま終了せず後続のテストがすべてエラーになるというトラブルが発生し、しばらく原因がわからず頭を悩ませていました。

Unity2018とUnity2020のそれぞれのコマンドライン引数のドキュメントを読んでいたところ、Unity2020では -runEditorTests の項目がなくなっていることに気付きました。
https://docs.unity3d.com/ja/2018.4/Manual/CommandLineArguments.html
https://docs.unity3d.com/ja/2020.3/Manual/CommandLineArguments.html
Unity2019のドキュメントでもなくなっているのですが、実行はできていたので、互換性は保たれていたようです。
https://docs.unity3d.com/ja/2019.4/Manual/CommandLineArguments.html

Unity2020に対応した方法はUnity Test Frameworkのページで解説されていました。
https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/manual/reference-command-line.html

まとめ

本記事ではUnity2020でCLIからEditorTestを実行する際の2つの方法について解説しました。皆様の快適な開発環境の構築にお役立て頂けましたら幸いです。

Category
ドロシア /
技術