WinAppDriver Locators: Perils, Playbook, and AI Help

While the world has generally moved to mobile devices, desktop computers and applications still play a key role inside offices doing business. This is true for SMEs and enterprise alike. That's why the need for efficient test automation of all sorts of desktop applications, whether they work on Mac or Windows, has not gone away, it has just gone quiet. Nobody writes hype posts about desktop automation anymore, but somewhere behind almost every insurance company, bank, hospital, and manufacturing floor, a WPF, WinForms, or Win32 app is still running the actual business, and someone still has to test it.

For Windows apps specifically, WinAppDriver has been the default place teams start since Coded UI was retired. Worth saying up front, WinAppDriver itself has not seen much active development in a few years, releases have slowed and the open issue list is long, but it stays the practical starting point simply because there are not many real alternatives for driving native Windows UI. It is free, it is Microsoft's own tool, and it speaks the same WebDriver protocol Selenium and Appium already use, so C#, Java, and Python testers all feel at home with it fairly fast. What nobody tells you on day one is that the actual skill in WinAppDriver automation is not the driver setup, it is locators. Get those right and a suite runs for years. Get them wrong and you spend more time fixing "element not found" than writing new tests.

This post is about that exact skill: finding, choosing, and maintaining locators for WinAppDriver automation, plus a look at how AI and the Model Context Protocol (MCP) are starting to change how that discovery work gets done.

The Five Locator Strategies WinAppDriver Gives You

WinAppDriver, being a WebDriver-protocol server sitting on top of Windows UI Automation (UIA), exposes five ways to find an element:

• Accessibility ID, matching the control's AutomationId. This is the one you want most of the time.
• Name, matching the control's visible Name property.
• Class Name, matching the control's ClassName (for example TextBlock or Button).
• ID, matching RuntimeId, a value Windows assigns to a control at runtime.
• XPath, which can match on any attribute at all.

That list looks flat on paper, but the strategies are not equally reliable, and the gap between them is where most WinAppDriver flakiness comes from.

Accessibility ID is the strategy to build your suite on. It is developer-set, stable across app restarts, and independent of language or window layout. If a screen has good AutomationIds, use them, full stop.

Name breaks the moment your app is localized, or even the moment a product manager tweaks copy from "Save" to "Save Changes." Fine as a fallback, risky as a primary strategy for anything beyond a quick script.

RuntimeId is a trap many people fall into once, and only once. It looks like a stable identifier because it is a specific-looking string, but it is assigned fresh by Windows each time the control is created, so it can, and often does, change between app restarts. Do not build locators on it.

XPath is the one to reach for last, and to use sparingly, for two reasons. First, an XPath query in WinAppDriver has to walk the full UIA tree with no indexing, which real-world reports on the WinAppDriver GitHub issue tracker describe as dramatically slower than a direct AccessibilityId or Name lookup, sometimes the difference between a near-instant find and a multi-second one. Second, an XPath tied to sibling position or index is exactly the kind of structural locator that breaks the moment a designer adds a new control to a panel. If you must use XPath, anchor it to a stable ancestor with a known AutomationId, and keep the path as short as you can. (There is a real exception to "use it sparingly," covered just below, if your project runs on Appium 2.0 or newer.)

A Real Gotcha: Appium 2.0+ Changes the Rules

Everything above assumes the classic setup: WinAppDriver.exe running as its own server, with your test project talking to it directly through a Selenium-style WebDriver client. A lot of what is out there still teaches exactly that.

If your project instead runs on Appium 2.0 or newer with the appium-windows-driver plugin, so an Appium server sits in front of WinAppDriver rather than your tests talking to it directly, watch out for a real, documented quirk: By.Id and By.Name locators can get translated into CSS selectors under the hood and simply fail to find anything. In that specific setup, XPath stops being a last resort and becomes the strategy that actually works.

I put together a full, working example of this exact Appium 5 plus WinAppDriver setup in C#, including the AppiumServiceBuilder startup pattern and a small EasyXPath helper class for building the XPath locators this setup needs, on GitHub: Appium5-WinAppDriver. Worth cloning and running side by side with whatever setup you are on, so you know which locator rules actually apply to your project before you build fifty tests on the wrong assumption.

Why WinAppDriver Locators Get Fragile in the First Place

A few realities make Windows desktop locators harder than the web locators most testers cut their teeth on, and they show up constantly in WinAppDriver suites specifically.

A lot of apps simply never set AutomationIds. Setting an AutomationId is a deliberate developer choice, and in older or legacy Win32, MFC, and even plenty of WPF codebases, nobody ever did it. You end up locating by Name, which is fine until localization or a copy change breaks half the suite in one release.

Custom-drawn controls can be invisible to UIA entirely. Canvas-based UI, some CAD and design tools, and heavily custom-rendered WPF controls can expose almost nothing to the accessibility tree WinAppDriver relies on. When that happens, none of the five strategies above help, and coordinate-based clicks become the only fallback, which is the most fragile option there is.

Coordinates and window layout drift. A locator anchored to screen position breaks the moment DPI scaling, resolution, or window size changes. This is common enough on shared CI machines that it deserves its own line: if your test farm runs at a different resolution than your dev machine, coordinate-based clicks are a ticking clock, not a strategy.

Timing is part of the locator problem, not a separate one. A control can exist in the UIA tree and still not be safe to interact with, disabled, off-screen, or sitting behind a modal dialog that has not finished rendering. WinAppDriver will happily hand you a reference to an element you cannot actually click yet.

A WinAppDriver Locator Playbook

Inspect before you write a single locator. WinAppDriver ships a bundled UI Recorder specifically for this, point it at your app and it shows you the AutomationId, Name, and ClassName for anything you click. The Windows SDK's Inspect.exe does the same job with a bit more detail on the full ancestor chain. Five minutes here saves an hour of trial and error later.

Centralize your locators in Page Objects. Whatever language you're driving WinAppDriver from, keep every screen's locators in one class or module, not copy-pasted string literals scattered across test methods. When an AutomationId changes, you want to fix it in one place, not grep your whole repo.

Search relative to a container, not the whole window. Finding a button by searching the entire application window is slower and more ambiguous than first finding the containing dialog or panel by its AutomationId, then searching within that. It is also safer if two screens in the same app happen to reuse a button labeled "OK."

Push for AutomationIds from the dev side. If a screen has none, that is not a testing problem to quietly route around forever, it is a product defect, the same category as a missing API endpoint. Teams that add AutomationIds in XAML or code from day one save their QA function months of pain over an app's life.

Treat your RuntimeId and coordinate-based locators as expiring debt. If you have to fall back to either while a screen lacks proper accessibility support, flag it, track it, and replace it once the real AutomationId lands. Do not let it quietly become permanent.

FlaUI as a WinAppDriver Sidekick

You do not need to choose between WinAppDriver and FlaUI, the open source .NET library built on Microsoft's UIA APIs. Plenty of teams run WinAppDriver as their actual test driver and lean on FlaUI, or a small standalone FlaUI script, purely as an inspection tool during locator discovery. Because FlaUI runs in-process rather than through a separate driver, it is quick to spin up a throwaway console app that walks a window's tree, prints every control's AutomationId, ClassName, and Name, and lets you confirm exactly what to plug into your WinAppDriver FindElementByAccessibilityId call, without touching Inspect.exe at all.

If you want to go deep on the WinAppDriver side specifically, from setup through real, running C# tests, that is exactly what my course, Windows Desktop Applications Test Automation in WinAppDriver, covers end to end. I also wrote a full breakdown of how WinAppDriver compares to the now-retired Coded UI if you want the background on why WinAppDriver became the default choice in the first place.

Waiting for Controls to Actually Show Up

A locator that finds the wrong moment in time is just as broken as one that finds the wrong element. Since WinAppDriver speaks the WebDriver protocol, the same explicit-wait pattern Selenium and Appium testers already know applies directly:

var wait = new WebDriverWait(driver, TimeSpan.FromSeconds(10));
var saveButton = wait.Until(d => d.FindElementByAccessibilityId("btnSave"));

That poll-until-true-or-timeout pattern, not a fixed sleep, is what keeps a suite fast on a quick CI machine and still reliable on a slow one. A few habits matter more than which exact wait class you reach for:

• Wait on a condition, not a clock. "Wait until this element exists and is enabled" survives a loaded CI box. "Wait three seconds" does not.
• For test steps that involve more than one flaky element, or that depend on a slow backend the app talks to, wrap the whole step in a retry policy with backoff rather than one fixed wait. Polly is the standard .NET library for this and composes cleanly around any WinAppDriver call.
• If you are also using FlaUI for inspection or verification steps alongside WinAppDriver, its own Retry helper (Retry.WhileNull, Retry.WhileFalse, Retry.WhileException, each with a timeout and polling interval) is worth knowing, since it is purpose-built for exactly this kind of polling.
• Wait for interactability, not just existence. WinAppDriver can hand you a reference to a control that is disabled or off-screen. Check the element's enabled state before you act on it, not just that the find call did not throw.

AI and MCP: Finding WinAppDriver Locators Faster

The most useful recent shift here is not a new locator syntax, it is tooling that lets an AI agent read the accessibility tree directly and reason about it, instead of guessing from a screenshot the way early "AI testing" tools did, and then hand you back exactly the AutomationId or path you plug into a WinAppDriver By call.

FlaUI-MCP, an open source MCP server built on FlaUI by Scott Hanselman, is a clean example. It exposes tools like windows_snapshot, which returns the live accessibility tree as structured element references, so an AI coding assistant can walk the real UIA tree, the same tree WinAppDriver itself queries under the hood, and hand back accurate AutomationIds, ClassNames, and ancestor paths for the controls you care about. Point it at your app during locator discovery, and it can shortcut a lot of manual Inspect.exe spelunking before you write the actual WinAppDriver test. Similar projects like windows-mcp-server extend this further with synthetic input and process control on top of the same accessibility-tree-first approach.

For scenarios no MCP server covers well yet, custom-written tree walker code is still a valid, sometimes necessary, fallback. Windows exposes System.Windows.Automation.TreeWalker directly in .NET, letting you write a small utility that recursively crawls a window's UIA tree and dumps every control's properties to JSON, then hand that JSON to an LLM with a prompt like "which of these elements is most likely the login button," and get back a suggested AutomationId or path to verify. It is a lighter-weight, roll-your-own version of what FlaUI-MCP does out of the box.

Two cautions matter more as this tooling gets more impressive. First, an AI suggesting a locator is not the same as an AI verifying one, always confirm a suggested AutomationId against a real inspector tool or an actual WinAppDriver test run before it lands in your suite; a language model can produce a plausible-looking but entirely wrong selector with total confidence. Second, an AI-suggested locator still belongs in your centralized Page Object, not pasted inline into a test method, or you have just automated your way into the same brittle mess faster.

Things You Must Never Do With WinAppDriver Automation

A short, hard-earned list:

• Never rely on Thread.Sleep as your primary wait strategy. It is either too short and flaky, or too long and slow, never both correct and fast. Use WebDriverWait every time.
• Never build a locator on RuntimeId. It looks stable and usually is not, it can change on every app restart.
• Never automate purely by screen coordinates when a real locator is available. Coordinates break on the first DPI or resolution change, and they break silently, the click just lands on the wrong thing.
• Never scatter the same locator string across dozens of test files. Centralize in Page Objects so a UI change costs one edit, not a search-and-replace across the whole suite.
• Never trust visible Name text as your primary locator in an app that ships in more than one language. What is stable in English can vanish entirely in a localized build.
• Never assume your suite can run against a locked or logged-off machine. WinAppDriver needs a real, interactive, unlocked session to drive UI at all. A CI runner that locks the screen on idle will fail your whole suite for reasons that have nothing to do with your app.
• Never leave WinAppDriver.exe or the app under test running after a failed session. A crashed test that skips driver.Quit() leaves orphaned processes behind that steal focus and intercept clicks meant for the next run. Clean up in a finally block, every time, even on failure.
• Never wrap a flaky locator in more retries without asking why it is flaky. Sometimes it is hiding a real race condition or a bug in the app itself. Blind retries just turn a real defect into an intermittent one nobody ever files.
• Never skip explicit handling for modal dialogs. "Element not found" is, more often than not, a focus problem in disguise, a dialog stole input focus and your script kept looking at the window behind it.
• Never treat a missing AutomationId as purely your problem to work around. It is a testability gap in the product. Raise it, do not just quietly build a fragile workaround and move on.

Wrapping Up

WinAppDriver gives you five ways to find an element, but only one of them, AccessibilityId, deserves to be your default. Everything else in a stable suite follows from that one fact: centralize locators so a UI change costs one edit, wait on conditions instead of clocks, and treat a missing AutomationId as a product defect rather than a personal problem to route around before a release.

What has genuinely changed recently is how fast the discovery part of that work goes. Tools like FlaUI-MCP put a real accessibility tree in front of an AI agent instead of a screenshot, which means the tedious part, figuring out what a control is actually called under the hood, is finally starting to get faster without getting less accurate, and the AutomationId it hands you drops straight into a WinAppDriver test.

If you want to see real, working code first, my Appium5-WinAppDriver repo on GitHub is free and shows the full Appium 5 plus WinAppDriver setup in C#, XPath helper class included.

If you want the full setup explained end to end, from installing WinAppDriver through writing real, running C# tests against a live desktop app, that is exactly what my course walks through.

Windows Desktop Applications Test Automation in WinAppDriver (code CBP2026AU) →