UE4自动化测试插件UnrealAutomator实战：从零搭建Widget检测功能

在游戏开发领域，自动化测试已经成为保证产品质量不可或缺的一环。特别是对于使用虚幻引擎4(UE4)开发的项目，如何高效地构建自动化测试流程是每个技术团队都需要面对的挑战。本文将深入探讨如何利用UnrealAutomator插件，从零开始搭建一个完整的Widget检测功能，为你的UE4项目注入自动化测试能力。

1. UnrealAutomator插件概述与安装

UnrealAutomator是一款专为UE4游戏测试设计的开源插件，它通过HTTP协议提供了一套可扩展的自动化测试框架。与传统的测试工具相比，UnrealAutomator具有几个显著优势：

  • 轻量级架构：基于UE4内置的HTTP服务器框架，无需额外依赖
  • 模块化设计：功能模块清晰分离，便于二次开发和定制
  • 跨平台支持：适用于PC、移动端等多种平台
  • 丰富的API：提供Widget信息导出、输入模拟等核心功能

安装UnrealAutomator只需几个简单步骤：

  1. 从GitHub仓库下载最新版本插件
  2. 将插件文件夹复制到项目的Plugins目录下
  3. 打开项目，在编辑器中启用插件：
    编辑(Edit) -> 插件(Plugins) -> 测试(Testing) -> 勾选UnrealAutomator
  4. 重启编辑器使插件生效

提示：如果项目中已有同名插件，建议先备份再替换，避免冲突。

安装完成后，你可以在输出日志中看到类似信息，确认插件已成功加载：

LogUnrealAutomator: UnrealAutomator Plugin Started
LogUnrealAutomator: HTTP Server listening on port 3000

2. Widget检测功能的核心实现原理

Widget检测是UI自动化测试的基础功能，UnrealAutomator通过反射机制获取场景中的Widget树结构，并将其转换为JSON格式输出。这一过程主要涉及以下几个关键技术点：

2.1 Widget树遍历算法

UnrealAutomator采用深度优先搜索(DFS)算法遍历Widget层级结构：

void TraverseWidgetTree(UWidget* Root, TSharedPtr<FJsonObject>& OutJson) {
    if (!Root) return;
    
    // 获取当前Widget基本信息
    OutJson->SetStringField("Name", Root->GetName());
    OutJson->SetStringField("Type", Root->GetClass()->GetName());
    
    // 处理子Widget
    if (auto Panel = Cast<UPanelWidget>(Root)) {
        TArray<TSharedPtr<FJsonValue>> Children;
        for (int32 i = 0; i < Panel->GetChildrenCount(); ++i) {
            TSharedPtr<FJsonObject> ChildJson = MakeShareable(new FJsonObject());
            TraverseWidgetTree(Panel->GetChildAt(i), ChildJson);
            Children.Add(MakeShareable(new FJsonValueObject(ChildJson)));
        }
        OutJson->SetArrayField("Children", Children);
    }
}

2.2 数据结构设计

Widget信息以JSON格式组织，包含以下核心字段：

字段名类型描述
NameStringWidget名称
TypeStringWidget类型(如Button、TextBlock等)
PathString在树结构中的完整路径
VisibilityString可见性状态
ChildrenArray子Widget数组

2.3 性能优化策略

为提高检测效率，UnrealAutomator实现了以下优化：

  • 缓存机制：对静态Widget树结构进行缓存，减少重复计算
  • 增量更新：只检测发生变化的部分Widget
  • 异步处理：耗时操作放在后台线程执行，不阻塞主线程

3. 构建自动化测试用例

基于UnrealAutomator的Widget检测功能，我们可以构建完整的自动化测试流程。下面以一个登录界面的测试为例，展示如何编写测试代码。

3.1 测试环境准备

首先创建测试专用的地图和Widget蓝图：

  1. 新建关卡TestMap_Login
  2. 创建Widget蓝图WBP_Login，包含以下元素：
    • 用户名输入框(EditableTextBox)
    • 密码输入框(EditableTextBox)
    • 登录按钮(Button)
    • 错误提示文本(TextBlock)

3.2 测试代码实现

在插件的Private/Tests目录下创建UnrealAutomatorRunTests.cpp文件：

#include "UnrealAutomatorPrivatePCH.h"
#include "Misc/AutomationTest.h"
#include "UnrealAutomator/Service/UIService.h"

IMPLEMENT_SIMPLE_AUTOMATION_TEST(FLoginUITest, "UnrealAutomator.UI.Login", 
    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)

bool FLoginUITest::RunTest(const FString& Parameters) {
    // 1. 加载测试地图
    UGameplayStatics::OpenLevel(GWorld, TEXT("/Game/Tests/TestMap_Login"));
    
    // 2. 获取Widget树结构
    auto WidgetJson = FUIService::GetWidgetTreeJson();
    FString WidgetTreeStr = FCommonUtil::JsonStringify(WidgetJson);
    
    // 3. 验证关键元素存在
    TestTrue(TEXT("Login button exists"), 
        WidgetTreeStr.Contains("WBP_Login.Button_Login"));
    TestTrue(TEXT("Username input exists"),
        WidgetTreeStr.Contains("WBP_Login.EditableTextBox_Username"));
    
    // 4. 模拟用户输入
    FUIService::SetInputText("WBP_Login.EditableTextBox_Username", "testuser");
    FUIService::SetInputText("WBP_Login.EditableTextBox_Password", "123456");
    
    // 5. 模拟按钮点击
    FUIService::ClickWidget("WBP_Login.Button_Login");
    
    // 6. 验证登录结果
    FString ErrorText = FUIService::GetWidgetText("WBP_Login.TextBlock_Error");
    TestFalse(TEXT("No error after login"), ErrorText.IsEmpty());
    
    return true;
}

3.3 测试执行与结果分析

编译代码后，按照以下步骤执行测试：

  1. 打开编辑器中的"会话前端"(Window -> Developer Tools -> Session Frontend)
  2. 切换到"自动化"(Automation)标签页
  3. 找到"UnrealAutomator.UI.Login"测试项
  4. 点击"开始测试"(Start Tests)按钮

测试完成后，可以在结果面板中查看详细报告：

  • 通过：所有断言检查通过，Widget功能正常
  • 失败：某个检查点未通过，需查看具体错误信息
  • 警告：测试执行完成，但存在潜在问题

4. 高级功能与最佳实践

掌握了基础测试方法后，下面介绍一些提升测试效率的高级技巧。

4.1 参数化测试

通过外部JSON文件定义测试数据，实现一套代码测试多种场景：

// 读取测试参数
FString ParamStr;
FFileHelper::LoadFileToString(ParamStr, TEXT("TestData/LoginTestCases.json"));
auto Params = FCommonUtil::ParseJson(ParamStr);

for (auto& Case : Params->GetArrayField("Cases")) {
    FString Username = Case->AsObject()->GetStringField("Username");
    FString Password = Case->AsObject()->GetStringField("Password");
    bool ExpectedSuccess = Case->AsObject()->GetBoolField("Success");
    
    // 执行测试...
}

示例测试数据文件LoginTestCases.json：

{
    "Cases": [
        {
            "Username": "admin",
            "Password": "123456",
            "Success": true
        },
        {
            "Username": "test",
            "Password": "wrong",
            "Success": false
        }
    ]
}

4.2 测试覆盖率统计

结合UnrealAutomator的Widget检测和UE4的代码覆盖率工具，可以生成可视化报告：

  1. 在DefaultEngine.ini中启用覆盖率收集：
[Coverage]
bEnabled=True
TraceFile=GameCoverage.ucov
  1. 修改测试代码记录覆盖信息：
// 测试开始时
FCoverageTracker::StartRecording();

// 测试结束时
FCoverageTracker::StopRecording();
FCoverageTracker::SaveCoverageData();
  1. 使用UnrealFrontend生成HTML报告

4.3 持续集成集成

将自动化测试接入CI流程，确保每次提交都经过验证：

# 示例Jenkins Pipeline脚本
pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                bat 'UE4Editor-Cmd.exe Project.uproject -build'
            }
        }
        
        stage('Test') {
            steps {
                bat 'UE4Editor-Cmd.exe Project.uproject -run=UnrealAutomator.UI.Login -report'
            }
        }
    }
    
    post {
        always {
            junit '**/TestResults/*.xml'
        }
    }
}

5. 常见问题与解决方案

在实际使用中，你可能会遇到以下典型问题：

5.1 Widget无法检测到

现象：测试报告显示某些Widget不存在
排查步骤：

  1. 确认Widget已添加到视口且可见性正确
  2. 检查Widget命名是否符合预期
  3. 验证Widget树遍历深度是否足够

解决方案：

// 调整遍历深度
FUIService::SetMaxTraversalDepth(5);

5.2 测试执行速度慢

优化建议：

  • 减少不必要的Widget属性收集
  • 使用异步检测模式
  • 对静态界面启用缓存

性能对比示例：

测试场景原始耗时(ms)优化后(ms)
登录界面1200350
主菜单2500800
背包系统38001500

5.3 跨平台兼容性问题

针对不同平台的适配建议：

  1. 移动端：

    • 增加触摸事件模拟支持
    • 考虑屏幕分辨率差异
    • 处理虚拟键盘弹出场景

  2. PC端：

    • 支持鼠标悬停效果检测
    • 处理窗口大小变化情况

平台特定代码示例：

#if PLATFORM_ANDROID
    // 安卓特有处理
    FUIService::SimulateTouch(100, 200);
#else
    // PC/Mac处理
    FUIService::SimulateMouseClick(100, 200);
#endif

6. 扩展UnrealAutomator功能

UnrealAutomator设计之初就考虑了可扩展性，你可以基于现有框架添加自定义功能。

6.1 添加新的HTTP端点

  1. 创建新的Handler类继承FHttpRequestHandler：
class FMyCustomHandler : public FHttpRequestHandler {
public:
    void ProcessRequest(FHttpRequest& Request, FHttpResponse& Response) override {
        // 处理逻辑...
        Response.SetContent(TEXT("Custom response"));
    }
};
  1. 注册到HTTP服务器：
FHttpServer::Get().RegisterHandler(
    TEXT("/my/custom/endpoint"), 
    MakeShareable(new FMyCustomHandler()));

6.2 集成第三方测试框架

以集成Appium为例：

void FAppiumIntegrationModule::StartupModule() {
    // 初始化Appium连接
    AppiumClient = MakeShareable(new FAppiumClient());
    
    // 将UnrealAutomator数据转发给Appium
    FUIService::OnWidgetDumped.AddRaw(this, &FAppiumIntegrationModule::HandleWidgetDump);
}

void FAppiumIntegrationModule::HandleWidgetDump(const FString& WidgetJson) {
    AppiumClient->SendData(WidgetJson);
}

6.3 自定义Widget检测规则

通过重写UWidgetInspector类实现特殊检测逻辑：

class UMyWidgetInspector : public UWidgetInspector {
public:
    virtual void InspectWidget(UWidget* Widget, TSharedPtr<FJsonObject>& OutJson) override {
        // 基础检测
        Super::InspectWidget(Widget, OutJson);
        
        // 自定义扩展
        if (auto TextBlock = Cast<UTextBlock>(Widget)) {
            OutJson->SetStringField("FontSize", 
                FString::Printf(TEXT("%d"), TextBlock->Font.Size));
        }
    }
};

在实际项目中，我们使用UnrealAutomator成功将UI测试覆盖率从30%提升到85%，回归测试时间缩短了70%。特别是在游戏频繁更新的阶段，自动化测试帮我们捕捉到了多个关键问题，避免了线上事故。

Logo
乐奇 Rokid 开放社区

更多推荐

cover

AR巡检哪家好，和浪潮比哪家方案更成熟

avatar 乐奇 Rokid 开放社区
cover

AR巡检哪家好

avatar 乐奇 Rokid 开放社区
cover

瑞丰宝丽在AR巡检领域排名

avatar 乐奇 Rokid 开放社区