Version 2023.01


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 2023 GameDriver, Inc.

GameDriver is a registered trademark.

Unreal Engine™ is a trademark of Epic Games.

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 support@gamedriver.io.


Prerequisites


Unreal Agent Installation

The GDIO Unreal Agent is installed by placing a small plugin in your game. That plugin communicates with our API, which you use to drive your game remotely.


Be sure to register for a trial license follow the quickstart link for the appropriate Unreal release from GameDriver.io/license. For example:

The link to the quickstart document will contain the plugin, and instructions on how to install it, as well as the unreal_api DLLs for use in your test programs. Once you’ve completed the quick start, return here for instructions on installing the license file. 

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 need to be renamed to "gdio.license.txt", and copied to the Plugins folder in your game project in order for the agent to run.


Your final Project will look like the following:

SomeProjectPath/

└─ Plugins/

   └─ UnrealCLR    <----- You should see the UnrealCLR folder here

   └─ gdio.license    <----- Place your license here

└─ Managed/

   └─ GameDriver    <----- You should see a GameDriver folder here 

└─ MyProject.uproject    

└─ MyProject.sln    



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 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:


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


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


  1. Add the following references to your code.

    using System;
using System.Diagnostics;
using NUnit.Framework;
using gdio.unreal_api;
using gdio.common.objects;

  2. In the project references, you will also need to add the following DLLs to resolve all of the above classes. Those are gdio.common.objects, gdio.plugin.serializer, and gdio.unreal_api. In Visual Studio, simply right-click the "References" node in the Solution view, shown below, then navigate to the libraries. The libraries will be located in the Plugins folder of the project


Note: Be sure to verify your test project is using the .NET Framework 6.0.x library. In Visual Studio, this can be found under the Solution > Project (right-click) > Options (as shown in VS for Mac below): 



Then under the General tab in the Project Options, under Target Framework.


The location of this option in other IDEs may vary, along with other IDE-specific settings such as the Test Runner (View menu > Tests in Visual Studio for Mac), which is used to execute your tests in the IDE.


You are now ready to start automating your testing! 



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 Unreal editor in Play Mode or executing the game build executable.


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

api.Connect("localhost");

  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:

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

            On macOS, the path would look something like this:

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.




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 gdio.common.objects;
using System;
using gdio.unreal_api;
using Nunit.Framework;


namespace startertest
{
    public partial class Tests
    {
        ApiClient api;


        [OneTimeSetUp]
        public void Setup()
        {
  
            api = new ApiClient();


            //Connect to the client in the editor
            api.Connect("localhost");
        }


        [Test, Order(0)]
        public void Test1()
        {
            //Write tests here
            
        }


        [Test, Order(1)]
        public void Test2()
        {
            //Write tests here
        }


        [OneTimeTearDown]
        public void Disconnect()
        {
            api.Disconnect();
        }
    }
}


Common issues

  1. In order to simulate mouse clicks in the editor you will need to unset the "High DPI Support" flag in the editor preferences. Screenshot of the editor preference window, to illustrate how to disable "High DPI Support"

  2. You may want to "build clean" for your project. Doing so will delete the precompiled binaries for the plugin. To rectify this copy the "Binary" and " Intermediate" folders from within the original plugin to your project's Plugin folder after making clean (or recopy the entire Plugin folder - if you prefer)


Limitations

  • Mouse and touch events do not work with headless execution at this time.