Version 2023.06

Legal Notices

Warranty

The only warranties for products and services of GameDriver and its affiliates and licensors (“GameDriver”) are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. GameDriver shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.

Restricted Rights

Contains Confidential Information. Except as specifically indicated otherwise, a valid license is required for possession, use, or copying.

© Copyright 2022 GameDriver, Inc.

GameDriver® is a Registered Trademark of GameDriver, Inc. All rights reserved. 

Unity™ is a trademark of Unity Technologies AsP.

Microsoft® and Visual Studio® are U.S. registered trademarks of Microsoft Corporation.

Introduction

Thank you for choosing GameDriver! We believe in better video games through the power of test automation and want to help you get the most out of your testing efforts. This guide will help you through the installation and initial configuration process. Any errors or omissions can be reported to [email protected].

Prerequisites

• A PC running Windows 10 or macOS 10.13.x or higher

• Unity 2020.3 LTS, Unity 2021.3 LTS, or Unity 2022.3 LTS

• Visual Studio 2019 or higher

• NUnit Test Framework or equivalent .NET compatible test framework

Unity Agent Installation

The GDIO Unity Agent is installed by importing the GameDriver .unitypackage for your specific release, and is then as a GameObject in your Unity project, through the IDE.

Be sure to register for a trial license and Download the appropriate .unitypackage  from GameDriver.io/license. For example:

From back in the Unity editor, navigate to Assets > Import Package and select Custom Package:

Select the .unitypackage appropriate for your Unity version and click Open:

Ensure all of the objects and folders in the import package are selected and select Import:

Adding the License File

In order to run a test, a license file needs to be present. If you didn't download the license already, do so now. The license file will need to be renamed to "gdio.license.txt", and copied to the Assets\GDIO\Resources folder in your game project in order for the agent to run.

Enabling GameDriver

Add an empty GameObject in the base of your game hierarchy. If you have multiple scenes, it will be necessary to attach the agent to a scene that is loaded initially but is not likely to be reloaded later, such as a splash screen or menu. This is due to the agent remaining resident in memory after the scene has been closed.

Add the gdio.unity_agent to this empty GameObject via Add Component > Scripts > gdio.unity_agent > GDIO Agent.

Once the agent is installed, it can be configured via the GameObject in the inspector. A brief description of each option can be found below.

The GameDriver Unity Agent script configuration dialog in Unity.

• Enable Keyboard Hooks - This is necessary to capture keyboard input into your project while Play Mode is active. Should be OFF while testing manually in the IDE, and ON when controlling your project via the GameDriver agent and API. You can set this within your test.

• Enable Mouse Hooks - This is necessary for capturing mouse input into your project while Play Mode is active. Should be OFF while testing manually in the IDE, and ON when controlling your project via the GameDriver agent and API. You can set this within your test.

• Listening Port - This is the port the agent will listen to for incoming client (API) connections.

Working with GameDriver

For a working version of the test project below, visit our GitHub repo. The rest of this guide will explain how the example project was set up and can be used as a reference. The instructions below and the example provided assume a standalone test class project will be used. To integrate your GameDriver tests with your Unity project and utilize the Unity Test Framework, please refer to these instructions.

The GameDriver API can be used with a test framework such as NUnit, which provides essential capabilities such as test execution, base reporting, and assertions (checks). It is also cross-platform compatible, which is ideal for our purposes. To demonstrate, we will use Visual Studio 2019 Community Edition for Windows, and Visual Studio for Mac Community Edition, along with NUnit. Other development environments and test frameworks will vary.

1. In Windows, create a new Test Project under File > New > Project and select Class Library (.NET Framework). Make sure this is the one using C#, as shown with the tags below.

Note: If you do not see this option when starting a new project, you may need to modify your Visual Studio installation to include the Desktop Development workload shown below.

In macOS, use the Other > .NET > Library template from the Visual Studio project creation screen:

2. Give your test project a new name, and save it to an easy-to-find location.

3. Using the NuGet Package Manager, find and install the NUnit, NUnit3TestAdapter, and NUnit Console packages. These are needed for the use of, visualization, and execution of NUnit tests respectively.

4. Add the following references to your code.

using System;
using System.Diagnostics;
using NUnit.Framework;
using gdio.unity_api;
using gdio.unity_api.v2;
using gdio.common.objects;

Attaching to your Game

Once you have configured your game and test environment, it is necessary to connect to the GameDriver agent via API in order to run a test. There are a few ways to connect to your game and initiate testing; either attaching to the Unity editor in Play Mode or executing the game build executable.

1. Attaching to the Unity editor in Play Mode. With the Unity editor open and Play Mode initiated, simply add the following method to your test script:

api.Connect("localhost", 19734, true, 30);

2. Executing the Game Build executable. Simply add the following method to your test script, with the full path to the executable for your game:

ApiClient.Launch(@"c:\path\to\MyGame.exe");

ApiClient.Launch(@"/Users/user/Desktop/MyGame.app/Contents/MacOS/MyGame");

Note: The @ Symbol in this method is used to escape the entire string. Without this, it is necessary to escape all special characters in the path.

For information on building your game for use with GameDriver see “Configure the Unity Build” above.

Building Tests using the NUnit Framework

The NUnit test framework provides basic tools for assertions (or checks) and execution of tests inside Visual Studio and other common IDEs, as well as from build systems such as Jenkins. NUnit follows a structure that the IDE interprets for configuration at run-time, which also allows the test to exclude some of the standard components of C# coding, such as the Main method. Generally, the template supplied by the IDE can be followed for test creation. More information on the structure and usage of NUnit tests can be found here.

For the purpose of GameDriver testing, tests should be structured as follows. The comment sections are provided as information only and can be removed.

using System;
using System.Diagnostics;
using NUnit.Framework;
using gdio.unity_api;
using gdio.unity_api.v2;
using gdio.common.objects;

namespace DemoTest
{
    [TestFixture]
    public class UnitTest
    {
        //These parameters can be used to override settings used to test when running from the NUnit command line
        public string testMode = TestContext.Parameters.Get("Mode", "IDE");
        public string pathToExe = TestContext.Parameters.Get("pathToExe", null); // replace null with the path to your executable as needed

        ApiClient api;

        [OneTimeSetUp]
        public void Connect()
        {
            try
            {
                // First we need to create an instance of the ApiClient
                api = new ApiClient();

                // If an executable path was supplied, we will launch the standalone game
                if (pathToExe != null)
                {
                    ApiClient.Launch(pathToExe);
                    api.Connect("localhost", 19734, false, 30);
                }

                // If no executable path was given, we will attempt to connect to the Unity editor and initiate Play mode
                else if (testMode == "IDE")
                {
                    api.Connect("localhost", 19734, true, 30);
                }
                // Otherwise, attempt to connect to an already playing game
                else api.Connect("localhost", 19734, false, 30);

            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
            }
            // Enable input hooking
            api.EnableHooks(HookingObject.ALL);

            //Start the Game - in this example we're waiting for an object called "StartButton" to become active, then clicking it.
            api.WaitForObject("//*[@name='StartButton']");
            api.ClickObject(MouseButtons.LEFT, "//*[@name='StartButton']", 30);
            api.Wait(3000);
        }

        [Test]
        public void Test1()
        {
            // Do something
        }

        [Test]
        public void Test2()
        {
            // Do something else. Tests should be able to run independently after the steps in [OneTimeSetup] and should use try/catch blocks to avoid exiting prematurely on failure
        }

        [OneTimeTearDown]
        public void Disconnect()
        {
            // Disconnect the GameDriver client from the agent
            api.DisableHooks(HookingObject.ALL);
            api.Wait(2000);
            api.Disconnect();
            api.Wait(2000);
        }
    }
}

Limitations

No known limitations at the time of this publishing