How to use Unit Test Runner
NOTE: Since Unity 5.3 the Unit Tests Runner is a part of the Editor and was removed from the Unity Test Tools package. For more reference, look at the Editor Tests Runner section in the documentation.
How to open the Unit Test Runner
You open the Unit Test Runner from the menu bar Unity Test Tools/Unit Test Runner or by shift+ctrl+alt+u combination.
Getting Started with NUnit
After importing Unity Test Framework package, NUnit library(version 2.6.2) is included into your project.
If you are new to NUnit please visit NUnit's Quick Start guide to get started. This article demonstrates the development process with NUnit in the context of a C# banking application.
To start your unit testing experience open the test runner window by clicking Unity Test Tools/Unit Test Runner and it will show you the windows with test examples that are supplied with Unity Test Framework.
How Unit Test Runner works
The Unit Test Runner uses NUnit library that's included into the project (nunit.core.dll, nunit.core.interfaces.dll, nunit.framework.dll). The runner looks for tests in Assembly-CSharp.dll and Assembly-Editor-CSharp.dll.
Before executing the tests the runner will open a new scene (unless you disable it in the options), therefore you may get a prompt to save your scene. After the run is finished the previous scene will be loaded automatically in between the run no cleanup is done and it must be done within the test suite if necessary. For managing GameObjects on the scene you can use the UnityUnitTest class which provides you with a method for creating GameObjects and does the cleanup automatically.
It's recommended to keep the unit test files under Editor folder so they won't be included in the build.
Unit Tests Runner window
- Run all tests
- Run selected test
- Run failed tests
Options - show options panel
- Run on recompilation - the tests will automatically run after every compilation (unless the compilation failed)
- Run tests on a new scene - the runner will open new scene to run the tests and load back the current one after the run has finished. The user will be prompt to save the scene first.
- Autosave scene - will automatically save the scene before the run start (available when "Run tests on a new scene" is checked)
- Show details below tests - positions the details tab below the test list.
Filter that allows to show only methods and classes that match the string in this field
- Category filter - if tests have Category attribute set on them, this field will allow you to filter the list by selecting one or many categories to show
- Advanced button shows advanced filtering settings
- Tests hierarchy window that shows the tests and the execution results
- Displays the exception and the stacktrace for failed tests
After each run the results are reported in the Test Runner window. When running in a batch mode, an XML file is generated with nUnit style results. It's located in project's root folder or under specified path. The schema for the file can be found here: http://www.nunit.org/docs/2.6.2/files/Results.xsd.
Include unity tests from external libraries
The runner will scan all dll libraries in the project and include those that depend on nunit.framework.
Headless running (batch mode)
It is possible to run test from command line. In order to do that, run unity in batch mode and execute UnityTest.Batch.RunUnitTests method on start.
- resultFilePath - A path where the result file should be placed. If the path is a folder, a default file name will be used. If not specified, the results will be places in project's root folder.
- filter - Filter tests by names.
- categories - Filter tests by categories
For Unity 5.2 or previous versions.
>Unity.exe -batchmode -projectPath PATH_TO_YOUR_PROJECT -executeMethod UnityTest.Batch.RunUnitTests -resultFilePath=C:\temp\results.xml
This will run all available tests and generate result file under C:\temp\results.xml.
The editor will exit with a return code according to the result of the run:
- 0 - Run succeeded, no failures occurred
- 2 - Run succeeded, some tests failed
- 3 - Run failure (other failure)
In order to get the result code, do not use the -quit parameter. Read more about command line argument here.
On Windows, for batch mode, run Unity with followind command in order to receive the return code properly:
start /WAIT Unity.exe ARGUMENT_LIST
It will allow you to get the return code from ERRORLEVEL variable.