Skip to content

M2.2 — Anatomy of a Gauntlet command line

What you'll learn

  • The core parameters every RunUnreal invocation needs, and what each selects.
  • The difference between Gauntlet parameters and game arguments passed through to the launched processes.
  • How to read an unfamiliar command line and predict what session it will produce.

How it applies (QA)

The command line is the test configuration for the built-in tests — no C# required. Most of a QA owner's day-one Gauntlet work is constructing, reading, and tweaking these. A misread -build or a missing -platform is the difference between "tested the PS5 shipping build" and "tested nothing useful."

Concepts

The core parameters

Parameter Selects Example
RunUnreal the UAT command itself (positional) RunUAT RunUnreal ...
-test= which test node(s) to run; comma-separated for several -test=UE.BootTest
-project= the game project -project=ShooterGame
-platform= the target platform -platform=Win64 / PS5 / Android
-configuration= build configuration -configuration=Development / Test / Shipping
-build= where the cooked build is -build=local / a staged path / a build id
-device= which device to run on (optional; defaults to local) -device=10.1.2.3 / a devkit name

The first six are the backbone. -platform, -configuration, and -build together pin down exactly which artifact runs — get any wrong and you've tested a different build than you think.

Build configuration is not platform

-platform is the hardware/OS target. -configuration is which compile of the code:

  • Development — full logging, asserts, and tooling; what you usually test against in QA.
  • Test — closer to shipping (most debug stripped) but keeps some testability hooks; the configuration many automated suites target.
  • Shipping — final, stripped; least introspectable. Some log-based assertions won't work here because the log lines they look for are compiled out.

A test that passes in Development because it greps a UE_LOG line can silently change behavior in Shipping where that log is gone. Knowing your -configuration is part of knowing what your assertion can even see.

Gauntlet parameters vs. pass-through game args

Two audiences share one command line:

  • Gauntlet parameters (above) configure the harness: what to run, where, on what.
  • Game arguments are forwarded to the launched Unreal processes — the same switches you'd put on a normal game command line (-windowed, -resx=1280 -resy=720, -nullrhi, -ExecCmds=..., map overrides, etc.). They tune the game, not the test framework.

The mental split: Gauntlet args decide the session; game args decide how each process inside the session behaves. Built-in tests also expose their own extra options (e.g. a boot-timeout) that sit on the Gauntlet side.

Pitfall: testing the wrong configuration

"It works in our nightly but fails in cert" frequently reduces to a -configuration mismatch: nightly ran Development, cert runs Shipping/Test, and a Development-only log line or assert changed the behavior or the assertion's visibility. Always record the exact -platform/-configuration/-build triple alongside a result.

Worked example

Read this command and predict the session before running it:

RunUAT.bat RunUnreal -test=UE.BootTest -project=ShooterGame ^
    -platform=PS5 -configuration=Test -build=\\builds\ShooterGame\CL-48211\PS5 ^
    -device=DevKit-07 -resx=1920 -resy=1080

Prediction:

  • Test: the built-in boot test (UE.BootTest) — launch, confirm it boots, no crash.
  • Artifact: the Test configuration, PS5, from the staged build at CL-48211.
  • Where: DevKit-07 (a console devkit), not the local PC.
  • Game args: -resx/-resy forwarded to the game process (1080p).
  • Gauntlet's job here: install that staged build on the devkit, launch it 1080p, watch for a successful boot and no crash, collect logs, report.

Exercise 1 — Label each token

For the command above, tag every token as command, Gauntlet param, or pass-through game arg: RunUnreal, -test=UE.BootTest, -project=ShooterGame, -platform=PS5, -configuration=Test, -build=\\builds\...\PS5, -device=DevKit-07, -resx=1920, -resy=1080.

Lab — Build three command lines

Write RunUnreal command lines for these three scenarios. State any assumption you make about -build/-device explicitly (and mark it verify on a real build):

  1. Run the editor automation tests for ShooterGame on Win64, Development, local build.
  2. Boot-test the Shipping Android build (CL 50000) on a device at IP 10.0.0.42.
  3. Run UE.BootTest and UE.PLMTest in one invocation on a local Win64 Development build.

Exercise 2 — Predict the blind spot

A suite asserts "passed" by matching the log line LogShooter: Smoke OK, and runs -configuration=Shipping. The game wraps that log in UE_LOG(LogShooter, Display, ...), which is compiled out of Shipping. What happens to the test, and what's the fix?

Self-check — answers

Exercise 1: command — RunUnreal; Gauntlet params — -test, -project, -platform, -configuration, -build, -device; pass-through game args — -resx, -resy.

Lab (shape, not exact tokens):

  1. RunUAT.bat RunUnreal -test=UE.EditorAutomation -project=ShooterGame -platform=Win64 -configuration=Development -build=editor
  2. RunUAT.bat RunUnreal -test=UE.BootTest -project=ShooterGame -platform=Android -configuration=Shipping -build=\\builds\ShooterGame\CL-50000\Android -device=10.0.0.42
  3. RunUAT.bat RunUnreal -test=UE.BootTest,UE.PLMTest -project=ShooterGame -platform=Win64 -configuration=Development -build=local

Note the comma-list in -test=. Verify on a real build: -build=editor/local tokens and device addressing vary by studio config.

Exercise 2: The Shipping build never prints LogShooter: Smoke OK (the log is stripped), so the matcher never fires and the test fails/ times out even though the game booted fine — a false negative. Fixes: assert on something present in Shipping (an exit code, a marker that isn't a stripped Display/Verbose log, a TestController signal), or run the suite in a configuration where the log survives. The deeper lesson: assertions must be visible in the configuration you ship.

Done when

  • [ ] You can list the six core parameters and what each pins down.
  • [ ] You can distinguish a Gauntlet parameter from a pass-through game argument.
  • [ ] You can explain how -configuration can change whether an assertion is even visible.
  • [ ] You can read an unfamiliar command line and describe the session it produces.

Next: M2.3 — The built-in tests.