Skip to content

M2.1 — RunUnreal & the UAT BuildCommand

What you'll learn

  • What RunUnreal is, and why it is a [UAT] BuildCommand rather than a standalone tool.
  • The invocation chain from RunUAT to a running test.
  • What RunUnreal does for you before any test logic executes.

How it applies (QA)

RunUnreal is the command you (or CI) actually type. Understanding that it's a UAT command — not a bespoke binary — explains where it lives, why it needs the automation assemblies compiled, and why its errors sometimes look like UAT errors. When a job dies before any test runs, this lesson is where you look.

Concepts

RunUnreal is a UAT command

RunUnreal is "a class that inherits from UAT's BuildCommand." UAT (UnrealAutomationTool) is Epic's C# automation harness; a BuildCommand is one named operation UAT can run (others you may know: BuildCookRun, BuildGraph). Gauntlet plugs into UAT by providing RunUnreal as one more command.

Consequences that matter:

  • It's C#, compiled into automation assemblies. RunUnreal and your tests live in *.Automation projects that UAT compiles on demand. If those don't compile, you never reach a test — you get a build error from UAT.

  • It runs through RunUAT. You invoke it with the RunUAT script, naming the command:

    Engine\Build\BatchFiles\RunUAT.bat RunUnreal -test=UE.BootTest -project=MyGame ^
    -platform=Win64 -configuration=Development -build=local

  • Its job is setup, then hand-off. RunUnreal "configures a number of parameters before constructing a list of tests and then executing them." It does not contain your test logic; it builds the context and starts the executor.

The invocation chain

RunUAT.bat RunUnreal -test=... -project=... -platform=...
   │
   ▼
UAT bootstraps: compiles/loads the *.Automation assemblies
   │
   ▼
UAT finds the RunUnreal BuildCommand and calls it
   │
   ▼
RunUnreal:
   • resolves the project and the build (UnrealBuildSource)
   • resolves target device(s) (ITargetDevice)
   • parses -test= into a list of test nodes (UnrealTestNode subclasses)
   • configures global options (configuration, platform, args)
   • hands the list to TestExecutor
   │
   ▼
TestExecutor: queues, runs, and monitors each test node to a verdict

Everything above the dashed "test runs" line is RunUnreal's responsibility. A failure there — can't find the project, can't compile the automation assembly, can't resolve -test= to a class, no build at the path — happens before your test's logic and is a RunUnreal/UAT problem, not a test bug.

Pitfall: a stale automation assembly runs old test code

Because the *.Automation assemblies are compiled C#, a test source change that wasn't recompiled means UAT happily runs the previous build of your test. "I fixed it but it still fails identically" is often a stale-assembly symptom. Force a recompile (or let UAT rebuild) before trusting a re-run.

Worked example

A CI job logs:

ERROR: Unable to find type for argument -test=UE.BootTset

Read it against the chain: UAT loaded fine, RunUnreal started, but parsing -test= failed to resolve UE.BootTset to a test node class. This is a typo (BootTset → BootTest) caught at the resolve -test= step — i.e. inside RunUnreal, before any session launched. No device, no build, no game was ever touched. The fix is the command line, not the test.

Exercise 1 — Above or below the line?

For each failure, say whether it happens in RunUnreal/UAT setup (above) or in the test's own execution (below):

  1. "Could not compile MyGame.Automation: syntax error in MyBootTest.cs."
  2. The game launched, ran 30s, and no "passed" marker appeared.
  3. "-test=UE.Boot does not match any known test."
  4. A client crashed mid-session.
  5. "Project 'MyGaem' not found."

Exercise 2 — Write the invocation

Write a complete RunUAT.bat command line that runs the built-in boot test for a project named ShooterGame, on Win64, Development, using a locally staged build. (Don't worry about exact optional flags; get the command and the five core parameters right.)

Self-check — answers

Exercise 1: 1 above (assembly won't compile — UAT), 2 below (session ran; verdict logic), 3 above (-test= resolution in RunUnreal), 4 below (in-session event), 5 above (project resolution in RunUnreal).

Exercise 2:

Engine\Build\BatchFiles\RunUAT.bat RunUnreal -test=UE.BootTest -project=ShooterGame ^
    -platform=Win64 -configuration=Development -build=local

Core five: command (RunUnreal), -test=, -project=, -platform=, -configuration=, plus a build source (-build=). -build=local / a staged path tells it where the cooked build is — remember Gauntlet won't cook it for you. Verify on a real build: the exact -build token your studio uses (local, editor, a UNC path, a build id) is project- and version-specific.

Done when

  • [ ] You can explain why RunUnreal is a UAT BuildCommand and what that implies about compilation.
  • [ ] You can recite the invocation chain from RunUAT to TestExecutor.
  • [ ] You can classify a pre-test failure as a RunUnreal/UAT problem vs. a test-logic problem.
  • [ ] You can write a minimal RunUnreal command line from memory.

Next: M2.2 — Anatomy of a Gauntlet command line.