Unit Testing in Unity

Until now, there has been no good solution for building unit tests for games built using Unity. As of today, there is. Get the package (version: 20090704) here.

Screenshots of the testrunner UI as seen in the editor:

Webplayer showing off the testrunner UI used outside of the editor.

Some highlights:

  • Test methods are coroutines, so you can test the behavior of things over time easily.
  • UnityGUI-based testrunner UI for both single-suite and multi-suite scenarios.
  • Graceful support for “test builds” that consist of a series of test scenes to be executed in sequence.

Usage is a bit trickier than I’d like, but still pretty straightforward: Create a class that derives from UnityTest. Add methods of the form:

public IEnumerator TestBlahBlahBlah() { ... }

Any method beginning with Test will be assumed to be a test method. (Avoid the TestAll method as that’s special.) These will be executed in a randomized order (to avoid accidentally letting your test methods become order-dependant!). Assertions are a bit of a gotcha here, since I can’t wrap a yield in a try/catch block.

if(AssertEquals(expectedValue, actualValue, "Custom message")) { yield break; }
if(Fail("Custom message")) { yield break; }

And so forth. Assertion methods return TRUE if execution is to be terminated. Drop an instance of this into a scene. Configure the scene as-needed for the test. Save it. Go to the Window menu, and select “Test Results” to create an editor panel showing the testrunner UI. Hit play, and watch as the testrunner shows you the results of your tests. Repeat the process until you have a few test scenes. Now make a new, empty scene and drop the UnitTestController prefab into it. Make sure iterate scenes is checked. This is your testrunner scene. Save it and make it scene 0. Add all your other test scenes to the build afterwards (make sure the build window ONLY has test scenes). Hit play with the testrunner scene loaded, and watch as it goes through and runs all your tests. You can now make standalone regression test builds, run a full regression test easily, or just selectively run individual regression test suites as-needed. When tracking down specific problems, check the break on error checkbox on a test to have the editor pause when a problem is encountered. This will help you in inspecting the state of things when there’s a problem.


  • Unity/iPhone 1.0.2+
  • Unity 2.5+


  • The iterations feature is VERY dangerous and should be used sparingly and carefully. Since UnityTest doesn’t reset the state of the execution and scene environment for you between iterations, it’s VERY easy to have one iteration poison the execution of subsequent ones!
  • Console output is written via System.Console.Write, not Debug.Log, so to see it you need to open Console.app (or whatever the Windows analogue is) – it doesn’t show up in Unity’s console display.
  • No stack trace is captured right now, so you have to find the source of the error based on the message. I intend to fix that, but need to make that behavior selective to not happen on-device with Unity/iPhone, since trying to get a stack trace crashes there.

523 words, est. time: 104 seconds.


Copyright © 2022 - Jon Frisby - Powered by Octopress