第二十三章自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系#

一句话理解：UE 的自动化测试是四层金字塔——Simple Test（纯 C++ 逻辑单元——毫秒级、零依赖）验证算法和工具函数，Complex Test（Automation Spec——BDD 风格、Latent Commands 支持异步）验证跨帧行为和子系统交互，Functional Test（关卡内行为——Spawn Actor、模拟玩家输入、验证 Gameplay 结果）验证完整的游戏功能链路，Gauntlet（大规模集群——多设备并发、性能回归、崩溃监控）验证产品的整体质量。这四层构成了”提交前跑 Simple → PR 前跑 Complex → Nightly 跑 Functional → Release 跑 Gauntlet”的完整质量门禁——是工业级 UE 开发的”最后一道防线”。

23.1 概念直觉 —— 测试体系的四层金字塔#

flowchart TD subgraph Simple["Simple Test —— 纯逻辑单元"] S1["IMPLEMENT_SIMPLE_AUTOMATION_TEST\n毫秒级 / 零引擎依赖"] S2["测试：FString 拼接 / TArray 排序\n数学工具函数 / 字符串转换"] end subgraph Complex["Complex Test —— BDD 风格 + 异步"] C1["Automation Spec\nDescribe / It / BeforeEach / AfterEach"] C2["Latent Commands\nFEngineWaitLatentCommand / 自定义异步步骤"] C3["测试：子系统初始化 / 模块加载\n异步任务 / 网络消息序列化"] end subgraph Functional["Functional Test —— 关卡内行为"] F1["AFunctionalTest 子类\nSpawn Actor / 模拟输入 / 断言结果"] F2["bTrackPerformance / bLogPerformance\n性能基准对比——帧率/内存/加载时间"] F3["测试：AI 行为树 / GAS 技能激活\n角色移动 / UI 交互 / 加载性能"] end subgraph Gauntlet["Gauntlet —— 大规模集群"] G1["UnrealTestNode\n多设备并发 / 模拟真实玩家"] G2["BuildGraph + RunUAT\n自动构建 → 部署 → 测试 → 报告"] G3["测试：全量回归 / 性能回归\n多人联机 / 崩溃率监控"] end Simple --> Complex Complex --> Functional Functional --> Gauntlet style Simple fill:#2d6a4f,stroke:#40916c,color:white style Complex fill:#e85d04,stroke:#f48c06,color:white style Functional fill:#d00000,stroke:#e85d04,color:white style Gauntlet fill:#d00000,stroke:#e85d04,color:white

1
// ===== 测试四层速记 =====
2
//
3
// Simple Test（纯逻辑）：
4
//   不依赖 World / Actor / Component——只测纯 C++ 函数和算法。
5
//   零启动时间——适合 TDD（测试驱动开发），提交前跑一次。
6
//
7
// Complex Test（模块集成）：
8
//   可以加载模块、创建 UObject（通过 NewObject）、模拟帧推进。
9
//   支持 Latent Commands——"等 3 帧，然后检查状态"。
10
//
11
// Functional Test（关卡内）：
12
//   需要完整的 Game World——加载关卡、Spawn Actor、模拟输入。
13
//   测试完整的 Gameplay 链路——"按下攻击键 → 技能激活 → 敌人受伤"。
14
//
15
// Gauntlet（工业化）：
16
//   在 CI 服务器上自动构建 → 部署到多台设备 → 运行预定义测试流程。
17
//   主要用于性能回归和崩溃率监控——不是日常开发工具。

23.2 Simple Test —— IMPLEMENT_SIMPLE_AUTOMATION_TEST#

23.2.1 最简单的单元测试#

1
// ===== IMPLEMENT_SIMPLE_AUTOMATION_TEST：零依赖的纯逻辑测试 =====
2
//
3
// 特点：
4
//   ✓ 不创建 World / Actor / Component——纯 C++ 逻辑
5
//   ✓ 毫秒级执行——适合 TDD
6
//   ✓ 可在命令行运行——适合 CI
7
//   ✗ 不能做需要 UObject / World 的事情
8

9
#include "Misc/AutomationTest.h"
10

11
// ---------- 测试 1：工具函数单元测试 ----------
12
IMPLEMENT_SIMPLE_AUTOMATION_TEST(
13
    FMyMathTest,                                     // 测试类名——全局唯一
14
    "MyGame.Core.Math.Addition",                     // ★ 测试路径——用 . 分隔层级
15
    EAutomationTestFlags::ApplicationContextMask |    // 在编辑器或命令行运行
16
    EAutomationTestFlags::ProductFilter               // 归类为"产品质量测试"
17
)
18

19
bool FMyMathTest::RunTest(const FString& Parameters)
20
{
21
    // 测试加法
22
    int32 Result = 2 + 3;
23
    TestEqual(TEXT("2 + 3 should equal 5"), Result, 5);
24

25
    // 测试浮点近似相等
26
    float FloatResult = 1.0f / 3.0f;
27
    TestNearlyEqual(TEXT("1/3 ≈ 0.333"), FloatResult, 0.333f, 0.001f);
28

29
    // 测试布尔条件
30
    TestTrue(TEXT("5 > 3"), 5 > 3);
31
    TestFalse(TEXT("5 < 3 is false"), 5 < 3);
32

33
    // 测试空指针
34
    int32* NullPtr = nullptr;
35
    TestNull(TEXT("ptr should be null"), NullPtr);
36

37
    return true;  // 所有断言通过
38
}
39

40
// ---------- 测试 2：FString 操作 ----------
41
IMPLEMENT_SIMPLE_AUTOMATION_TEST(
42
    FStringTest,
43
    "MyGame.Core.String.Concatenation",
44
    EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter
45
)
46

47
bool FStringTest::RunTest(const FString& Parameters)
48
{
49
    FString Result = FString::Printf(TEXT("Hello %s"), TEXT("World"));
50
    TestEqual(TEXT("Printf result"), Result, FString(TEXT("Hello World")));
51

52
    FString Trimmed = FString(TEXT("  spaced  ")).TrimStartAndEnd();
53
    TestEqual(TEXT("Trim result"), Trimmed, FString(TEXT("spaced")));
54

55
    return true;
56
}
57

58
// ---------- 测试 3：TArray 操作 ----------
59
IMPLEMENT_SIMPLE_AUTOMATION_TEST(
60
    FTArraySortTest,
61
    "MyGame.Core.Containers.Sort",
62
    EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter
63
)
64

65
bool FTArraySortTest::RunTest(const FString& Parameters)
66
{
67
    TArray<int32> Numbers = { 5, 2, 8, 1, 9 };
68
    Numbers.Sort();
69

70
    TestEqual(TEXT("First element after sort"), Numbers[0], 1);
71
    TestEqual(TEXT("Last element after sort"), Numbers.Last(), 9);
72

73
    // 模板类型测试
74
    TArray<FString> Names = { TEXT("Zoe"), TEXT("Alice"), TEXT("Bob") };
75
    Names.Sort();
76
    TestEqual(TEXT("First name after sort"), Names[0], FString(TEXT("Alice")));
77

78
    return true;
79
}

23.2.2 AutomationTestFlags 速查#

1
// ===== EAutomationTestFlags：控制测试的运行环境与行为 =====
2
//
3
// ┌────────────────────────────────┬──────────────────────────────────┐
4
// │ Flag                            │ 含义                               │
5
// ├────────────────────────────────┼──────────────────────────────────┤
6
// │ ApplicationContextMask          │ 编辑器和命令行都运行（最常用）        │
7
// │ EditorContext                   │ 仅在编辑器中运行                    │
8
// │ CommandletContext               │ 仅在命令行/CI 中运行                 │
9
// │ ProductFilter                   │ 产品测试——显示在 Session Frontend 中 │
10
// │ SmokeFilter                     │ 冒烟测试——构建后快速验证              │
11
// │ StressFilter                    │ 压力测试——长时间运行                   │
12
// │ PerfFilter                      │ 性能测试——需要记录性能数据              │
13
// │ Disabled                        │ 禁用——当前跳过                        │
14
// └────────────────────────────────┴──────────────────────────────────┘
15

16
// ---------- 测试路径命名规范 ----------
17
//
18
// 路径用 . 分隔，按层级组织：
19
//   "Project.System.Feature.TestCase"
20
//
21
// 示例：
22
//   "MyGame.Inventory.AddItem.Success"
23
//   "MyGame.Inventory.AddItem.FullInventory"
24
//   "MyGame.Combat.Damage.Normal"
25
//   "MyGame.Combat.Damage.Critical"
26
//
27
// 这样在 Session Frontend 中可以按层级勾选要运行的测试

23.3 Automation Spec —— BDD 风格 + 异步测试#

23.3.1 Describe / It 结构#

1
// ===== Automation Spec：BDD（行为驱动开发）风格的测试 =====
2
//
3
// 与 Simple Test 的区别：
4
//   Simple → 一个类一个测试
5
//   Spec   → 一个类可包含多个 Describe / It 块——更好的组织结构
6
//
7
// 语法对照：
8
//   BDD 术语          Automation Spec
9
//   ────────          ────────────────
10
//   Describe          Describe("场景描述")
11
//   It                It("行为描述", [this](){ ... })
12
//   BeforeEach        BeforeEach([this](){ ... })
13
//   AfterEach         AfterEach([this](){ ... })
14

15
#include "Misc/AutomationTest.h"
16

17
BEGIN_DEFINE_SPEC(
18
    FInventorySpec,                                  // Spec 类名
19
    "MyGame.Inventory",                              // 测试路径
20
    EAutomationTestFlags::ApplicationContextMask |
21
    EAutomationTestFlags::ProductFilter
22
)
23
    // ★ 成员变量——在 BeforeEach 中初始化，在 It 中使用
24
    TArray<FString> Inventory;
25
    const int32 MaxSlots = 10;
26

27
END_DEFINE_SPEC(FInventorySpec)
28

29
void FInventorySpec::Define()
30
{
31
    // ★ Describe 块——一组相关的测试场景
32
    Describe("AddItem", [this]()
33
    {
34
        // ★ BeforeEach —— 每个 It 之前运行
35
        BeforeEach([this]()
36
        {
37
            Inventory.Reset();
38
            Inventory.Reserve(MaxSlots);
39
        });
40

41
        // ★ AfterEach —— 每个 It 之后运行
42
        AfterEach([this]()
43
        {
44
            Inventory.Reset();
45
        });
46

47
        // ★ It —— 单个测试用例
48
        It("should add item to empty inventory", [this]()
49
        {
50
            Inventory.Add(TEXT("Sword"));
51
            TestEqual(TEXT("Inventory count"), Inventory.Num(), 1);
52
            TestEqual(TEXT("First item"), Inventory[0], FString(TEXT("Sword")));
53
        });
54

55
        It("should reject item when inventory is full", [this]()
56
        {
57
            // 填满背包
58
            for (int32 i = 0; i < MaxSlots; ++i)
59
            {
60
                Inventory.Add(FString::Printf(TEXT("Item_%d"), i));
61
            }
62

63
            // 验证无法添加
64
            TestEqual(TEXT("Inventory is full"), Inventory.Num(), MaxSlots);
65
            TestTrue(TEXT("Cannot add more"), Inventory.Num() >= MaxSlots);
66
        });
67

68
        It("should not add duplicate items", [this]()
69
        {
70
            Inventory.Add(TEXT("Sword"));
71
            // 假设去重逻辑在此
72
            TestEqual(TEXT("Only one Sword"), Inventory.Num(), 1);
73
        });
74
    });
75

76
    Describe("RemoveItem", [this]()
77
    {
78
        BeforeEach([this]()
79
        {
80
            Inventory = { TEXT("Sword"), TEXT("Shield"), TEXT("Potion") };
81
        });
82

83
        It("should remove existing item", [this]()
84
        {
85
            Inventory.Remove(TEXT("Shield"));
86
            TestEqual(TEXT("Count after remove"), Inventory.Num(), 2);
87
            TestFalse(TEXT("Shield not in inventory"),
88
                Inventory.Contains(TEXT("Shield")));
89
        });
90

91
        It("should do nothing when removing non-existent item", [this]()
92
        {
93
            Inventory.Remove(TEXT("NonExistent"));
94
            TestEqual(TEXT("Count unchanged"), Inventory.Num(), 3);
95
        });
96
    });
97
}

23.3.2 Latent Commands —— 异步步骤测试#

1
// ===== Latent Commands：测试需要"等待帧"的逻辑 =====
2
//
3
// 适用场景：
4
//   - 测试异步加载（等待 FStreamableManager 回调）
5
//   - 测试多帧动画（等待动画 Blueprint 状态机切换）
6
//   - 测试网络消息（等待 RPC 往返）
7
//   - 测试延迟生成（等待 SpawnActor 的 BeginPlay 完成）
8
//
9
// 原理：
10
//   Latent Command 是一个队列——引擎逐帧执行队列中的每个 Command。
11
//   每个 Command 的 Update() 返回 true → 推进到下一个 Command。
12
//   每个 Command 的 Update() 返回 false → 下一帧继续执行该 Command。
13

14
#include "Tests/AutomationCommon.h"
15
#include "Misc/AutomationTest.h"
16

17
// ---------- ① 使用内置 Latent Command ----------
18
IMPLEMENT_SIMPLE_AUTOMATION_TEST(
19
    FLatentWaitTest,
20
    "MyGame.Core.Latent.WaitFrames",
21
    EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter
22
)
23

24
bool FLatentWaitTest::RunTest(const FString& Parameters)
25
{
26
    int32 FrameCount = 0;
27

28
    // ★ 等待 5 帧——每帧 FrameCount 递增
29
    ADD_LATENT_AUTOMATION_COMMAND(FEngineWaitLatentCommand(0.1f));  // 等待 0.1 秒
30

31
    // 自定义逻辑——检查 World 是否就绪
32
    // ⚠️ Latent Command 跨帧异步执行——不能引用捕获局部变量（会变成悬空引用）！
33
    //    必须使用 TSharedPtr 等智能指针保持生命周期
34
    TSharedPtr<int32> FrameCount = MakeShared<int32>(0);
35
    ADD_LATENT_AUTOMATION_COMMAND(FFunctionLatentCommand([FrameCount]()
36
    {
37
        (*FrameCount)++;
38
        // 返回 true → 推进到下一个 Command
39
        // 返回 false → 下一帧重新执行（用于等待异步操作）
40
        return *FrameCount >= 3;  // 执行 3 帧后推进
41
    }));
42

43
    // 最终验证
44
    ADD_LATENT_AUTOMATION_COMMAND(FFunctionLatentCommand([this, FrameCount]()
45
    {
46
        TestTrue(TEXT("At least 3 frames elapsed"), *FrameCount >= 3);
47
        return true;  // 测试完成
48
    }));
49

50
    return true;
51
}
52

53
// ---------- ② 自定义 Latent Command 类 ----------
54
// 适用：可复用的异步等待逻辑
55
class FWaitForConditionCommand : public IAutomationLatentCommand
56
{
57
public:
58
    TFunction<bool()> Condition;
59
    float TimeoutSeconds;
60
    double StartTime;
61

62
    FWaitForConditionCommand(TFunction<bool()> InCondition, float InTimeout = 5.0f)
63
        : Condition(InCondition)
64
        , TimeoutSeconds(InTimeout)
65
        , StartTime(FPlatformTime::Seconds())
66
    {
67
    }
68

69
    virtual bool Update() override
70
    {
71
        // 条件满足 → 推进
72
        if (Condition())
73
        {
74
            return true;
75
        }
76

77
        // 超时 → 强制推进（避免永久卡住测试）
78
        double Elapsed = FPlatformTime::Seconds() - StartTime;
79
        if (Elapsed > TimeoutSeconds)
80
        {
81
            UE_LOG(LogTemp, Error, TEXT("Latent Command timed out after %.1f seconds"), Elapsed);
82
            return true;  // 超时也推进——让后续断言检测到失败
83
        }
84

85
        return false;  // 下一帧继续
86
    }
87
};
88

89
// 使用示例：
90
void UseCustomLatentCommand()
91
{
92
    // ★ 使用 TSharedPtr 安全捕获——Latent Command 跨帧异步，局部变量栈已销毁
93
    TSharedPtr<bool> bAsyncDone = MakeShared<bool>(false);
94

95
    // 启动异步操作
96
    AsyncTask(ENamedThreads::AnyThread, [bAsyncDone]()
97
    {
98
        FPlatformProcess::Sleep(0.1f);
99
        *bAsyncDone = true;
100
    });
101

102
    // 等待异步完成（最多 5 秒超时）
103
    ADD_LATENT_AUTOMATION_COMMAND(
104
        FWaitForConditionCommand([bAsyncDone]() { return *bAsyncDone; }, 5.0f)
105
    );
106
}

23.4 Functional Test —— 关卡内行为测试#

23.4.1 AFunctionalTest 完整实战#

1
// ===== AFunctionalTest：在真实关卡中测试 Gameplay 行为 =====
2
//
3
// 特点：
4
//   ✓ 拥有完整的 Game World——可以 Spawn Actor、触发输入、运行 Gameplay
5
//   ✓ 在关卡中放置 AFunctionalTest Actor → 运行 → 自动断言
6
//   ✓ 支持 Latent 步骤——等待动画/粒子/AI 行为完成
7
//   ✗ 比 Simple/Complex Test 慢得多——需要加载关卡和资源
8
//
9
// 使用方式：
10
//   ① 创建一个继承 AFunctionalTest 的蓝图或 C++ 类
11
//   ② 在关卡中放置该 Actor
12
//   ③ Session Frontend → Automation → 找到你的测试 → 运行
13

14
#include "FunctionalTest.h"
15
#include "AITestsCommon.h"
16

17
UCLASS()
18
class AMyCombatFunctionalTest : public AFunctionalTest
19
{
20
    GENERATED_BODY()
21

22
public:
23
    virtual void StartTest() override
24
    {
25
        Super::StartTest();
26

27
        // ① 在测试起点生成敌人
28
        FActorSpawnParameters SpawnParams;
29
        SpawnParams.SpawnCollisionHandlingOverride =
30
            ESpawnActorCollisionHandlingMethod::AlwaysSpawn;
31

32
        EnemyActor = GetWorld()->SpawnActor<AMyEnemy>(
33
            AMyEnemy::StaticClass(),
34
            GetTransform(),    // 使用测试 Actor 的位置
35
            SpawnParams
36
        );
37

38
        if (!EnemyActor)
39
        {
40
            FinishTest(EFunctionalTestResult::Error,
41
                TEXT("Failed to spawn enemy"));
42
            return;
43
        }
44

45
        // ② 初始化敌人属性
46
        EnemyActor->Health = 100.0f;
47

48
        // ③ ★ AFunctionalTest 没有 AddCommand —— 它是普通 AActor，非 FAutomationTestBase
49
        //   多步异步测试通过 FTimerHandle 状态机驱动——每步定时触发下一步
50
        TestStep = 0;
51
        GetWorld()->GetTimerManager().SetTimer(
52
            TestStepTimer,
53
            this,
54
            &AMyCombatFunctionalTest::ExecuteTestStep,
55
            0.1f,   // 每 0.1s 推进一步——给 World 一帧时间稳定
56
            true    // 循环——在 ExecuteTestStep 中按 TestStep 分发
57
        );
58
    }
59

60
    void ExecuteTestStep()
61
    {
62
        switch (TestStep)
63
        {
64
            case 0:  // 第 1 步：模拟攻击
65
                ApplyDamageToEnemy(30.0f);
66
                TestStep++;
67
                break;
68

69
            case 1:  // 步骤 2：验证血量
70
                if (EnemyActor->Health != 70.0f)
71
                {
72
                    FinishTest(EFunctionalTestResult::Error,
73
                        FString::Printf(TEXT("Expected health 70, got %.1f"),
74
                            EnemyActor->Health));
75
                    GetWorldTimerManager().ClearTimer(TestStepTimer);
76
                    return;
77
                }
78
                TestStep++;
79
                break;
80

81
            case 2:  // 步骤 3：暴击伤害
82
                ApplyDamageToEnemy(100.0f);
83
                TestStep++;
84
                break;
85

86
            case 3:  // 步骤 4：验证死亡
87
                if (!EnemyActor->IsDead())
88
                {
89
                    FinishTest(EFunctionalTestResult::Error,
90
                        TEXT("Enemy should be dead"));
91
                }
92
                else
93
                {
94
                    FinishTest(EFunctionalTestResult::True,
95
                        TEXT("Combat test passed!"));
96
                }
97
                GetWorldTimerManager().ClearTimer(TestStepTimer);
98
                break;
99
        }
100
    }
101

102
    void ApplyDamageToEnemy(float Damage)
103
    {
104
        if (EnemyActor)
105
        {
106
            EnemyActor->Health -= Damage;
107
            if (EnemyActor->Health <= 0.0f)
108
            {
109
                EnemyActor->OnDeath();
110
            }
111
        }
112
    }
113

114
protected:
115
    UPROPERTY()
116
    TObjectPtr<AMyEnemy> EnemyActor;
117

118
    int32 TestStep = 0;
119
    FTimerHandle TestStepTimer;
120
};

23.4.2 性能基准测试#

1
// ===== 用 Functional Test 做性能基准 =====
2
//
3
// AFunctionalTest 内置了性能监控——设置期望的帧率/内存阈值
4
// 测试运行时自动记录性能数据——超标则标记为失败
5

6
UCLASS()
7
class AMyPerformanceTest : public AFunctionalTest
8
{
9
    GENERATED_BODY()
10

11
public:
12
    AMyPerformanceTest()
13
    {
14
        // ★ 性能基准——通过 bTrackPerformance / bLogPerformance 开启官方追踪
15
        //   AFunctionalTest 上不存在 AutomationPerfMonitor —— 这是幻觉 API
16
        //   bTrackPerformance = true  → 自动记录帧率/内存/加载时间到日志
17
    }
18

19
    virtual void StartTest() override
20
    {
21
        Super::StartTest();
22

23
        // 生成大量 AI 来压测
24
        SpawnStressTestActors();
25

26
        // 用 Timer 驱动性能采样——第 60 次 Tick 后检查帧率
27
        PerformanceFrameCount = 0;
28
        GetWorld()->GetTimerManager().SetTimer(
29
            PerformanceTimer,
30
            [this]()
31
            {
32
                PerformanceFrameCount++;
33

34
                // 等场景稳定——第 60 帧后检查性能
35
                if (PerformanceFrameCount < 60) return;
36

37
                GetWorldTimerManager().ClearTimer(PerformanceTimer);
38

39
                float FrameTimeMs = FApp::GetDeltaTime() * 1000.0f;
40
                float TargetFrameTimeMs = 1000.0f / 30.0f;  // 30fps target
41

42
                if (FrameTimeMs > TargetFrameTimeMs)
43
                {
44
                    FinishTest(EFunctionalTestResult::Error,
45
                        FString::Printf(TEXT("Frame time %.2fms exceeds target %.2fms (30fps)"),
46
                            FrameTimeMs, TargetFrameTimeMs));
47
                }
48
                else
49
                {
50
                    FinishTest(EFunctionalTestResult::True,
51
                        FString::Printf(TEXT("Performance OK: %.2fms (%.0f fps)"),
52
                            FrameTimeMs, 1000.0f / FrameTimeMs));
53
                }
54
            },
55
            0.05f,  // 每 50ms 采样一次
56
            true    // 循环
57
        );
58
    }
59

60
    void SpawnStressTestActors()
61
    {
62
        for (int32 i = 0; i < 50; ++i)
63
        {
64
            FVector RandomLoc = FVector(
65
                FMath::RandRange(-1000, 1000),
66
                FMath::RandRange(-1000, 1000),
67
                0
68
            );
69
            GetWorld()->SpawnActor<AMyEnemy>(AMyEnemy::StaticClass(),
70
                FTransform(RandomLoc));
71
        }
72
    }
73
};

23.5 Gauntlet 框架概览 —— 大规模工业化测试#

23.5.1 Gauntlet 是什么#

1
// ===== Gauntlet：UE 的大规模自动化测试框架 =====
2
//
3
// 定位：不是日常开发工具——是 CI/CD 管线中的"最终质量门禁"。
4
//
5
// 核心能力：
6
//   ① 自动构建 → 自动部署到集群设备 → 自动运行测试 → 自动收集报告
7
//   ② 支持多设备并发——同时测试 PC + Console + Mobile
8
//   ③ 模拟真实玩家行为——Controller 驱动的输入回放
9
//   ④ 长期稳定性测试——连续运行 24 小时检测内存泄漏和性能退化
10
//
11
// Gauntlet 的工作流：
12
//   Build（UBT 编译）→ Deploy（部署到测试设备）→ Test（运行测试）→ Report（生成报告）
13
//
14
// 关键组件：
15
//   UnrealTestNode   → 测试节点的控制器——管理单台设备的测试流程
16
//   Gauntlet.Config  → JSON 配置文件——定义构建/部署/测试参数
17
//   BuildGraph       → 构建脚本——定义完整的 CI 流水线步骤
18
//   RunUAT           → 命令行入口——启动 Gauntlet 测试
19

20
// ===== Gauntlet 简化配置文件示例（JSON） =====
21
/*
22
{
23
    "ClientTest": {
24
        "MapName": "TestMap_Main",
25
        "TestList": [
26
            "MyGame.Functional.Combat.MeleeAttack",
27
            "MyGame.Functional.Movement.SprintAndJump",
28
            "MyGame.Performance.MainMenu_30fps"
29
        ],
30
        "NumClients": 2,
31
        "MaxDuration": 3600,
32
        "ExpectedFPS": 30,
33
        "MaxMemoryMB": 4000,
34
        "bCaptureTraceOnFailure": true
35
    }
36
}
37
*/

23.6 CI/CD 集成 —— 在自动化流水线中跑测试#

23.6.1 命令行运行测试#

1
// ===== 在 CI 中运行自动化测试 =====
2
//
3
// 三种运行方式——按复杂度递增：
4

5
// ---------- ① 编辑器内运行（开发期） ----------
6
// UE5Editor.exe MyProject.uproject
7
//   -ExecCmds="Automation RunTests MyGame.Core"
8
//   -NullRHI          ← 无渲染——纯逻辑测试不需要 GPU
9
//   -Unattended       ← 无人值守——不弹对话框
10
//   -Log              ← 输出日志到文件
11

12
// ---------- ② Development 构建运行 ----------
13
// MyProject.exe
14
//   -RunAutomationTests="MyGame.Core.Math;MyGame.Core.String"
15
//   -TestExit="Automation Test Queue Empty"
16
//   -NullRHI
17
//   -Unattended
18
//   -Log=TestResults.log
19

20
// ---------- ③ RunUAT 运行 Gauntlet 测试 ----------
21
// RunUAT.bat BuildGraph
22
//   -Script=Engine/Build/InstalledEngineBuild.xml
23
//   -Target=Submit Test
24
//   -Set:WithClient=true
25
//   -Set:WithServer=false
26

27
// ---------- 测试退出码 ----------
28
// 0 → 所有测试通过
29
// 1 → 至少一个测试失败
30
// 其他 → 引擎启动失败 / 崩溃

23.6.2 Session Frontend —— 编辑器测试面板#

1
// ===== Session Frontend：编辑器中的测试管理界面 =====
2
//
3
// 打开方式：Window → Developer Tools → Session Frontend
4
//           → 切换到 "Automation" 标签页
5
//
6
// 功能：
7
//   ✓ 按层级树浏览所有测试（Simple / Complex / Functional）
8
//   ✓ 勾选要运行的测试 → 点击 "Start Tests"
9
//   ✓ 实时查看每个测试的状态（Running / Passed / Failed）
10
//   ✓ 查看失败测试的日志和断言详情
11
//   ✓ 导出测试报告
12
//
13
// 快捷键：
14
//   Ctrl+Shift+F5 → 运行当前关卡中放置的所有 Functional Test

23.7 常见陷阱与面试深度追问#

23.7.1 自动化测试 TOP 5 陷阱#

1
// ===== 陷阱 #1：测试依赖执行顺序 =====
2
// ✗ 假设测试按字母顺序执行——TestA 创建的资源 TestB 继续使用
3
//   → 实际执行顺序不可控——TestB 可能在 TestA 之前运行
4
// ✓ 每个测试独立创建所需状态——BeforeEach / 构造函数初始化
5

6
// ===== 陷阱 #2：在 Simple Test 中创建 World / Actor =====
7
// ✗ IMPLEMENT_SIMPLE_AUTOMATION_TEST 中调用 GetWorld() / SpawnActor
8
//   → Simple Test 没有 Game World——空指针崩溃
9
// ✓ Simple Test 只做纯逻辑；需要 World 用 Functional Test
10

11
// ===== 陷阱 #3：Latent Command 忘记超时机制 =====
12
// ✗ FFunctionLatentCommand 中永远返回 false——等待一个永不满足的条件
13
//   → 测试永久挂起——CI 超时（通常 30 分钟后才被 Kill）
14
// ✓ 每个循环等待的 Latent Command 必须有超时——超时后返回 true + 标记失败
15

16
// ===== 陷阱 #4：Functional Test 用错了异步机制 =====
17
// ✗ 试图在 AFunctionalTest 中调用 AddCommand / FFunctionalTestLatentCommand
18
//   → AFunctionalTest 是普通 AActor——没有 AddCommand 接口，编译硬错
19
// ✓ AFunctionalTest 的多步异步通过 FTimerHandle 状态机驱动——
20
//   每步在 Tick/Timer 回调中执行，测试结束时调用 FinishTest()
21

22
// ===== 陷阱 #5：不写测试——"代码很简单不需要测试" =====
23
// ✗ "这个函数太简单了" → 然后 6 个月后重构出 Bug
24
//   → 没有测试 = 没有安全网 = 重构恐惧症
25
// ✓ Simple Test 写一个只需 30 秒——投资回报率 ∞

23.7.2 面试速记三连#

1
Q: "UE 的自动化测试分几层？每层适用什么场景？"
2
A: 四层——① Simple Test（IMPLEMENT_SIMPLE_AUTOMATION_TEST）：纯 C++ 逻辑、
3
   毫秒级、零引擎依赖——测算法和工具函数。② Complex Test（Automation Spec +
4
   Latent Commands）：BDD 风格、支持异步等待——测模块初始化和子系统交互。
5
   ③ Functional Test（AFunctionalTest）：关卡内行为——测完整 Gameplay 链路
6
   （战斗/移动/UI 交互）。④ Gauntlet：大规模 CI 集群——多设备并发、性能回归、崩溃监控。
7

8
Q: "Latent Command 是什么？什么时候用？"
9
A: Latent Command 是测试中的异步步骤队列——引擎逐帧执行每个 Command 的 Update()。
10
   Update 返回 true → 推进到下一步，返回 false → 下一帧继续执行。
11
   适用：等待异步加载完成、等待动画播放、等待网络 RPC、等待帧稳定后测性能。
12
   内置：FEngineWaitLatentCommand（按时间等待）、FFunctionLatentCommand（自定义条件）。
13
   自定义：继承 IAutomationLatentCommand 并覆写 Update()。
14

15
Q: "怎么把 UE 的自动化测试集成到 CI/CD 流水线中？"
16
A: ① 命令行运行：-RunAutomationTests="TestGroup" + -NullRHI -Unattended
17
   -TestExit 退出码 0=通过 1=失败。② BuildGraph 脚本编排：Build → Deploy
18
   → Test → Report。③ Gauntlet 框架做大规模回归——自动构建+部署+测试+报告。
19
   ④ Jenkins/GitHub Actions 调用 RunUAT BuildGraph 触发整个流水线。

23.8 30 秒速答#

面试被问：“你写过 UE 的自动化测试吗？项目里怎么做的？”

四层体系——Simple Test：IMPLEMENT_SIMPLE_AUTOMATION_TEST 测所有纯 C++ 工具函数（数学/字符串/容器），每次提交前本地跑，30 秒内完成。Complex Test：BEGIN_DEFINE_SPEC + Describe/It BDD 风格测模块集成（背包系统/属性计算），PR 时 CI 跑。Functional Test：AFunctionalTest 子类在关卡中测完整 Gameplay（AI 行为树/技能激活），Nightly 构建跑。Gauntlet：大规模 CI 集群做性能回归和崩溃监控，Release 前跑全量。

面试追问：“Simple Test 和 Complex Spec Test 的区别？什么时候用哪个？”

Simple Test（IMPLEMENT_SIMPLE_AUTOMATION_TEST）：一个类一个测试——适合单一职责的纯逻辑测试（FMath::Clamp 边界值）。Spec Test（BEGIN_DEFINE_SPEC + Describe/It）：一个类包含多个场景——适合有状态的模块测试（背包系统的增删查改），BeforeEach 在每个 It 之前重置状态。规则：单一函数测 Simple，多场景模块测 Spec。

面试追问：“Functional Test 怎么模拟玩家输入？”

AFunctionalTest 运行在完整 Game World 中——在 StartTest() 中通过 FTimerHandle 分步驱动：Spawn Actor → 用 APlayerController::InputKey(FKey("LeftMouseButton"), IE_Pressed) 模拟按键 → SetControlRotation() 模拟视角 → 定时器回调中逐帧检查关键状态变更（血量/Montage/AI 行为树节点）。所有步骤走完后调用 FinishTest(EFunctionalTestResult::Succeeded)。★ 注意：AFunctionalTest 没有 AddCommand——那是 Spec Test 的接口。

面试追问：“怎么在 CI 中跑 UE 测试并获取结果？”

命令行：MyProject.exe -RunAutomationTests="MyGame." -NullRHI -Unattended -TestExit="Automation Test Queue Empty" -Log=TestResults.log。进程退出码：0 = 全过，1 = 有失败。CI 脚本（Jenkins/GitHub Actions）解析 TestResults.log 或退出码判断通过/失败。进阶：用 BuildGraph XML 脚本编排完整的 Build → Cook → Test → Report 流水线。

面试追问：“测试驱动开发（TDD）在 UE 中可行吗？怎么实践？”

可行且推荐——但适用范围有边界。TDD 适用：纯 C++ 工具函数（数学库/容器扩展/序列化）→ Simple Test 先写 → 秒级反馈。TDD 不适用：需要 Game World 的 Gameplay 逻辑 → 测试启动成本太高（加载关卡 + 资源），不适合秒级迭代。实践策略：工具层 TDD（Simple Test），Gameplay 层先实现再补 Functional Test。

23.9 本章自查清单#

📚 第四部第五章完结 · 全系列终章。 自动化测试是工业化开发的最后一道防线——Simple Test 守住代码质量，Complex Spec 守住模块契约，Functional Test 守住 Gameplay 行为，Gauntlet 守住产品底线。最好的测试不是”上线前补”，而是”写代码时就跟着写”——每写一个函数，花 30 秒加一个 Simple Test，你就在为自己 6 个月后的重构买下最便宜的保险。

🏁 全系列 23 章完结。 从第一部 UE C++ 语言体系（Ch1-Ch7：类型系统/反射/GC/容器/智能指针/委托/多线程），到第二部引擎核心框架（Ch8-Ch13：Actor/GameFramework/输入/UI/网络/数据驱动），到第三部工业化核心子系统（Ch14-Ch18：GAS/AI/动画/物理/音频），到第四部工程实践（Ch19-Ch23：构建系统/编码规范/性能优化/编辑器扩展/自动化测试），这套笔记覆盖了从”会写 UE C++“到”能在团队中交付工业化产品”的全部核心知识。
下一步：把这 23 章的内容转化为你自己的项目实践——每学一章，在你的个人项目中实现对应功能。知识的真正内化不在阅读，在于亲手写出能跑、能测、能交付的代码。🚀

💡 前置依赖提醒：

构建系统（CI 中编译项目的 UBT 流程） → 见 Ch19：模块与构建系统

编码规范（check/ensure 在测试中的使用） → 见 Ch20：Epic 编码规范与最佳实践

GAS 技能系统（Functional Test 验证技能激活链路） → 见 Ch14：GAS 技能系统

数据驱动与资源管理（DataAsset 的 Simple Test 验证） → 见 Ch13：数据驱动与资源管理

音乐

音乐

第二十三章自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系#

23.1 概念直觉 —— 测试体系的四层金字塔#

23.2 Simple Test —— IMPLEMENT_SIMPLE_AUTOMATION_TEST#

23.2.1 最简单的单元测试#

23.2.2 AutomationTestFlags 速查#

23.3 Automation Spec —— BDD 风格 + 异步测试#

23.3.1 Describe / It 结构#

23.3.2 Latent Commands —— 异步步骤测试#

23.4 Functional Test —— 关卡内行为测试#

23.4.1 AFunctionalTest 完整实战#

23.4.2 性能基准测试#

23.5 Gauntlet 框架概览 —— 大规模工业化测试#

23.5.1 Gauntlet 是什么#

23.6 CI/CD 集成 —— 在自动化流水线中跑测试#

23.6.1 命令行运行测试#

23.6.2 Session Frontend —— 编辑器测试面板#

23.7 常见陷阱与面试深度追问#

23.7.1 自动化测试 TOP 5 陷阱#

23.7.2 面试速记三连#

23.8 30 秒速答#

23.9 本章自查清单#

文章分享

评论区

音乐

目录

音乐

音乐

第二十三章 自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系

第二十三章 自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系#

23.1 概念直觉 —— 测试体系的四层金字塔#

23.2 Simple Test —— IMPLEMENT_SIMPLE_AUTOMATION_TEST#

23.2.1 最简单的单元测试#

23.2.2 AutomationTestFlags 速查#

23.3 Automation Spec —— BDD 风格 + 异步测试#

23.3.1 Describe / It 结构#

23.3.2 Latent Commands —— 异步步骤测试#

23.4 Functional Test —— 关卡内行为测试#

23.4.1 AFunctionalTest 完整实战#

23.4.2 性能基准测试#

23.5 Gauntlet 框架概览 —— 大规模工业化测试#

23.5.1 Gauntlet 是什么#

23.6 CI/CD 集成 —— 在自动化流水线中跑测试#

23.6.1 命令行运行测试#

23.6.2 Session Frontend —— 编辑器测试面板#

23.7 常见陷阱与面试深度追问#

23.7.1 自动化测试 TOP 5 陷阱#

23.7.2 面试速记三连#

23.8 30 秒速答#

23.9 本章自查清单#

文章分享

评论区

音乐

目录

第二十三章自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系

第二十三章自动化测试：从 Unit Test 到 Gauntlet 的完整测试体系#