Version 2020.10



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 Notice

© Copyright 2021 GameDriver, Inc.

Trademark Notices


Unity™ is a trademark of Unity Technologies AsP.

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



Introduction

Thank you for trying 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 support@gamedriver.io.



Prerequisites




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.


Download the appropriate .unitypackage and license file 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 in step 1, do it now.

The license file will be named gdio.license. The file needs to be copied to the GDIO 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.


  • Use Unity Engine Logging - Allows you to see every input and command performed on your project while Play Mode is active, as well as the detailed output of the GameDriver agent.

  • 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.

  • Capture Input Events - This is used to capture input while in Play Mode.

  • Agent Hostname or IP - Used to control access to your project by the GameDriver agent. Enter the hostname or IP of the machine you will be testing from. Default is localhost

  • Agent Override from Autoplay Request - Allows you to remotely override the Agent Hostname or IP setting from the test machine. Note: enabling this will allow any machine to connect to the agent remotely while the Unity project is active.

  • Recorder and Api Endpoint - This is the hostname and port number used by the agent to allow remote connections. Default is localhost:5555

  • FPS Event Publish - The GameDriver agent polls your project for the current framerate, allowing you to control input based on the number of frames that has passed per second. This setting allows you to change the frequency of that polling.


For more information on agent options, see the GameDriver API reference.



Configure the Unity Build

The GameDriver agent requires your Unity game to be compiled using the .NET 4.x scripting runtime. WARNING: This may cause compatibility issues with scripts built specifically using .NET 3.5.


  1. Modify the Unity scripting runtime via Build Settings > Player Settings > Other Settings > Configuration and set the Scripting Runtime Version to .NET 4.x Equivalent. This change will result in the immediate recompilation of all game assets.


Unity 2018 LTS Build Settings

Unity 2019 LTS Build Settings


Note: The build process should move the requisite GameDriver files and folders into the standalone build automatically, which is the <ProjectName>_Data\Managed\ folder for all DLLs except NetCallback.dll, which will fall under <ProjectName>_Data\Managed\Plugins\ along with your gdio.license file.

In some versions of Unity, this process may fail and throw an exception during the build. If that occurs, simply move the NetCallback.dll and gdio.license files under the <ProjectName>_Data\Managed\Plugins\ folder and your standalone build should function as expected.



Working with GameDriver

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 and NUnit 3.


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


  1. Give your test a new name, and save to an easy to find location.


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


  1. Add the gdio.unity_api.dll reference to your project by expanding the project in the Solution Explorer, and right-clicking “References”. The library will be located in the \Assets\GDIO folder where you imported the .unitypackage at the start of this document.


  1. Add the declaration ‘using NUnit.Framework;’ and ‘using gdio.unity_api;’ without the single quotes:

You are now ready to start automating your testing using GameDriver!



Building Tests

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.WaitForGame(“127.0.0.1”);


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


            Api.Launch(@"C:\Full\path\to\your\Game.exe");


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 highlighted sections are provided as information only, and can be removed.



using System;
using NUnit.Framework; // needed for NUnit
using gdio.unity_api; // needed for GameDriver

namespace _GameDriverTest
{
    [TestFixture]
    public class UnitTest
    {
        /* The ‘OneTimeSetUp’ section will be executed once at the start of testing, and as a best practice should be where you put any connection and initialization work that needs to be done to get the app running.
        */
        [OneTimeSetUp]
        public void Connect()
        {
            // The following code is an example of connecting to the Unity editor
            bool connected;
            connected = Api.WaitForGame("127.0.0.1");
            if (connected)
            {
                Api.EnableKeybordHooks();
                Api.EnableMouseHooks();
            }

            // this is a sample from the 2D Game Kit from Unity. Your project will differ.
            Api.WaitForObject("//*[@name='StartButton']");
            Api.ClickObject("//*[@name='StartButton']",
            Api.MouseButtons.LEFT);
        }
        
        // The Test attribute is used to separate your tests.
        // Additional attributes are available to allow for input to be passed in at runtime, or define the ordering of tests. For more information visit NUnit.org.
        [Test]
        public void Test1()
        {
        //Do some testing...
        }

        // Tests should be able to run independently and in random order, so avoid dependencies
        [Test]
        public void Test2()
        {
        //Do some more testing...
        }

        /* Like ‘OneTimeSetUp’, the ‘OneTImeTearDown’ attribute tells NUnit to execute this code after all tests have completed. This is typically where we put our “disconnect” code, and any other cleanup that needs to be done.
       */
        [OneTimeTearDown]
        public void Disconnect()
        {
            Api.DisableKeybordHooks();
            Api.Wait(3000);
            Api.DisableMouseHooks();
            Api.Wait(3000);
            Api.Quit();
            Api.Wait(3000);
        }
    }
}




Limitations

Updated 10/14/2020:


  • Standalone testing is limited to Windows and macOS. iOS are currently in Public Beta, and may be made available upon request.

  • Api.Detach is inconsistent in standalone mode.

  • Api.DisableKeybordHooks’ contains a typo in the Api