Using GameDriver with Gauntlet in Unreal Engine

Learn how to integrate GameDriver with Gauntlet in Unreal Engine and gain additional testing capabilities

If you’re already running in Gauntlet with C++ tests, you can simply integrate GameDriver C++ API calls into your tests.

In your existing custom controller, use GameDriver's C++ API.

UGDIOApi::ClickObject(EKeys::LeftMouseButton, "/simpleButton_C_0/Button", 30);

A complete listing of the Unreal C++ GameDriver API shows that you can use the powerful HPath syntax as well as a large subset of the GameDriver API in addition to any C++ code you want. You can also see some examples here.

Using Gauntlet and GameDriver with C#. 

Suppose you’ve not started testing in Unreal’s C++ framework, or you’re looking for an easier way to write game tests. In that case, there’s a second way to use Gauntlet and GameDriver where you bypass the Unreal testing framework altogether, and still utilize Gauntlet to manage test execution. This methodology lets you write tests in C# using GameDriver’s API, which can then be executed remotely on mobile, consoles, and desktop.

You weave GameDriver’s API into the StartTest portion of your Gauntlet test script and can return pass/fail information as well as artifacts as required:

using gdio.unity_api;  // Required for GameDriver API
using gdio.common.objects;
using EpicGameAutomation;

public class GameDriverGauntletTest : UnrealTestNode
{
    private ApiClient api; // The GameDriver API client.
    private UnrealSession session;

    public override UE4TestConfig GetConfiguration()
    {
        UE4TestConfig Config = base.GetConfiguration();
        UnrealTestRole ClientRole = Config.RequireRole(UnrealTargetRole.Client);

        // Launch game
        ClientRole.CommandLine += "-EnableAutomation";

        Config.MaxDuration = 300;
        return Config;
    }

    public override void StartTest()
    {
        base.StartTest();

        // Initialize the GameDriver API client
        api = new ApiClient();

        try
        {
            // Connect to the Unity game running on localhost with default port 19734
            // Parameters: hostname, port, autoplay, timeout, autoPortResolution
            api.Connect("localhost", 19734, true, 60, true);
            
            Console.WriteLine("Successfully connected to Unity game!");
        }

        catch (Exception ex)
        {
            Console.WriteLine($"Failed to connect to Unity game: {ex.Message}");
            throw;
        }

        // Start your test sequence!
        ExecuteTestLogic();
    }

    private void ExecuteTestLogic()
    {
        // Get the current scene name
        string sceneName = api.GetSceneName();

        Console.WriteLine($"Current scene: {sceneName}");

        gdio.common.objects.Vector3 initialPosition;

        // Get player position in world space
        initialPosition = api.GetObjectPosition(playerHPath, CoordinateConversion.None);

        // Press the W key for the specified number of frames
        Console.WriteLine($"Pressing W key for {durationInFrames} frames...");

        api.KeyPress(new KeyCode[] { KeyCode.W }, durationInFrames);
        
        // Wait a bit to ensure physics and animations complete
        api.Wait(1000);
        
        // Get position after moving
        gdio.common.objects.Vector3 finalPosition;

        finalPosition = api.GetObjectPosition(playerHPath, CoordinateConversion.None);

        // Calculate the distance moved
        double distanceMoved = CalculateDistance(initialPosition, finalPosition);

        Console.WriteLine($"Player moved: {distanceMoved:F2} units");

        //Integrate with UnrealTestNode functions to return the test result to Gauntlet. 
        SetUnrealTestResult(TestResult.Passed);
    }

    public override void StopTest(bool WasCancelled)
    {
        Console.WriteLine("Disconnecting from Unity game...");
        api.Disconnect();
    }
}

Run the test using Gauntlet's standard CLI, with no C++ code required:

RunUAT.bat RunUnreal -project=YourProject -test=GameDriverGauntletTest -build=Path/To/Build

Advantages

• No C++ Code: Entire test logic lives in C#.
• Direct Orchestration: Control test flow and assertions directly in Gauntlet.
• Portability: Tests can run on any platform where GameDriver's agent is active.
• Integration: Use the reporting and device management strengths of Gauntlet/Horde
• Portability. Easy to run GameDriver tests with/without Gauntlet.