Custom attributes, comparers, and constraints for writing more expressive tests in Unity Test Framework.
Required Unity 2019 LTS or later.

BuildSceneAttribute is a NUnit test attribute class that build a scene before running the test on player.

This attribute has the following benefits:

• Scenes that are NOT in "Scenes in Build" can be specified.
• The scene file path can be specified as a relative path from the test class file.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [BuildScene("Assets/Path/To/Tests/Scenes/TestScene.unity")]
    public void MyTestMethod()
    {
        // Setup before load scene

        // Load scene
        await SceneManagerHelper.LoadSceneAsync("Assets/Path/To/Tests/Scenes/TestScene.unity");

        // Excercise the test
    }

    [Test]
    [BuildScene("../../Scenes/SampleScene.unity")]
    public void UsingRelativePath()
    {
        // snip
    }
}

CreateSceneAttribute is an NUnit test attribute class to create a new scene and activate it before running the test.

This attribute has the following benefits:

• Can use the same code for running Edit Mode tests, Play Mode tests in Editor, and on Player

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [CreateScene(camera: true, light: true)]
    public void MyTestMethod()
    {
        var camera = GameObject.Find("Main Camera");
        Assert.That(camera, Is.Not.Null);

        var light = GameObject.Find("Directional Light");
        Assert.That(light, Is.Not.Null);
    }
}

FocusGameViewAttribute is an NUnit test attribute class to focus GameView or SimulatorWindow before running the test.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [FocusGameView]
    public void MyTestMethod()
    {
        // e.g., Test using InputEventTrace of Input System package.
    }
}

GameViewResolutionAttribute is an NUnit test attribute class to set custom resolution to GameView before running the test.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with async Test and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [UnityTest]
    [GameViewResolution(640, 480, "VGA")]
    public IEnumerator MyTestMethod()
    {
        yield return null; // Wait for one frame to apply resolution.

        // e.g., Test using GraphicRaycaster.
    }
}

GizmosShowOnGameViewAttribute is an NUnit test attribute class to show/hide Gizmos on GameView during the test running.

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [GizmosShowOnGameView(true)]
    public void MyTestMethod()
    {
        // Show Gizmos on GameView during the test running.
    }
}

IgnoreBatchModeAttribute is an NUnit test attribute class to skip the test execution when run tests with -batchmode from the commandline.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [UnityTest]
    [IgnoreBatchMode("Using WaitForEndOfFrame.")]
    public IEnumerator MyTestMethod()
    {
        // e.g., Test needs to take a screenshot.

        yield return new WaitForEndOfFrame();
        ImageAssert.AreEqual(expectedTexture, Camera.main, settings);
    }
}

IgnoreWindowModeAttribute is an NUnit test attribute class to skip the test execution when run tests on Unity editor window.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [IgnoreWindowMode("Requires command line arguments")]
    public void MyTestMethod()
    {
        var args = Environment.GetCommandLineArgs();
        Assert.That(args, Does.Contain("-arg1"));
    }
}

LoadAssetAttribute is a NUnit test attribute class that loads an asset file at the specified path into the field before running the test.

This attribute has the following benefits:

• The same code can be used for Edit Mode tests and Play Mode tests in Editor and on Player.
• The asset file path can be specified as a relative path from the test class file.

This attribute can be placed on the field only.

Usage:

[TestFixture]
public class MyTestClass
{
    [LoadAsset("Assets/Path/To/Tests/Prefabs/Cube.prefab")]
    private GameObject _prefab;

    [LoadAsset("../../Prefabs/Sphere.prefab")]
    private GameObject _relative;

    [OneTimeSetUp]
    public void OneTimeSetUp()
    {
        LoadAssetAttribute.LoadAssets(this);    // Must call this method to load assets.
    }

    [Test]
    public void MyTestMethod()
    {
        Assume.That(_prefab, Is.Not.Null);  // Already loaded and set to the field.
    }
}

LoadSceneAttribute is a NUnit test attribute class that loads a scene before running the test.

This attribute has the following benefits:

• The same code can be used for Edit Mode tests and Play Mode tests in Editor and on Player.
• Scenes that are NOT in "Scenes in Build" can be specified.
• The scene file path can be specified as a relative path from the test class file.

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [LoadScene("Assets/Path/To/Tests/Scenes/TestScene.unity")]
    public void MyTestMethod()
    {
        var cube = GameObject.Find("Cube in TestScene");
        Assert.That(cube, Is.Not.Null);
    }

    [Test]
    [LoadScene("../../Scenes/SampleScene.unity")]
    public void UsingRelativePath()
    {
        // snip
    }
}

RecordVideoAttribute is an NUnit test attribute class for recording a video while running the test.

Default save path is "Application.persistentDataPath/TestHelper/Screenshots/TestContext.Test.Name.mp4". You can specify the save directory by arguments. Directory can also be specified by command line arguments -testHelperScreenshotDirectory.

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [RecordVideo]
    public void MyTestMethod()
    {
        // Recording a video while running the test.
    }
}

TakeScreenshotAttribute is an NUnit test attribute class to take a screenshot and save it to a file after running the test.

Default save path is "Application.persistentDataPath/TestHelper/Screenshots/TestContext.Test.Name.png". You can specify the save directory and/or filename by arguments. Directory can also be specified by command line arguments -testHelperScreenshotDirectory.

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [TakeScreenshot]
    public void MyTestMethod()
    {
        // Take screenshot after running the test.
    }
}

TimeScaleAttribute is an NUnit test attribute class to change the Time.timeScale during the test running.

This attribute can be placed on the test method only. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [TimeScale(2.0f)]
    public void MyTestMethod()
    {
        // Running at 2x speed.
    }
}

UnityVersionAttribute is an NUnit test attribute class to skip the test run if Unity version is older and/or newer than specified.

This attribute can be placed on the test method, the test class (TestFixture), and the test assembly. Can be used with sync Test, async Test, and UnityTest.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    [UnityVersion(newerThanOrEqual: "2022")]
    public void MyTestMethod()
    {
        // Test run only for Unity 2022.1.0f1 or newer (include specified version).
    }

    [Test]
    [UnityVersion(olderThan: "2019.4.0f1")]
    public void MyTestMethod()
    {
        // Test run only for Unity older than 2019.4.0f1 (exclude specified version).
    }
}

GameObjectNameComparer is a NUnit test comparer class that compares two GameObject by name.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    public void MyTestMethod()
    {
        var actual = GameObject.FindObjectsOfType<GameObject>();
        Assert.That(actual, Does.Contain(new GameObject("test")).Using(new GameObjectNameComparer()));
    }
}

XDocumentComparer is a NUnit test comparer class that loosely compares XDocument.

It only compares the attributes and values of each element in the document unordered. XML declarations and comments are ignored.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    public void MyTestMethod()
    {
        var x = XDocument.Parse(@"<root><child>value1</child><child attribute=""attr"">value2</child></root>");
        var y = XDocument.Parse(@"<?xml version=""1.0"" encoding=""utf-8""?>
<root><!-- comment --><child attribute=""attr"">value2</child><!-- comment --><child>value1</child></root>");
        // with XML declaration, comments, and different order

        Assert.That(x, Is.EqualTo(y).Using(new XDocumentComparer()));
    }
}

XmlComparer is a NUnit test comparer class that compares two string as an XML document.

It only compares the attributes and values of each element in the document unordered. XML declarations and comments are ignored, and white spaces, tabs, and newlines before and after the value are ignored.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    public void MyTestMethod()
    {
        var x = @"<root><child>value1</child><child attribute=""attr"">value2</child></root>";
        var y = @"<?xml version=""1.0"" encoding=""utf-8""?>
<root>
  <!-- comment -->
  <child attribute=""attr"">
    value2
  </child>
  <!-- comment -->
  <child>
    value1
  </child>
</root>";

        Assert.That(x, Is.EqualTo(y).Using(new XmlComparer()));
    }
}

DestroyedConstraint tests that a GameObject is destroyed.

Usage:

using Is = TestHelper.Constraints.Is;

[TestFixture]
public class MyTestClass
{
    [Test]
    public void MyTestMethod()
    {
        var actual = GameObject.Find("Cube");
        GameObject.DestroyImmediate(actual);

        Assert.That(actual, Is.Destroyed);
    }
}

TestHelper.Statistics namespace provides utilities for statistical testing, including assertions for pseudo-random number generators (PRNG) and statistical summary tools.

Experiment is a class for running experiments of PRNG.

Usage:

[TestFixture]
public class MyStatisticsTest
{
    [Test]
    public void Experiment_2D6()
    {
        var sampleSpace = Experiment.Run(
            () => DiceGenerator.Roll(2, 6), // 2D6
            1 << 20); // 1,048,576 times

        Assert.That(sampleSpace.Max, Is.EqualTo(12));
        Assert.That(sampleSpace.Min, Is.EqualTo(2));
    }
}

DescriptiveStatistics is a class for calculate statistical summaries and plotting a histogram.

Usage:

[TestFixture]
public class MyStatisticsTest
{
    [Test]
    public void DescriptiveStatistics_2D6()
    {
        const int TrialCount = 1 << 20; // 1,048,576 times
        const double Tolerance = TrialCount * 0.001d;

        var sampleSpace = Experiment.Run(
            () => DiceGenerator.Roll(2, 6), // 2D6
            TrialCount);

        var statistics = new DescriptiveStatistics<int>();
        statistics.Calculate(sampleSpace);
        Debug.Log(statistics.GetSummary()); // Write to console

        Assert.That(statistics.PeakFrequency, Is.EqualTo(TrialCount / 6).Within(Tolerance));
        Assert.That(statistics.ValleyFrequency, Is.EqualTo(TrialCount / 36).Within(Tolerance));
        Assert.That(statistics.MedianFrequency, Is.EqualTo(TrialCount / 12).Within(Tolerance));
        Assert.That(statistics.MeanFrequency, Is.EqualTo(TrialCount / 11).Within(Tolerance));
    }
}

Console output example:

Experimental and Statistical Summary:
  Sample size: 1,048,576
  Maximum: 12
  Minimum: 2
  Peak frequency: 174,554
  Valley frequency: 29,070
  Median frequency: 87,490
  Mean frequency: 95,325.09
  Histogram: ▁▂▃▅▆█▆▅▃▂▁
  (Each bar represents the frequency of values in equally spaced bins.)

PixelPlot is class that outputs a pixel plot image file.

Default save path is "Application.persistentDataPath/TestHelper/Statistics/TestContext.Test.Name.png". You can specify the save directory and/or filename by arguments. Directory can also be specified by command line arguments -testHelperStatisticsDirectory.

Usage:

[TestFixture]
public class MyStatisticsTest
{
    [Test]
    public void PixelPlot()
    {
        var sampleSpace = Experiment.Run(
            () => UnityEngine.Random.value,
            1 << 16); // 256x256

        var pixelPlot = new PixelPlot<float>();
        pixelPlot.Plot(sampleSpace);
        pixelPlot.WriteToFile("Path/To/Directory", "PixelPlot.png");
    }
}

Image output example; Left: generated by strong PRNG, Right: generated by weak (short period) PRNG:

The classes in the TestHelper.RuntimeInternals assembly can be used from the runtime code because it does not depend on com.unity.test-framework.

SceneManagerHelper is a utility class to load the scene file.

This method has the following benefits:

• The same code can be used for Edit Mode tests and Play Mode tests in Editor and on Player.
• The scene file path can be specified as a relative path from the test class file.

Usage:

[TestFixture]
public class MyTestClass
{
    [Test]
    public void MyTestMethod()
    {
        // Setup before load scene

        // Load scene
        await SceneManagerHelper.LoadSceneAsync("Assets/Path/To/Tests/Scenes/TestScene.unity");

        // Excercise the test
    }

    [Test]
    public void UsingRelativePath()
    {
        // Setup before load scene

        // Load scene
        await SceneManagerHelper.LoadSceneAsync("../../Scenes/SampleScene.unity");

        // Excercise the test
    }
}

ScreenshotHelper is a utility class to take a screenshot and save it to a file.

Default save path is "Application.persistentDataPath/TestHelper/Screenshots/TestContext.Test.Name.png". (Replace TestContext.Test.Name to caller method name when called outside a test context.) You can specify the save directory and/or filename by arguments. Directory can also be specified by command line arguments -testHelperScreenshotDirectory.

Usage:

[TestFixture]
public class MyTestClass
{
    [UnityTest]
    public IEnumerator MyTestMethod()
    {
        yield return ScreenshotHelper.TakeScreenshot();
    }

    [Test]
    public async Task MyTestMethodAsync()
    {
        await ScreenshotHelper.TakeScreenshotAsync();   // Required Unity 2023.3 or newer
    }

    [Test]
    public async Task MyTestMethodAsync()
    {
        var coroutineRunner = new GameObject().AddComponent<CoroutineRunner>();
        await ScreenshotHelper.TakeScreenshot().ToUniTask(coroutineRunner); // Required UniTask package
    }

    private class CoroutineRunner : MonoBehaviour { }
}

The PathHelper.CreateTemporaryFilePath method provides utilities for creating a temporary file path in running tests.
By default, the path is named by the test name in the directory pointed to by Application.temporaryCachePath.

Usage:

namespace MyNamespace
{
  [TestFixture]
  public class MyTestClass
  {
    [Test]
    public void MyTestMethod()
    {
      var path = PathHelper.CreateTemporaryFilePath(extension: "txt");
      File.WriteAllText(path, "test file");
      // write to {Application.temporaryCachePath}/MyTestMethod.txt

      var path2 = PathHelper.CreateTemporaryFilePath(extension: "txt");
      File.WriteAllText(path2, "test file");
      // write to {Application.temporaryCachePath}/MyTestMethod_1.txt
    }

    [Test]
    public void MyTestMethod2()
    {
      var path = PathHelper.CreateTemporaryFilePath(namespaceToDirectory: true);
      File.WriteAllText(path, "test file");
      // write to {Application.temporaryCachePath}/MyNamespace/MyTestClass/MyTestMethod2
    }
  }
}

Select menu item Window > Test Helper > Open Persistent Data Directory, which opens the directory pointed to by Application.persistentDataPath in the Finder/ File Explorer.

Select menu item Window > Test Helper > Open Temporary Cache Directory, which opens the directory pointed to by Application.temporaryCachePath in the Finder/ File Explorer.

If you specify path with -testHelperJUnitResults command line option, the test result will be written in JUnit XML format when the tests are finished.

If you specify display resolution standards (e.g., VGA) with the -testHelperGameViewResolution command line option, the GameView resolution is set to the specified size when starting the tests.

Or, you can specify width and height with -testHelperGameViewWidth and -testHelperGameViewHeight command line options.

1. Open the Project Settings window (Editor > Project Settings) and select Package Manager tab (figure 1.)
2. Click + button under the Scoped Registries and enter the following settings:
   1. Name: package.openupm.com
   2. URL: https://package.openupm.com
   3. Scope(s): com.nowsprinting
3. Open the Package Manager window (Window > Package Manager) and select My Registries tab (figure 2.)
4. Select Test Helper and click the Install button

Figure 1. Scoped Registries setting in Project Settings window

Figure 2. My Registries in Package Manager window

1. Open your test assembly definition file (.asmdef) in the Inspector window
2. Add TestHelper into Assembly Definition References

MIT License

Open an issue or create a pull request.

Be grateful if you could label the PR as enhancement, bug, chore, and documentation. See PR Labeler settings for automatically labeling from the branch name.

Clone this repository as a submodule under the Packages/ directory in your project.

git submodule add [email protected]:nowsprinting/test-helper.git Packages/com.nowsprinting.test-helper

Generate a temporary project and run tests on each Unity version from the command line.

make create_project
UNITY_VERSION=2019.4.40f1 make -k test

The release process is as follows:

1. Run Actions > Create release pull request > Run workflow
2. Merge created pull request

Then, will do the release process automatically by Release workflow. After tagging, OpenUPM retrieves the tag and updates it.