M4.1 — Project setup & the test node

What you'll learn

• The prerequisites to author a Gauntlet test: a source engine and a *.Automation project.
• The base classes a test derives from — ITestNode, UnrealTestNode, DefaultTest.
• How UAT discovers your test and how -test= resolves to your class.

How it applies (QA)

The first time you go from running built-ins to writing a test, the friction is almost never the test logic — it's project setup: wrong project type, not a source build, the assembly not discovered, -test= not resolving. This lesson removes that friction so M4.2–M4.4 are about logic, not plumbing.

Concepts

Two hard prerequisites

1. A source build of the engine. Gauntlet's authoring side is C# that compiles alongside [UAT]; you cannot author against a launcher (binary) install. If you only have a launcher engine, you can't write Gauntlet tests — full stop.
2. A *.Automation project. Your test lives in a Class Library (.NET Framework) project whose name ends in .Automation (e.g. ShooterGame.Automation). UAT scans for these, compiles them, and loads the test types they contain. The .Automation suffix is the discovery convention — miss it and UAT never sees your test.

The base classes

• ITestNode — the interface every test implements (tier 1). It defines the lifecycle contract TestExecutor drives. You rarely implement it directly.
• UnrealTestNode<TConfig> — the Unreal-aware base class you actually derive from (tier 3). It implements ITestNode "largely by configuring an UnrealSession object and calling its relevant functions," so you inherit session launch/monitor/teardown and override only what's specific to your test. TConfig is your UnrealTestConfiguration type (M4.2).
• DefaultTest — a ready base test the docs point to as a starting point; concrete tests are "a C# class based on the class DefaultTest." Treat it as the convenient on-ramp; UnrealTestNode is the general base beneath it.

Discovery and resolution

*.Automation project (Class Library, .NET Framework)
   └─ contains class MyBootTest : UnrealTestNode<MyConfig>
        │
   UAT compiles the assembly and registers its ITestNode types
        │
   RunUnreal -test=MyBootTest   ← resolves the name to your class
        │
   your test node is instantiated and handed to TestExecutor

So -test= takes the test type name (or a configured short/qualified name). The resolution you saw fail in M2.1 ("no type for argument -test=…") is this step not finding your class — usually because the assembly didn't compile, wasn't named *.Automation, or the name is misspelled.

Pitfall: launcher engine, no authoring

A surprising amount of "I can't get my Gauntlet test to build" ends at you're on a binary/ launcher engine. Authoring requires engine source so UAT can compile your .Automation assembly against the Gauntlet libraries. Confirm you have a source build before anything else.

Worked example — the smallest test skeleton

A boot test, reduced to its setup essentials (logic comes in M4.2–M4.3):

// ShooterGame.Automation/MyBootTest.cs   (Class Library, .NET Framework)
using Gauntlet;

namespace ShooterGame.Automation
{
    // Derive from the Unreal-aware base; MyBootTestConfig defined in M4.2.
    public class MyBootTest : UnrealTestNode<MyBootTestConfig>
    {
        public MyBootTest(UnrealTestContext context) : base(context) { }

        // GetConfiguration() (M4.2) declares the roles/args.
        // StartTest / TickTest / StopTest (M4.3) carry the logic.
    }
}

Run it:

RunUAT.bat RunUnreal -test=MyBootTest -project=ShooterGame ^
    -platform=Win64 -configuration=Development -build=local

Verify on a real build: exact namespaces, the usings, the constructor signature, and whether you derive from UnrealTestNode<T> directly or via DefaultTest vary by engine version. The load-bearing facts — source engine, *.Automation Class Library, derive from the Unreal test base, -test= resolves the type — are stable.

Exercise 1 — Diagnose the setup failure

For each, name the setup prerequisite it violates:

1. "UAT: no test type matches -test=MyBootTest" — but the file exists.
2. "Cannot find Gauntlet types" when compiling, on a launcher-installed engine.
3. The project is named ShooterGameTests and UAT never compiles it.

Exercise 2 — Name the base

A teammate's class is public class SmokeTest : ITestNode. They're re-implementing session launch and teardown by hand and it's hundreds of lines. What base should they use instead, and what do they get for free?

Self-check — answers

Exercise 1: 1 — the assembly didn't compile or the type/name isn't what -test= expects (a compile error upstream, or name mismatch); 2 — not a source engine, so the Gauntlet libraries aren't there to compile against; 3 — project name doesn't end in .Automation, so UAT's discovery skips it.

Exercise 2: Derive from UnrealTestNode<TConfig> (or DefaultTest). It implements ITestNode by driving an UnrealSession, so they inherit role launch, monitoring, crash/ensure detection, artifact collection, and teardown — overriding only configuration and their pass/fail logic instead of rebuilding the session machinery.

Done when

• [ ] You can state the two hard prerequisites (source engine, *.Automation Class Library).
• [ ] You can place ITestNode, UnrealTestNode<T>, and DefaultTest relative to each other.
• [ ] You can trace how -test= resolves to your class and why resolution fails.
• [ ] You can diagnose the common setup failures from their symptoms.

---

Next: M4.2 — Configuration & context.