Working with Unity Test Framework

• Part 1: Preparing Test Runner
• Part 2: Writing Play Mode Tests
• Part 3: Using Edit Mode Testing

The Unity Test Framework (UTF) provides a way for developers to write unit and integration tests via built-in usage of the NUnit library in Unity. Tests can be run in either Play or Edit Mode, depending on the need and context of the testing.

Part 1: Preparing Test Runner

Testing Concepts

What is a unit test?

In programming terminology, a unit is any recognizably individual part of a complex system. Often, a unit can be as “small” as a function or as “large” as a class containing multiple methods. Generally, each unit is considered an independent module within a larger collection.

Unit testing takes it name from testing each of a system’s units. For example, if some code handled reading and processing files, one unit might be the code for reading files and another for processing its values. For however the code was represented as part of the system, each part could be considered its own unit.

Each test within a unit testing collection focuses on itself, checking if actions create specific results, cause expected errors, or produce known output ranges.

What is integration testing?

Integration testing considers the “integration” between modules. While unit tests focus on each unit within a system, integration tests uses multiple modules in connection with each other, passing data between them and testing the responses. Because it uses multiple modules, three strategies exists when using it: top-down (highest-level modules combined together first), bottom-up (lowest-level modules combined first), and hybrid or “sandwich testing” (highest and lowest tested at same time). Each have their own pitfalls, but designing an effective integration testing strategy involves understanding the modules within the system and in which order to test them.

Enabling the Unity Test Framework

Any existing and open Unity project can enable the use of the UTF through accessing its window.

The “Test Runner” window can be opened via Window –> General –> Test Runner.

Tests using the UTF work in either Play Mode or Edit Mode. Tests run in one mode cannot be saved in the same folder as tests using the other mode.

Creating a (PlayMode) Tests Folder

In the Project View, navigate to the root, Assets directory.

If not already selected, click on “PlayMode” in the Test Runner window.

Click on “Create PlayMode Test Assembly Folder” in the Test Runner window.

The newly created Tests window will contain one new file, Tests.

The created file, Tests.asmdef, is a collection of settings for use of the NUnity library. It allows for overriding how tests work within the UTF.

Creating a Default Test Script

After creating the Tests folder and the Tests.asmdef file, the UTF will produce a warning in the Console letting the developer know there are no tests and the created Tests.asmdef will be ignored.

To create a new test script, first open the Tests directory in the Project View.

Next, click on “Create Test Script in Current Folder” in the Test Runner window. This will use the currently open folder in the Project View, creating a new testing script.

The new test script will default to the name NewTestScript.cs. Once its name has been confirm, or the default name used, the Test Runner Window will update.

As there is now at least one test, the Test Runner Window will show the current tests as part of “Tests.dll” (based on the Tests.asmdef file).

Expanding the different levels will show two existing (default) tests called “NewTestScriptSimplePasses” and “NewTestScriptWithEnumeratorPasses”.

Running Tests

Once at least one test is created, it can be run. Any tests found within C# files stored in the same folder as the Tests.asmdef file will be added to the Test Runner Window for testing.

Clicking on the “Run All” button in the Test Runner Window will start the current scene, run the testing methods, and return the results. If the tests pass, they will have a green checkmark next to their name. If any fail, they will have a red circle with a ‘X’ in the middle.

The two default tests can be run without problems.

If the two default tests run and passed, the UTF is ready for use. Additional tests can be added as new C# scripting files.

Issues with PlayMode and EditMode Tests

This initial part in the series used PlayMode tests as part of an example of creating tests and running them. As will be covered later, EditMode tests can also be created. However, these tests cannot be stored together. The existence of a Tests.asmdef file in the same directory as any test files will add them to the Test Runner Window. Because PlayMode and EditMode tests run in different contexts, having tests using either mode in the same folder (and thus loaded in the Test Runner Window) will cause errors.