In this post I’m going to show you how to use Unreal’s Automation System in order to create unit tests for your code. Unit tests are tests written by developers in order to test various aspects of their code and identify bugs or other unintended behavior before it happens.

Download the source code from my GitHub repo

In order to test out the Automation System, open up the .Build.cs file of your project and add “UnrealEd” and “Engine” on the dependecy modules list:

Implementing a dummy class

For the sake of this post, I’m also adding a dummy class to test its behavior:

Creating the first unit test

We have created a class that we can test so go ahead and create a new class. On its source file add the following code:

The IMPLEMENT_SIMPLE_AUTOMATION_TEST macro defines the class which contains our test. The macro requires:

  • The name of the class we want to define (in this case FMathStructTest)
  • A string which defines tha category that this test will be assigned in the Editor
  • Some flags regarding our test

For more information about the different flags you can use I would suggest to check out the AutomationTest.h file in the Engine’s source code. In this case, I have added the ApplicationContextMask flag which makes this test availabe in the Editor and the SmokeFilter which means that we expect this test to be completed quickly. In the provided link you can find out more about those flags so I would highly suggest to check it out!

Since we’re happy with the first unit test we have created, you can compile your code and open up the “Session Frontend” window from Window->Developer Tools. When you open up the Session Frontend you can click the Automation tab and you can locate the test we have created above:

(Click on image to enlarge)

If the test doesn’t appear on that window try clicking “Refresh Tests” or restarting your editor. Once you select the MathTests test you can click the Start Tests button and the editor will run your tests:

(Click on image to enlarge)

As we can see the results from the previous test passed. In case the result would fail, the editor would inform us about what went wrong. For example, if we change the expected result in the first addition on the code above from 20 to 19 we’re going to get the following result:

(Click on image to enlarge)

In this case I changed the expected value of the test from 20 to 19 and we can see that the editor informs us about why the test failed. Moreover, if you click on the red mathtests button in the SessionFrontend window the editor will display the error message of the output log to your window.

Creating another unit test

The previous unit test was pretty straightforward, however in real applications we may need to check various stuff inside our levels. For demonstration purposes, I created an automated process that verifies that we have a valid character placed inside the level we have currently open in the Editor:

Once you compile your code the Automation Tab should detect the new test and place it in the corresponding category:

(Click on image to enlarge)

Creating Complex Tests

Sometimes we want to test complex stuff and we don’t know exactly the duration of tests. Fortunately, Unreal provides an easy to use way of creating latent tests that can run for some time, allowing us to test things out. To implement a complex test we need to:

  • Define a new complex test
  • Override the GetTests function
  • Add the various tests in our complex test

Create a new class and in the header file add the following code in order to create a new test:

On the source file of our class, add the following code:

Once you compile your code and refresh your tests you will notice a new category and new tests in your Automation Tab:

(Click on image to enlarge)

To sum up, by defining a complex test we’re able to run several different tests on different maps. Once we have defined our tests, we can select the required maps we want to test out and run the tests in each one of them! This post was written using 4.26 version of the engine so depending on your version things may be slightly different.

In the next post, I’m going to show you how to run Functional Tests which simulate a user’s behavior when running our application so stay tuned! Thanks for reading and have a nice day!