Unity ECS

How To Test Unity ECS Code

This tutorial will teach you how to test Unity ECS code using a system that’s already built into the Unity.Entities package.

This post assumes that you have some basic knowledge of Unity ECS. You should at least know what it is ECS is and have some experience writing ECS code.

If you know, then I highly recommend checking out my video called What Is Unity ECS. It contains everything you need to get started and some links to more resources.

Should You Test Unity ECS Code?

Automated testing is a tricky subject to cover; especially in game development. Some developers swear by writing automated tests while others think it’s a complete waste of time.

But that’s not what this tutorial is about. This post will simply walk you through how to test Unity ECS code using a couple of simple examples.

Whether or not you believe that automated tests are necessary is up to you.

The System Under Test

We’ll be testing the MoveForwardSystem, which comes built into the Unity.Entities package.

The MoveForwardSystem is responsible for moving entities forward based on their speed and the direction that they’re facing.

It does this by operating on entities that one of two component archetypes:

  • MoveForward, MoveSpeed, Position, Rotation
  • MoveForward, MoveSpeed, Position, Heading

MoveForwardSystem Component
Our tests will focus on the second archetype; entities that have a MoveForward, MoveSpeed, Position, and Heading component.

Setting Up Our Test Environment

There are a few ways to set up a test environment in Unity. We’re going to us Assembly Definition Files to setup ours.

Assembly Definition Files tell Unity how to compile scripts, as well as which assemblies to include in each build.

Complete the following steps to setup your test environment:

  1. Create a folder called “Tests”.
  2. Right-click the Tests folder and select Create → Assembly Definition (name it “Tests”)
  3. Select the Tests assembly definition file so it appears in the Inspector window
  4. Enable the Test Assemblies checkbox
  5. In the platforms section, click Select All, enable the checkbox next to Any Platform, and enable the checkbox next to Editor
  6. Add references to Unity.Entities, Unity.Entities.Test, Unity.Mathematics, Unity.Transforms

Test Assembly Settings

Now create a class file inside of the Tests folder called “MoveForwardSystemTests” and open it in your IDE.

Our First Test: The Base Case

The first test is a base case, which means it tests the simplest case possible. It asserts that if an entity’s move speed is zero, then it won’t move.

Our test class derives from ECSTestsFixture which exposes two important protected field variables, World and m_Manager.

World holds an instance of a special test world that’s created in the base class before the tests run. And the m_Manager variable holds an instance of an entity manager that belongs to the test world.

The arrange step uses the entity manager to create an entity with all of the components mentioned in the previous section. It then sets all of the components’ values to zero.

The act step creates an instance of MoveForwardSystem and calls it’s Update method. And finally, the assert step tests that the entity’s position hasn’t changed.

Test Two: Asserting Forward Movement

The second test actually tests that the MoveForwardSystem is behaving the way we expect it to.

The assert step creates an entity that should move along the x-axis. The entity’s move speed is set to 1 and it’s heading is set to a float3 with an x value of 1.

Just like before, the act step creates an instance of MoveForwardSystem and calls it’s Update method. But this time the assert step tests that the entity moves along the x-axis.

The MoveForwardSystem moves entities in the direction that they’re facing at a rate of speed times delta time by updating the entity’s position. That’s why this test asserts that the test entity’s position is equal to a float with an x value of Time.deltaTime.

Summary

These are just a couple of basic examples that should serve as a springboard to get you started. As we begin adding more systems we’ll likely need a more sophisticated to isolate our test worlds.

The method of testing described in this post was used to test all of the systems created in my Unity ECS tutorial series.

The project files for this post are available for download to my tier-2 patrons at https://www.patreon.com/posts/code-how-to-for-19769879