Gauntlet Primer

Development Platform & Builds
, ,
1

Article written by Branden T.
The official Gauntlet Documentation is a great place to start!

Gauntlet has two parts. A UAT (Unreal Automation Tool) based framework written in C# (located at [UE_Root]/Engine/Source/Programs/AutomationTool/Gauntlet ), and a helper plugin for Unreal ( located at [UE_Root]/Engine/Plugins/Experimental/Gauntlet ) that provides convenience functions for managing and responding to state changes that can occur during testing.

It’s important to understand that Gauntlet is not a testing framework per-se (there are already several options in Unreal for this that cover different needs and preferences). Gauntlet is “a way to run things” and provides the following:

  • Low level interfaces around platforms, devices, builds, and sessions.
    • E.g. you can (and we do) write a Gauntlet script that says "take a build at this path, copy it to the N devices in this list, then run them with these command-lines.
  • High-level interfaces that can define “sessions”
    • E.g. “Run a server and 100 clients using this build, this mix of platforms, and these arguments”

In both cases Gauntlet will manage discovery/reservation of devices, installation of builds, launching processes, monitoring the health of those processes, and retrieval of artifacts (logfiles, screenshots, crashdumps). We use Gauntlet both for automation on the farm and day to day developer and QA workflows. E.g. devs have a Gauntlet script that can pull any Fortnite build from the network, deploy it on their kit, and launch it with their locally built executables.

Aside from the source of the C# and plugin side, there are additional resources that will help you understand Gauntlet further:

One of the better examples of using the Gauntlet system with an actual game that we have is located in the Shooter Game sample that’s available through the Epic Games Launcher.

  • After you download that project, in [ProjectRoot]/Build/Scripts there should be a ShooterGame automation C# project that you can explore that drives the tests. That can also be leveraged through BuildGraph, and there’s an example of doing so in [ProjectRoot]/Build/ShooterGameBuild.xml if you’re curious about that side of things.

  • The ShooterGameBuild file also has references to running projects for other platforms (using the -platform command line argument for the test runner)

  • One additional set of parameters that’ve been helpful to a lot of users is using the -device="XXXX" or -devices="XXXX,XXXX" parameters, to specify a specific device UUID or IP that you want Gauntlet to run on.

  • To get some more specific information on what command line parameters are available to use, check out
    [UE_Root]/Engine/Source/Programs/AutomationTool/Gauntlet/Unreal/Base/Gauntlet.UnrealTestContext.cs

For more implementation details for the tests, there’s also the project’s native test controller code located in [ProjectRoot]/Source/ShooterGame/Private[ or Public]/Tests/ .

This should be a good foundation in Gauntlet and get you on your way to using it for your projects!