What you will get from this page: Tips on how to use the Unity Test Framework (UTF) to QA your projects. The UTF is one of the most important tools for quality assurance; it is used to run automated tests both in the Editor and on supported platforms. And it's available to all Unity users!
A new Test Runner API brings greater flexibility and extensibility to the UTF, for most of your testing needs. It’s available via the Unity Package Manager, so we can ship bug fixes and new updates faster. This also means you can access the source code of the UTF locally. You can look at the source code, step through it when debugging, and modify it.
To get the full story, watch the UTF session at Unite Copenhagen, featuring Unity tooling and testing developers Richard Fine and Christian Warnecke.
Getting started with the Unity Test Framework
If you are new to the Unity Test Framework (UTF), read the documentation for an introduction. In brief, the UTF enables Unity users to test their code in both Edit Mode and Play Mode, and also on target platforms such as Standalone, Android, iOS, and others.
UTF uses a Unity integration of the NUnit library, which is an open-source unit testing library for .Net languages. For more information about NUnit, see the official NUnit website and the NUnit documentation on GitHub.
You might also find these blog posts informative:
Another related solution to learn about is Backtrace, an error management platform that enables you to capture crashes and exceptions and fix them quickly. Watch this Unite Now session for an in-depth introduction.
Overview of the Test Runner API
You can run your tests programmatically from any script via the Test Runner API (see API below). It allows you to retrieve a list of tests that will run in Edit Mode, Play Mode, or both, without running them. You can hook into some register/unregister callbacks at the start and finish of each test and at each level within the testing cycle, that is, on the entire test assembly, on each individual test fixture, and on each test class and test.
At the start of each test, you get information about the test route that is about to be run. When the test finishes, you see the test results.
In addition to running the UTF in Play Mode in the Unity Editor, a new customization point lets you run it on target devices. This is called before you build the Player; you can modify the Player build options, for example, to change the test run settings and to specify the build locations.
Splitting build and run
Splitting the build and run processes is useful when you want to run tests on a target device that is not attached to your local machine, for example, if it is in the cloud (or is multiple devices in the cloud).
To do this, you first need to customize the test Player build process itself. Here’s how to do that:
- Disable the AutoRun, so that once you build the Player it doesn’t launch and run the tests.
- Save it to a known location rather than into the system’s temporary folder (where it would be saved by default.
Then you add custom result reporting on the Player side (using the callback interface) to capture all the results and save them to an XML file, or whatever format works for your project.
See the following code examples for splitting build and run. In the Unite session (at 6:28) Richard Fine takes you step by step through the code for both parts of this application – the build and result reporting.
Splitting build and run: build
Splitting build and run: save results in run
Running tests before the build
Running tests before the build can be tricky because the build process requires that the tests are run from a callback, so there’s no opportunity to pump the engine update loop. But the benefit is that you can check that basic functionality is working, prior to spending time actually building (which can take many minutes for some projects).
You can implement this application using the IPreprocessBuildWithReport interface, the same way you might implement any other kind of build preprocessing. To get the results, register a callback as usual.
Because you can’t go into Play Mode in the middle of a build, you can use the Test Runner API to run specific tests in Edit Mode. You can select those tests by filtering by category, such as a pre-build validation test category. You can run these tests synchronously.
Once the test is finished, check the results. If something failed, you can throw a BuildFailed exception, which will cause the build process to abort.
This application can be broken down into two parts – the ResultCollector and the preprocessor – which Richard details in their talk (at 15:20).
Watch Christian and Richard demo the Test Runner API live. Check out the whole session for even more QA tips!