简介一份基于C# UI Automation的自动化测试示例工程面向需要为Windows桌面应用建立UI自动化回归测试的.NET开发者。工程通过15个按钮示例覆盖程序启停、文本编辑、按钮点击、列表展开及控件遍历等常见操作直观演示如何借助UI Automation库驱动和校验界面元素帮助初学者快速掌握桌面端自动化测试的编写思路与调试方法。压缩包共29个文件包含7个C#源码文件、2个可执行程序、配置文件、资源文件及Visual Studio解决方案等整体仅71KB结构紧凑适合直接打开学习或二次改造。已有2498人学习下载。资源内含完整的WindowsFormsApp1示例项目从Form界面设计到自动化调用代码一应俱全并带有生成的exe与调试日志便于对照运行结果理解每一步操作对于正在搭建持续集成或需要减少手工回归成本的团队也是一份轻量实用的参考模板。1. 为什么我还在用 C# 写 UI 自动化而不是等 AI 来点按钮先交代一下背景。这些年 UI 自动化测试的工具链变化很快从 Selenium 到 Playwright从 Appium 到各种 AI 测试平台名字换了一茬又一茬。但我手里的很多测试对象是那些跑在 Windows 上的老牌桌面客户端——工控上位机、扫码枪配置工具、内部 OA 客户端、医疗仪器操作软件。这些程序没有浏览器那样的 DOM也不提供测试后门你甚至拿不到它的源代码。在这种场景下C# 的 UI AutomationUIA依然是 Windows 桌面端自动化绕不开的一条路。这个示例工程解决的核心问题很简单让 C# 程序能够像人一样“看见”Windows 窗口里的按钮、输入框、列表项并且去点击、输入、读取内容最终验证软件行为是否符合预期。它适合三类人看一是刚接手 Windows 桌面端自动化测试不知道该从哪里下手的测试开发二是主要做上位机或客户端开发想给自己的软件补一套自动化回归手段的 C# 工程师三是在研究“AI 自动化测试平台搭建”但发现底层还得有人先把 UIA 这套机制讲清楚的技术选型人员。需要先说清楚的是UIA 不等于“录制回放”也不等于“图像识别”。它是一套微软提供的 UI 可访问性框架早在 .NET 3.0 时代就推出了到今天依然是 WinForms、WPF、Qt非自绘部分等主流 Windows 桌面技术天然支持的自动化接口。你不需要往被测软件里注入任何 DLL不需要改它的代码只要被测程序实现了 UIA Provider绝大多数标准控件默认实现你就能从外部拿到它的完整控件树像查看网页 DOM 一样去操作界面。我把一个可以直接跑的示例工程拆开、揉碎结合自己这几年在上位机自动化测试项目里的实践把选型思路、关键对象模型、完整示例代码和踩坑记录都放在这篇文章里希望能帮你少走几个月的弯路。2. 整体设计思路为什么选 UIA以及示例工程的分层骨架2.1 先比较一下主流的 Windows 桌面 UI 自动化方案在做技术选型的时候很多人第一个想到的是各种商业工具或者干脆用图像识别来兜底。我先用一个对照表来说明 UIA 在整个方案矩阵里的定位这样你就明白我为什么优先选它。方案实现思路优点明显短板C# UI Automation读取并操作系统暴露的 UI 控件树不侵入被测程序、控件属性丰富、稳定性高、支持多种桌面框架对自绘控件无能为力定位逻辑需要自己封装Win32 APISendMessage/PostMessage直接向句柄发送 Windows 消息简单直接、响应快收不到现代控件的语义信息很多 WPF 控件本质是自绘的句柄层级和逻辑控件不对应FlaUIUIA2/UIA3 封装对微软 UIA 的社区封装好用、支持 XPath、事件机制完善需要额外引入 NuGet 包本质还是 UIATestStack.White基于 UIA 的上层框架上手快、能少写不少样板代码项目更新节奏慢遇到现代控件树有时候要绕图像识别OpenCV/模板匹配截屏匹配像素能测任何软件极其脆弱分辨率/缩放一变就挂维护成本高AI 驱动的测试平台AI 模型理解界面看起来美好能做智能断言底层依然需要 UIA/OCR 提供控件信息现阶段不适合做精确回归从这个对比能看出UIA 是 Windows 桌面自动化的“底层真香方案”。商业工具和 AI 平台的上层能力再花哨最终还是要靠 UIA 来抓取控件信息。这也是我这个示例工程选择直接用原生System.Windows.Automation命名空间实现的核心理由——少包一层框架你就少一层黑盒。2.2 示例工程的目录结构与职责划分一个能长期维护的 UIA 自动化工程一定不能把所有查找控件、等待元素、断言的操作都堆在测试方法里。我给这个示例工程设计了四层结构跟写网站的分层思路其实是一样的AutomationBase基础封装层封装 UIA 的常用操作包括等待窗口出现、按 AutomationId 查找元素、按 Name 查找元素、控件是否存在等基础方法。这一层放的是工具类。PageObjects页面对象层把被测软件的一个窗口或一个功能模块抽象成一个类。类里面的属性是控件方法是操作流程。举个例子登录窗口对应一个LoginWindow类里面有用户名输入框、密码输入框、登录按钮等属性以及Login(user, password)方法。TestCases测试用例层用上面的页面对象去写具体测试步骤和断言。CommonHelper辅助工具层放日志、截图、配置文件读取。这个不是核心但对定位问题很重要。2.3 为什么示例工程要用 NUnit 而不是控制台程序可能你会问我就想写个小工具自动化点两下为什么非要引入测试框架我在实际项目里也这么想过后来发现纯控制台式的自动化脚本有致命问题一旦某个步骤失败整个脚本就中断了前面的成功操作也拿不到有效报告而测试框架能帮你把“操作步骤”和“断言验证”分开还能生成结构化报告对 CI/CD 集成也很友好。示例工程选用 NUnit 附带一个额外的好处NUnit 的断言失败信息能直接和 UIA 的控件状态关联起来。你可以在断言类里写一个“控件是否存在、是否可用、文本是否匹配”的扩展方法失败时自动把控件截图和当前 UI 树的 XML 快照保存到测试输出目录。这在排查“环境问题”还是“代码问题”时非常有帮助。3. 核心对象模型拆解AutoElement、Condition、Pattern 这三板斧3.1 理解自动化元素树就像理解网页 DOM如果你是做 Web 自动化出身的学 UIA 会非常快因为它的核心概念和 DOM 如出一辙。AutomationElement相当于 DOM 里的Element表示一个 UI 控件自动化元素树相当于整个 HTML 文档树。树根是AutomationElement.RootElement代表 Windows 桌面本身往下是各个应用程序的顶层窗口再往下是窗口内的所有控件。真正写代码时你不需要也不可能遍历整棵树。UIA 提供了FindFirst/FindAll方法接收两个参数搜索范围TreeScope和过滤条件Condition。这等价于在 DOM 里执行document.querySelectorAll。// 查找桌面上的名为计算器的窗口 var condition new PropertyCondition(AutomationElement.NameProperty, 计算器); AutomationElement desktop AutomationElement.RootElement; AutomationElement calcWindow desktop.FindFirst(TreeScope.Children, condition);3.2 Condition 的三种常用姿势Condition是 UIA 查询的灵魂。实际编码中我最常用的是这三种PropertyCondition按单个属性过滤比如控件名称NameProperty、AutomationIdAutomationIdProperty、控件类型ControlTypeProperty。这是最基础也最常用的。AndCondition多个条件同时满足等价于逻辑与。比如你要找一个 AutomationId 为txtUser且类型为 Edit 的控件就用new AndCondition(条件1, 条件2)。OrCondition多个条件任一满足等价于逻辑或常用于目标控件在不同版本里名称变化的情况。特别提醒Inspect 工具Windows SDK 自带显示的 AutomationId 是你定位控件的黄金标准。拿到被测软件后第一步就是打开 Inspect鼠标一点看目标控件的 Name、AutomationId、ControlType、IsEnabled、IsOffscreen 这几项属性。这是所有后续代码的基础。3.3 PatternUIA 操作控件的统一接口光是找到控件还不够你要能点击它、勾选它、往里面填文字。UIA 把常见交互抽象成了一个个 Pattern模式每个 Pattern 对应一组能力InvokePattern触发按钮、菜单项等控件的点击。它只有Invoke()一个方法没有参数相当于鼠标左键单击。ValuePattern读写编辑框、ComboBox 等的文本值。SetValue()用于赋值Current.Value用于读取。SelectionItemPattern选择列表项、Tab 页等。通过Select()方法选中某个项目。TogglePattern勾选/取消勾选 CheckBox。调用Toggle()会在选中、未选中之间切换。LegacyIAccessiblePattern这是个大杂烩兜底模式。遇到标准 Pattern 搞不定的老控件比如某些 MFC 自绘控件通过它可以拿到Select()、SetValue()等方法算是 UIA 的“最后手段”。我的经验是定位控件用AutomationId判断操作类型就看它支持哪些 Pattern。GetSupportedPatterns()能列出一个控件支持的所有 Pattern多方验证比瞎猜靠谱得多。4. 从零搭建示例工程一个能跑的完整实现4.1 新建工程和引用示例工程基于 .NET 8开发工具用 Visual Studio 2022。打开 VS新建一个类库或控制台项目都可以然后在项目文件里加上对System.Windows.Automation和 NUnit 的引用dotnet new nuget dotnet add package NUnit dotnet add package NUnit3TestAdapter dotnet add package Microsoft.NET.Test.Sdk编译目标我建议选择 x64。现在的 Windows 系统虽然 64 位是主流但很多被测程序是 AnyCPU 编译的在 64 位进程里跑 UIA 对它们来说最稳妥。4.2 等待与超时机制最容易忽视的环节自动化测试最烦人的就是“偶发失败”程序还没完全启动、动画还在播放、异步加载还没结束代码就去点按钮自然就点不上。我的示例工程里专门封装了一个重试机制替代脆弱的Thread.Sleep。public static class AutomationWait { public static AutomationElement WaitForElement( AutomationElement parent, Condition condition, int timeoutMs 10000) { var sw System.Diagnostics.Stopwatch.StartNew(); while (sw.ElapsedMilliseconds timeoutMs) { var element parent.FindFirst(TreeScope.Descendants, condition); if (element ! null element.Current.IsEnabled) { return element; } System.Threading.Thread.Sleep(200); // 200ms 轮询一次别太频繁 } throw new TimeoutException($等待控件超时{condition}); } }这个方法的思路是“轮询条件直到满足或超时”。它比固定等待好的地方在于程序慢的时候多等一会儿快的时候立刻执行测试整体不会拖沓。轮询间隔 200ms 是一个平衡点太短会占用 CPU太长又不够灵敏。4.3 演示用的目标程序一个简易计算器为了让示例可复现我不拿你公司的业务软件当测试对象。这里用一个最普通的 WinForms 计算器程序假设它的窗口标题是“WinFormsCalc”界面上有一个文本框txtDisplay四个按钮分别对应加、减、乘、除。被测工程只需要新建一个 WinForms 项目拖一个 TextBox 和几个 Button 就行。下面是核心的测试类代码覆盖了“启动被测程序 → 找到窗口 → 点击按钮 → 断言结果”这条最典型的链路using NUnit.Framework; using System.Diagnostics; using System.Windows.Automation; [TestFixture] public class CalculatorTests { private Process _calcProcess; private AutomationElement _mainWindow; [SetUp] public void LaunchCalc() { _calcProcess Process.Start(WinFormsCalc.exe); _calcProcess.WaitForInputIdle(5000); var windowCondition new PropertyCondition( AutomationElement.NameProperty, WinFormsCalc); _mainWindow AutomationElement.RootElement.FindFirst( TreeScope.Children, windowCondition); Assert.That(_mainWindow, Is.Not.Null, 未能找到主窗口); } [Test] public void Add_1_And_2_Should_Display_3() { // 点击数字按钮 1 ClickButton(btn1); ClickButton(btnAdd); ClickButton(btn2); ClickButton(btnEquals); // 读取结果并断言 var displayTextBox UiaHelper.FindElementById(_mainWindow, txtDisplay); var valuePattern displayTextBox.GetCurrentPattern(ValuePattern.Pattern) as ValuePattern; Assert.That(valuePattern.Current.Value, Is.EqualTo(3)); } [TearDown] public void CloseCalc() { _mainWindow?.GetCurrentPattern(WindowPattern.Pattern) ?.Close(); _calcProcess?.Dispose(); } private void ClickButton(string automationId) { var button UiaHelper.FindElementById(_mainWindow, automationId); var invokePattern button.GetCurrentPattern(InvokePattern.Pattern) as InvokePattern; invokePattern.Invoke(); } }4.4 我发现的一个关键坑进程启动后不能马上找窗口Process.Start()返回之后被测程序的窗口很可能还没创建完成这时候立刻去FindFirst经常会返回 null。示例代码里加了WaitForInputIdle(5000)这个方法的含义是“等待进程进入空闲状态”对 WinForms 和 WPF 都有效但它不是万能的。如果你的被测程序启动后还要做网络登录、加载大型配置文件界面可能长时间“卡住”WaitForInputIdle会直接超时。这时候就需要配合 4.2 节的轮询等待方法而不是把WaitForInputIdle当成万能钥匙。正确的启动流程是WaitForInputIdle等待第一帧渲染完成再用WaitForElement去等关键的登录按钮可用。4.5 页面对象到底怎么设计以登录窗口为例拿完整项目来举例页面对象的代码大概长这样public class LoginWindow { private readonly AutomationElement _window; public LoginWindow(AutomationElement window) { _window window; } private AutomationElement UserNameBox UiaHelper.FindElementById(_window, txtUserName); private AutomationElement PasswordBox UiaHelper.FindElementById(_window, txtPassword); private AutomationElement LoginButton UiaHelper.FindElementById(_window, btnLogin); public void Login(string user, string password) { UserNameBox.GetCurrentPattern(ValuePattern.Pattern) .SetValue(user); PasswordBox.GetCurrentPattern(ValuePattern.Pattern) .SetValue(password); LoginButton.GetCurrentPattern(InvokePattern.Pattern) .Invoke(); } }这样设计的最大好处是当被测软件的界面调整时你只需要改页面对象里的定位条件测试用例层的代码可以完全不动。这也是从 Web 自动化里继承过来的 Page Object 模式在桌面端完全适用。5. 高频问题与排查手段实测过程中踩过的坑5.1 控件明明存在FindFirst 却返回 null这大概是 UIA 自动化里出现频率最高的问题。原因通常有三个第一你找的窗口在桌面树的TreeScope.Children下但如果你传的是TreeScope.Descendants也能找到只是慢真正的问题往往是搜索范围不对。第二控件确实是动态创建的你查询的时候它还没加载出来用轮询等待解决。第三UIA 对权限隔离很敏感。如果你的测试程序以管理员权限运行而被测程序是普通权限或反过来UIA 可能看不到对方的窗口树。解决办法是让测试进程和被测进程的权限保持一致统一以管理员身份运行。5.2 多显示器环境下坐标错乱图像识别方案的老毛病是分辨率一变就抓瞎UIA 虽然不依赖截图但有些操作比如发送鼠标点击还是要用坐标。多显示器、DPI 缩放比例为 125%、150% 的时候UIA 返回的BoundingRectangle是物理像素而SetCursorPos这类 API 需要的坐标可能是逻辑像素两者不一致就会点偏。我的建议是优先使用 Pattern 方法Invoke()、SetValue()这些方法是语义级的系统内部会帮你处理坐标换算不需要手动操作鼠标。如果确实要模拟鼠标比如测拖拽功能那就用System.Windows.Forms.Cursor.Position结合虚拟屏幕坐标并且在测试环境里固定 DPI 缩放。5.3 等待动画和异步加载结束后再操作现代的桌面客户端很多用 WPF 或 Electron 重写了界面动画效果最常见的是按钮淡入、列表滚动、Tab 切换时的渐入渐出。这些动画期间控件的IsEnabled可能是 true但点击还是没反应。因为界面线程被动画逻辑占用了。处理办法有两个。第一用WaitForInputIdle配合一个短固定延时比如 500ms给动画留出完成时间。第二更严谨的做法是使用 UIA 的事件机制比如AutomationEventHandler监听AutomationElement.IsEnabledProperty的变化等控件从禁用变为启用时再操作。后者更“专业”但代码复杂度会上去示例工程就先按下不表。5.4 对自绘控件和 Electron 程序的补充方案UIA 的尴尬在于如果被测软件用了自绘控件比如很多游戏引擎、DirectX 渲染界面或完全不走标准 Windows 控件模型UIA 里能看到的就是一张“白纸”控件树是空的。这也不能全怪 UIA它本质上是让开发者提供可访问性信息的框架开发者没提供外部自然拿不到。这种时候我的兜底方案是混合使用图像识别做点击定位用 OCR比如 Tesseract读取结果再用 UIA 处理周边标准控件。虽然不纯粹但在“外挂式测试”的约束下已经是最稳定的方案了。像 Electron 程序其实内部是个浏览器页面如果你能用 Chrome DevTools 协议去控制它那会比对窗口截图靠谱得多。提示写 UIA 测试时被测软件的稳定性是第一位的。如果你的目标程序一打开就弹各种广告窗、自动更新提示自动化脚本会被这些杂音干扰。在测试环境里提前把这些弹窗机制关掉能省下大量调试时间。6. 一套稳妥的调试方法排查 UIA 问题时我发现最有用的不是写日志从头打印而是先“人工扮演 UIA”走一遍。具体操作是打开 Inspect先把鼠标放到目标控件上看一下四个关键属性——Name、AutomationId、ControlType、IsEnabled。然后手动点击或输入一次看软件的响应是否符合预期。这一步能帮你确认被测软件本身没有 bug问题只出在自动化脚本的定位或操作上。如果脚本里还是找不到元素我一般会在测试代码中把当前窗口的整个控件树序列化成一个 XML 文件然后用文本编辑器搜索关键字。这个功能可以通过TreeWalker.ControlViewWalker遍历实现代码量并不大public static string DumpTree(AutomationElement root) { var sb new StringBuilder(); var walker TreeWalker.ControlViewWalker; var element walker.GetFirstChild(root); while (element ! null) { sb.AppendLine(${element.Current.ControlType.ProgrammaticName} | $Name{element.Current.Name} | $AutomationId{element.Current.AutomationId}); element walker.GetNextSibling(element); } return sb.ToString(); }这个方法在排查“为什么这个按钮找不到”“这个控件到底叫什么名字”的时候比单纯靠肉眼盯屏幕高效得多。把这些信息输出到测试日志还能在 CI 环境里复现问题不用每次都跑回本地去点。7. 从示例工程到实际落地我还想再多说几句最后再聊点个人经验。搭好这个示例工程只是第一步真正把它用起来还涉及几个容易忽略的工程化问题。一是测试数据和环境隔离。UIA 测试跑起来会真实操作被测软件特别容易污染数据。比如测试一个登录流程你不能老拿一个真实用户的账号去登录。我的做法是在测试环境准备独立的测试账号和测试数据库跑完后自动还原。否则测试跑几次数据就乱了后面断言谁也过不了。二是失败现场的证据链保存。UIA 脚本失败的典型特征是“偶发性强”复现困难。我写的每个测试用例在TearDown里如果检测到测试失败就自动截屏整个桌面并调用 6.2 节的DumpTree方法保存当时的控件树快照。这样出了问题看截图和 XML通常五分钟内就能判断是环境问题还是脚本问题。三是和 CI/CD 的集成。UIA 测试天然需要一个有真实桌面的 Windows 环境普通的容器里跑不了。我自己用得多的方式是配置一台 Windows Server 作为自动化测试机用 Jenkins 或 GitLab Runner 调度测试任务。被测程序的构建产物发布到这台机器后自动拉起测试测试结果和截图再回传到 CI 服务器。整个过程对开发团队是透明的大家只在合并代码时看测试报告就行。如果你现在准备尝试 C# UIA 自动化测试我建议你从今天这个示例工程里的“查找控件 → 操作控件 → 断言结果”这条链路开始先把你电脑上的某个系统自带软件比如记事本作为目标练手。跑通这个最小闭环之后再用同样的套路去面对真正的被测软件。这比一上来就追求完整框架、多元件同步要稳得多。本文还有配套的精品资源点击获取