Edit Mode vs. Play Mode tests
Before getting started with Unity Test Framework it's important to understand what Play Mode and Edit Mode tests mean in the Unity Test Framework context.
Edit Mode tests
Edit Mode tests (also known as Editor tests) are only run in the Unity Editor and have access to the Editor code in addition to the game code.
Note: You can also control entering and exiting Play Mode from your Edit Mode test. This allow your test to make changes before entering Play Mode.
Edit Mode tests should meet one of the following conditions:
- They should have an assembly definition with reference to nunit.framework.dll
- Tests will be treated as Edit Mode by default if they only have the Editor as a target platform:
"includePlatforms": [ "Editor" ],
- If their assembly targets other platforms, EditMode tests should be have
[RequiresPlayMode(false)]. See Requiring Play Mode below.
Play Mode tests
Play Mode tests allow you to exercise your game code at Runtime, as the tests run as coroutines if marked with the
UnityTest attribute. If you run tests in the standard way, Play Mode tests will run in the Editor's in-built Play Mode. You can also run Play Mode tests in a standalone Player built for the target platform.
Play Mode tests should meet the following conditions:
- Have an assembly definition with reference to nunit.framework.dll.
- Have the test scripts located in a folder with the .asmdef file.
- The test assembly should reference an assembly that contains the code you want to test.
- Any project code you want to test must have its own assembly definition so that your test assembly can reference it.
"references": [ "NewAssembly" ], "optionalUnityReferences": [ "TestAssemblies" ], "includePlatforms": ,
Requiring Play Mode
If you have a test assembly that only has the Editor as a target platform then by default Unity Test Framework runs any tests in the assembly in Edit Mode only. Likewise, if your assembly targets a platform other than the Editor, for example Windows 64-bit, Unity Test Framework assumes these are Play Mode tests and will run them in the Editor's Play Mode by default.
You can override these defaults using the RequirePlayModeAttribute. If tests are part of an Editor-only assembly, you can annotate them with
[RequiresPlayMode] to make them run in the Editor's Play Mode. If you have a platform-specific assembly but you don't want your tests to run in the Editor's Play Mode, you can exclude them from running in Play Mode with
Where will my test run?
The following table summarizes where your test will run based on assembly configuration,
RequiresPlayMode value, and Run Location option:
|Assembly reference||RequiresPlayMode||Run Location||Runs in|
|Editor only||False or Not Specified||In Editor||Editor Edit Mode|
|True||In Editor||Editor Play Mode|
|Specific platform(s)||False||In Editor||Editor Edit Mode|
|True or Not Specified||In Editor||Editor Play Mode|
In summary: an Editor assembly makes your tests Edit Mode by default unless overridden by
[RequiresPlayMode]. A platform assembly makes your tests Play Mode by default, unless overridden by
[RequiresPlayMode(false)]. Tests run in a Player will always run in the Player.
References and builds
Unity Test Framework adds a reference to test assemblies in the Assembly Definition file but does not include any other references (e.g., to other scripting assemblies in your Unity project). To test other assemblies, you need to add them to the assembly definition yourself. For details on adding assembly references, see Assembly Definition. We recommend organizing your tests into separate assemblies and using assembly definitions files to selectively expose them to the code they test. This way you will have more control over which assemblies need to reference test related dlls and avoid having unnecessary assemblies in your builds.
Use the NUnit
Test attribute instead of the
UnityTest attribute, unless you need to yield special instructions, in Edit Mode, or if you need to skip a frame or wait for a certain amount of time in Play Mode.
It is possible for your Test Assemblies to reference the test tools in
UnityEditor.TestRunner. The latter is only available in Edit Mode. You can specify these references in the
Assembly Definition References on the Assembly Definition.