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.
That is not what this video is about.
In this video I’m simply gonna show you how I write tests for Unity ECS code.
Now, bear in mind that Unity ECS is still in its infancy, so some of the code here is
subject change.
Well, without further ado, let’s get right into the example.
This video assumes that you have a basic understanding of Unity ECS.
If you don’t, you should check out my video called “What is Unity ECS?”.
That should get you on the right track.
To keep this video as simple as possible, we’ll be writing tests for a system that
comes prepackaged with Unity ECS.
Let’s press play now and use the entity debugger to check out Unity’s built-in systems
so we can get a better idea of what we’ll need to get started.
Without writing any code, Unity has already generated a world for us called “Default
World”, and populated it with a number of systems.
Clicking on a particular system within the entity debugger reveals what kind of entities
it operates on.
The one that we’ll be testing in this video is the MoveForwardSystem.
Systems operate selectively on a subset of entities based on their components.
The move forward system operates on all entities that match either one of the following component
archetypes.
The first consists of the MoveForward, MoveSpeed, Position, and Rotation components.
And the second consists of the MoveForward, MoveSpeed, Position, and Heading components.
The Rotation and Heading components are used to represent the forward vector of the entity.
The MoveSpeed component is used to determine how fast the entity should move forward.
And the MoveForward component simply acts as a tag.
During each frame the MoveForwardSystem calculates a new value for each entity’s Position component
using the entity’s forward vector and speed.
This causes the entity to, well, move forward.
Our tests will focus on entities with the second archetype.
To get started let’s create a folder to hold our tests.
I’ll call it “Tests”.
Next let’s create an assembly definition file that we can use to define how our tests
should be compiled.
I’ll call this “Tests” too so it matches the folder name.
Now we need to make sure it’s configured as a test assembly so Unity doesn’t include
it in any of the player builds.
We can do this by clicking on the assembly file and toggling the “Test Assemblies”
checkbox in the inspector.
Because these will be editor tests, we’ll want to make sure that this assembly is only
included in the editor.
So scroll down to platforms, toggle the “Select All” checkbox, uncheck “Any Platform”,
and then toggle the checkbox next to “Editor”.
We’re almost ready to write some code.
We just need to include a few assemblies so they’ll be available to our test classes.
The assemblies we need are Unity.Entities
Unity.Entities.Test Unity.Mathematics
And Unity.Transforms.
Now we’re ready to write our first test!
Create a class called “MoveForwardSystemTests” and open it in your IDE now.
I’ve cleared out all of the boilerplate code that’s created by Unity so we can have
a clean starting point.
The first thing we’ll want to do is mark this class with the TestFixture attribute
since it’ll be holding multiple tests.
Now we can leverage a special test fixture class that’s included in the Unity.Entities.Tests
package.
The ECSTestFixture generates a test world and an entity manager, and stores them in
protected field variables that we can use throughout our tests.
The last thing we should do before we write our first test is add a category to the test
fixture.
This’ll allow us to filter the test runner so it’ll be easier to find our tests.
Now we can write our first test.
This one will be base case that we’ll use to get us started.
I’ll call it “when move speed equals zero then entity doesn’t move”.
There are dozens of naming conventions for tests, so if this one doesn’t float your
boat go ahead and call it whatever you’d like.
Now let’s go ahead and create an entity using the archetype we saw earlier.
Again, this variable, m_Manager, is provided by the base class.
It holds an instance of the entity manager that belongs to the test world.
Our entity will should have the following components.
MoveForward, MoveSpeed, Position, and Heading.
Now let’s give our entity’s components some values so it’s clear what this method
is testing.
Remember, this is a base case so all of the values should be set to zero.
Alright, we’ve completed the “arrange” step of our test.
Now we can act on our system by using the World variable, which comes from the base
class and holds an instance of the test world, to create a move forward system and call it’s
Update method.
Now we can assert that that entity hasn’t moved by checking its current position.
Perfect!
Our first test is complete.
Let’s switch back to the editor and run it.
Beautiful.
Now we can switch back to the IDE and write one more test.
This one will test actual forward movement.
I’ll call it “when move speed equals one then entity moves forward.”
And I’m just going to copy and paste code from our base case test.
We want to test forward movement so the first thing we need to change is the move speed.
I’ll set it equal to one, just like the name implies.
Now we need to give our entity a direction to move in.
I’ll initialize the Heading component so the entity moves along the x axis.
Lastly we need to update our assert.
Since the entity should now be moving along the x-axis at a rate of one unit per second,
and the the move forward system uses delta time to calculate position, we know that the
value of x should be equal to delta time.
And that’s all there is to it.
Let’s switch back to the editor and re-run the tests.
Beautiful.
If you’d like to learn more about Unity ECS, then I highly recommend checking out
my tutorial series where I’ll show you how to create a survival shooter game using Unity
ECS.
The project files for that series and this video is available for download to all of
my tier 2 patrons.
If you like to grab the code and support this channel at the same time, then please consider
becoming a patron today.
So that was a quick look at some basic tests of Unity ECS code.
If you’d like to some more advanced examples, feel free to hop on the Discord server and
let me know.
If you enjoyed this video, please leave a like and a comment letting me know what you
thought.
And for more Unity tutorials just like this one, don’t forget to subscribe with notifications
on.
I’ll catch you in the next video.
So that was a quick look at some basic tests of Unity ECS code.
If you’d like to some more advanced examples, feel free to hop on the Discord server and
let me know.
If you enjoyed this video, please leave a like and a comment letting me know what you
thought.
And for more Unity tutorials just like this one, don’t forget to subscribe with notifications
on.
I’ll catch you in the next video.
Thank you to all of my patrons.
And a special shoutout to Chance McDonald, Glaswyll Entertainment, Richard Stanz, and
Yakov.