winappdriver

Overview

Per the WinAppDriver repository:

"Windows Application Driver (WinAppDriver) is a service to support Selenium-like UI Test Automation on Windows Applications."

WinAppDriver exposes Microsoft UI Automation (UIA) - the Windows accessibility tree described in desktop-test-strategy-reference - behind a W3C-WebDriver-compatible HTTP endpoint. Per wad, it supports four application classes on Windows 10: "Universal Windows Platform (UWP)", "Windows Forms (WinForms)", "Windows Presentation Foundation (WPF)", and "Classic Windows (Win32) apps".

The driver is a Microsoft-maintained service, distinct from the Appium ecosystem's wrapper around it - see appium-windows-driver for the Appium proxy that sits in front of WinAppDriver.exe and adds gestures, multi-window helpers, and PowerShell hooks. Pick this skill when you want to talk to WinAppDriver.exe directly from a Selenium client; pick appium-windows-driver when you want the Appium feature surface.

When to use

• Native Windows desktop app under test - UWP, WPF, WinForms, or Win32 (wad).
• Selenium-style client already in the project (C# WindowsDriver<T>, Java WindowsDriver, Python webdriver-windows).
• Tests must drive system-installed apps (Notepad, Calculator, Settings) - app capability accepts an executable path or UWP application family name (wadauth).
• Direct-to-WinAppDriver.exe is required (no Appium installation permitted on the test host).

For Qt-on-Windows out-of-process tests, this is the recommended driver per desktop-test-strategy-reference; the Qt application must publish a usable QAccessible tree.

How to use

1. Install WinAppDriver and enable Developer Mode on a Windows 10/11 machine (Install + enable).
2. Launch WinAppDriver.exe on the default 127.0.0.1:4723 endpoint (Launch the service).
3. Declare app / platformName / appArguments / appTopLevelWindow capabilities for the app under test (Declare session capabilities).
4. Author a Selenium-style test that resolves an element by AccessibilityId (UIA AutomationId) and drives it end to end (Worked example). The full locator-strategy table, Inspect.exe discovery, and attach-to-running-window path live in references/locators-and-ci.md.
5. Run on a Windows CI runner and parse TRX / JUnit results (feeds junit-xml-analysis) - full workflow in references/locators-and-ci.md.

Install + enable

Per wad:

1. Windows 10 machine with the application under test installed.
2. Enable Developer Mode - Settings → Update & Security → For developers → Developer mode (wad).
3. Administrator privileges are required to run on a custom IP / port (wad); default 127.0.0.1:4723 runs as a normal user.

Download the latest WinAppDriver installer from the releases page (latest stable per wad: v1.2.1, published 2020-11-05) and run it on the test machine. The installer drops WinAppDriver.exe under C:\Program Files (x86)\Windows Application Driver\.

Launch the service

Per wad, launch on the default endpoint:

:: Default - 127.0.0.1:4723
"C:\Program Files (x86)\Windows Application Driver\WinAppDriver.exe"

The service prints Press ENTER to exit. and listens for incoming W3C-WebDriver session requests. Custom IP / port / URL-prefix bindings (which require an admin shell) are in references/locators-and-ci.md.

Declare session capabilities

Per the WinAppDriver authoring guide:

Per wadauth, the UWP Application Id appears in the generated AppX\vs.appxrecipe file under the RegisteredUserModeAppID node (example shape: c24c8163-548e-4b84-a466-530178fc0580_scyf5npe3hv32!App).

Worked example

Drive one element end to end - launch Notepad, locate its editor by AccessibilityId, type into it, and close the session (C# client). The canonical example from wadauth:

using System;
using OpenQA.Selenium.Appium.Windows;
using OpenQA.Selenium.Remote;

var capabilities = new AppiumOptions();
capabilities.AddAdditionalCapability("app", @"C:\Windows\System32\notepad.exe");
capabilities.AddAdditionalCapability("appArguments", @"MyTestFile.txt");
capabilities.AddAdditionalCapability("appWorkingDir", @"C:\MyTestFolder\");
capabilities.AddAdditionalCapability("platformName", "Windows");

var session = new WindowsDriver<WindowsElement>(
    new Uri("http://127.0.0.1:4723"),
    capabilities);

// Locate by AccessibilityId (the AutomationId attribute)
var editor = session.FindElementByAccessibilityId("15");
editor.SendKeys("Hello from WinAppDriver");

session.Quit();

The AccessibilityId locator maps to the UIA AutomationId property - the stable locator per the desktop-test-strategy-reference locator table. The full method-to-attribute mapping and the other locator strategies are in references/locators-and-ci.md.

Anti-patterns

Limitations

• WinAppDriver is community-described as unmaintained since ~2022 (per the Appium ecosystem driver page which states the upstream "has not been maintained since 2022"). The latest official release per wad is v1.2.1 (2020-11-05). For new projects on actively-maintained tooling, see appium-windows-driver.

• Windows-only. The service runs only on Windows 10/11. No cross-OS test sharing without re-authoring against XCTest / AT-SPI.
• No first-party Linux / macOS analogue. Per the desktop-test-strategy-reference matrix, each OS has its own driver.
• No headless mode. UIA requires an interactive desktop session; CI on windows-latest works because GitHub-hosted runners are interactive, but Windows containers under Session 0 do not.
• GPU / DirectComposition surfaces (some WPF + WinUI 3 surfaces using DirectX-rendered controls) may not expose themselves to UIA - visible as opaque rectangles in Inspect.exe.
• App must publish UIA. Custom-painted Win32 windows that don't implement IRawElementProviderSimple are uncovered by WinAppDriver. Add UIA support or fall back to image matching for those specific surfaces.

References

• WinAppDriver repository (README) - wad.
• WinAppDriver authoring guide - wadauth.
• Appium ecosystem drivers page (maintenance status note) - appiumdrivers.
• Deep reference (locator-strategy table, Inspect.exe discovery, custom service bindings, attach-to-running-window, CI wiring): references/locators-and-ci.md.
• Sibling skill: appium-windows-driver - the Appium proxy in front of WinAppDriver.
• Strategic frame: desktop-test-strategy-reference.