Using GameDriver with the Unity Test Framework (UTF)

Learn how to leverage GameDriver alongside the Unity Test Framework (UTF)

With the 2.0 release in June 2021, GameDriver is compatible with the Unity Test Framework allowing for test execution as part of the Unity build process, including using Unity Cloud Builds or any other build platform that is supported for building Unity apps. This new feature provides additional flexibility in where and how you test your application but is subject to the requirements and limitations of the Unity Test Framework itself.

This support is provided under the CoApiClient in the gdio.unity_utr_api library. Documentation for this can be found in our GitHub repository alongside ApiClient and generally follows the same usage. However, since UTR tests are compiled and run at build-time, the structure of tests is somewhat different from that of a standalone GameDriver test.

ApiClient versus CoApi?

Before we dive into the nuts and bolts of the CoApi, it is important to understand when to use this mode of execution versus the standard GameDriver ApiClient. While the majority of commands and helper methods are supported in both modes, there are some differences to consider. The table below is intended to highlight some of these differences and help you decide which of these methods is right for your project.

As you can see from this table, the majority of GameDriver features are identical between the ApiClient and CoApi, with only a few exceptions. The main difference between these two is where tests are built and run, and how internal methods are accessed. There is also significant value in being able to build, modify, and run tests without the need to recompile the target application. 

Unlike standalone tests written with NUnit and GameDriver, tests utilizing the Unity Test Framework make use of Coroutines which require the IEnumerable interface to control test flow, and Yields to return values. This allows test methods to iterate as needed before returning control back to the calling function. For more information on this approach, please refer to the Unity Test Framework documentation, specifically this section on UnitySetUp and UnityTearDown. Another good reference document for working with Iterators and Yields can be found on Microsoft’s documentation here, and we highly recommend this video for a practical working explanation.

Additionally, the CoApi does not currently support the newer VR/XR calls. This includes such calls as Vector2/3InputEvents, QuaternionInputEvent, Create/RemoveInputDevice, and IntegerInputEvent.

SmartAgent calls are also not currently supported, which includes ExecuteScript and Schedule/UnshceduleScript.

To summarize the use of this approach, it’s helpful to keep in mind all methods that return a value (whether it is a bool, int, string, etc..) need to use the IEnumerator interface and need to use the `yield return` syntax.

For the remainder of this document, we will refer to a sample project and test that can be found here on our GitHub. Following the examples in this project, you should be able to write similar tests for your Unity project.

Getting Started with the GameDriver CoApiClient

If you haven’t already installed GameDriver in your Unity project, please follow the steps outlined in the installation instructions. Next, follow the instructions for How to create a new test assembly in the Unity Test Framework documentation. Be sure to add the following GameDriver libraries under Assembly References to the Assembly Definition when on this step:

Next, create a test in the same directory as your Tests.asmdef file above. This can be done using the Create > Testing > C# Test Script menu option in the editor.

Next, open the new test script in your default development environment. For this example we will use Visual Studio 2019 for macOS. Once your test is open, you will need to add the following directives:

using System.Collections;
using System.Collections.Generic;
using NUnit.Framework;
using UnityEngine.TestTools;
using UnityEngine.SceneManagement;
using System.Threading;
using System;
using gdio.common.objects;
using gdio.unity_utr_api;

• [OneTimeSetup] method which loads the scene containing the GameDriver agent

• A client API connection method - this can be where you enable the input hooking

• Your test(s)

• A [OneTimeTearDown] method which disconnects from the agent

For example, here is the OneTimeSetup method used in our sample test.

CoApiClient client = null;

[OneTimeSetUp]
public void SetupInitialScene()
{
// An initial scene must be loaded when using PlayMode
SceneManager.LoadScene("Splash", LoadSceneMode.Single);

client = new CoApiClient();

client.LoggedMessage += (s, e) =>
{
       UnityEngine.Debug.Log(e.Message);
};

return;
}

[UnityTest, Order(1)]
public IEnumerator T001_ConnectToGame()
{
IEnumerator<bool> result = null;

yield return result = client.Connect();

Assert.IsTrue(result.Current);
}

[UnityTest, Order(2)]
public IEnumerator T002_EnableHooksTest()
{
IEnumerator<bool> result = null;

yield return result = client.EnableHooks(HookingObject.ALL);

Assert.IsTrue(result.Current);
}

Now we’re ready to add some project-specific tests.

Test Structure and Best Practices

Tests written using this method tend to be a lot smaller in scope than those written outside of the UTF and editor. Structurally they should be simple, and accomplish 3 things in order to execute in a repeatable way. Those are:

1. Test setup

2. Test operation

3. Validate results

While this structure is considered a best practice for all automated testing, it especially applies in this mode where combining multiple test steps into a single operation can make troubleshooting quite difficult. An example of this approach can be found below.

[UnityTest, Order(6)]
public IEnumerator T006_CallMethodGenericReturnIntTest()
{
// Set up the test
IEnumerator result;
SceneManager.LoadScene("UISample", LoadSceneMode.Single);

// Perform the test - in this example we’re calling a method attached to an object to perform a simple calculation

yield return result = client.CallMethod<int>("//*[@name='Canvas']/fn:component('HipProjectManager')", "DoMath", new object[] { 1, 2 });

// Debug message to make sure we did what we wanted
UnityEngine.Debug.Log($"CallMethod return int='{result.Current.ToString()}'");

// Test that the result is correct
Assert.IsTrue(result.Current.GetType().Equals(typeof(int)));
Assert.AreEqual(3, result.Current, "DoMath failed");
}

In the example above, we’re simply loading a scene, calling a method attached to an object with a few parameters, and then checking that the returned value is what we expected. In practice, this type of test is closer to a unit test, but the structure of the test is the same whether the goal of the test is a low-level validation like this, or a test to see what happens when a player character hits an enemy with a specific weapon. Let’s look at a more complex example:

[UnityTest, Order(10)]
public IEnumerator T010_KeyboardMovement()

{

// Set up the test
yield return client.LoadScene("MoveObjectScene");

IEnumerator result;
yield return result = client.WaitForEmptyInput();
UnityEngine.Debug.Log($"WaitForEmptyInput return string='{result.Current.ToString()}'");

// Get the initial position of the cube, and cast that to a new Vector3

IEnumerator before;
yield return before = client.GetObjectPosition("/*[@name='Cube']", CoordinateConversion.None);

UnityEngine.Vector3 cubeStart = (UnityEngine.Vector3)before.Current;

// Move the block down and left from the origin

yield return client.KeyPress(new UnityEngine.KeyCode[] { UnityEngine.KeyCode.DownArrow }, 100);

yield return client.Wait(1);

yield return client.KeyPress(new UnityEngine.KeyCode[] { UnityEngine.KeyCode.LeftArrow }, 100);
yield return client.Wait(1);

// Get the new position of the cube, and cast that to a new Vector3

IEnumerator after;
yield return after = client.GetObjectPosition("/*[@name='Cube']", CoordinateConversion.None);

UnityEngine.Vector3 cubeEnd = (UnityEngine.Vector3)after.Current;

// Check that the cube moved from the start

Assert.AreNotEqual(cubeStart.x, cubeEnd.x, "Cube didn't move!");

}

As a rule of thumb, you will want to keep tests self-contained as much as possible. Meaning a test should be able to run without requiring a previous test to pass. Also, try to avoid testing multiple scenarios in a single test. The best practice here is to always test one "thing" in each test, and keep dependencies to a minimum. This isn't specific to testing with the Unity Test Framework + GameDriver, but rather for automated testing in general.

Running Tests

Tests built using the Unity Test Framework can be run using the Unity Test Runner, which is available in the editor under Window > General > Test Runner.

Tests can be run directly from this interface during development, which provides details of any failed tests. You can also run tests against a standalone build, which is configured via the File > Build Settings > Player Settings dialog.

For more information regarding the Unity Test Runner, please refer to the Unity Documentation.

If you have any questions or feedback on this guide, please contact us at support@gamedriver.io.