Namespace UnityEngine.TestTools

Classes

ConditionalIgnoreAttribute

This attribute is an alternative to the standard Ignore attribute in NUnit. It allows for ignoring tests only under a specified condition. The condition evaluates during OnLoad, referenced by ID.

EnterPlayMode

Implements IEditModeTestYieldInstruction. Creates a yield instruction to enter Play Mode.

ExitPlayMode

Implements IEditModeTestYieldInstruction. A new instance of the class is a yield instruction to exit Play Mode.

LogAssert lets you expect Unity log messages that would otherwise cause the test to fail. A test fails if Unity logs a message other than a regular log or warning message. Use LogAssert to check for an expected message in the log so that the test does not fail when Unity logs the message.

Use LogAssert.Expect before running the code under test, as the check for expected logs runs at the end of each frame.

A test also reports a failure, if an expected message does not appear, or if Unity does not log any regular log or warning messages.

MonoBehaviourTest<T>

This is a wrapper that allows running tests on MonoBehaviour scripts. Inherits from CustomYieldInstruction MonoBehaviourTest is a coroutine and a helper for writing MonoBehaviour tests. Yield a MonoBehaviourTest when using the UnityTest attribute to instantiate the MonoBehaviour you wish to test and wait for it to finish running. Implement the IMonoBehaviourTest interface on the MonoBehaviour to state when the test completes.

ParameterizedIgnoreAttribute

This attribute is an alternative to the standard Ignore attribute in NUnit. It allows for ignoring tests based on arguments which were passed to the test method.

PostBuildCleanupAttribute

PostBuildCleanup attributes run if the respective test or test class is in the current test run. The test is included either by running all tests or setting a filter that includes the test. If multiple tests reference the same pre-built setup or post-build cleanup, then it only runs once.

PrebuildSetupAttribute

PrebuildSetup attribute run if the test or test class is in the current test run. The test is included either by running all tests or setting a filter that includes the test. If multiple tests reference the same pre-built setup or post-build cleanup, then it only runs once.

PreservedValuesAttribute

Like the ValuesAttribute it is used to provide literal arguments for an individual parameter of a test. It has the Preserve attribute added, allowing it to persist in players build at a high stripping level.

RecompileScripts

RecompileScripts is an IEditModeTestYieldInstruction that you can yield in Edit Mode tests. It lets you trigger a recompilation of scripts in the Unity Editor.

RequiresPlayModeAttribute

Use this attribute to instruct the test framework to run tests in PlayMode or EditMode when run in the Editor, independent of the assembly configuration. The attribute can be applied to a single test method, a test fixture, or the whole assembly. If specified on multiple levels, the test follows the attribute on the lowest level. E.g. if the assembly has [RequiresPlayMode(false)], which runs all tests in EditMode, and the test fixture has [RequiresPlayMode], which runs all tests in PlayMode, then a test in that fixture will run in PlayMode, taking the configuration from the fixture. The attribute allows for two new combinations:

Editor-only tests that always run in PlayMode.
Tests that can run on platforms, but that run without entering PlayMode when run in the Editor.

By default, any Editor-only assembly has the equivalent of [RequiresPlayMode(false)] applied, while an assembly with platform support has the equivalent of [RequiresPlayMode] applied.

TestMustExpectAllLogsAttribute

The presence of this attribute makes the Test Runner expect every single log. By default, the runner only fails automatically on any error logs, so this adds warnings and infos as well. It is the same as calling LogAssert.NoUnexpectedReceived() at the bottom of every affected test.

This attribute can be applied to test assemblies (affects every test in the assembly), fixtures (affects every test in the fixture), or on individual test methods. It is also automatically inherited from base fixtures.

The MustExpect property (on by default) lets you selectively enable or disable the higher level value. For example when migrating an assembly to this more strict checking method, you might attach [assembly:TestMustExpectAllLogs] to the assembly itself, but whitelist individual failing fixtures and test methods by attaching [TestMustExpectAllLogs(MustExpect=false)] until they can be migrated. This also means new tests in that assembly would be required to have the more strict checking.

UnityPlatformAttribute

Use this attribute to define a specific set of platforms you want or do not want your test(s) to run on.

You can use this attribute on the test method, test class, or test assembly level. Use the supported RuntimePlatform enumeration values to specify the platforms. You can also specify which platforms to test by passing one or more RuntimePlatform values along with or without the include or exclude properties as parameters to the Platform attribute constructor.

The test(s) skips if the current target platform is:

Not explicitly specified in the included platforms list
In the excluded platforms list

UnitySetUpAttribute

The UnitySetUp and UnityTearDownAttribute attributes are identical to the standard SetUp and TearDown attributes, with the exception that they allow for IEditModeTestYieldInstruction. The UnitySetUp and UnityTearDown attributes expect a return type of IEnumerator.

UnityTearDownAttribute

The UnitySetUpAttribute and UnityTearDown attributes are identical to the standard SetUp and TearDown attributes, with the exception that they allow for IEditModeTestYieldInstruction. The UnitySetUp and UnityTearDown attributes expect a return type of IEnumerator.

public class SetUpTearDownExample
 {
     [UnitySetUp]
     public IEnumerator SetUp()
     {
         yield return new EnterPlayMode();
     }

     [Test]
     public void MyTest()
     {
         Debug.Log("This runs inside playmode");
     }

     [UnityTearDown]
     public IEnumerator TearDown()
     {
         yield return new ExitPlayMode();
     }
 }

UnityTestAttribute

UnityTest attribute is the main addition to the standard NUnit library for the Unity Test Framework. This type of unit test allows you to skip a frame from within a test (so background tasks can finish) or give certain commands to the Unity Editor, such as performing a domain reload or entering Play Mode from an Edit Mode test.

In Play Mode, the UnityTest attribute runs as a coroutine. Whereas Edit Mode tests run in the EditorApplication.update callback loop.

The UnityTest attribute is, in fact, an alternative to the NUnit Test attribute, which allows yielding instructions back to the framework. Once the instruction is complete, the test run continues. If you yield return null, you skip a frame. That might be necessary to ensure that some changes do happen on the next iteration of either the EditorApplication.update loop or the game loop.

Edit Mode example

The most simple example of an Edit Mode test could be the one that yields null to skip the current frame and then continues to run:

[UnityTest]
public IEnumerator EditorUtility_WhenExecuted_ReturnsSuccess()
{
    var utility = RunEditorUtilityInTheBackground();

    while (utility.isRunning)
    {
        yield return null;
    }

    Assert.IsTrue(utility.isSuccess);
}

## Play Mode example

In Play Mode, a test runs as a coroutine attached to a MonoBehaviour. So all the yield instructions available in coroutines, are also available in your test.

From a Play Mode test you can use one of Unity’s Yield Instructions:

WaitForFixedUpdate: to ensure changes expected within the next cycle of physics calculations.
WaitForSeconds: if you want to pause your test coroutine for a fixed amount of time. Be careful about creating long-running tests.

The simplest example is to yield to WaitForFixedUpdate:

[UnityTest]
public IEnumerator GameObject_WithRigidBody_WillBeAffectedByPhysics()
{
    var go = new GameObject();
    go.AddComponent<Rigidbody>();
    var originalPosition = go.transform.position.y;

    yield return new WaitForFixedUpdate();

    Assert.AreNotEqual(originalPosition, go.transform.position.y);
}

WaitForDomainReload

WaitForDomainReload is an IEditModeTestYieldInstruction that you can yield in Edit Mode tests. It delays the execution of scripts until after an incoming domain reload. If the domain reload results in a script compilation failure, then it throws an exception.

Enums

TestPlatform

A flag indicating the targeted test platforms.