winappdriver

Overview

Per the WinAppDriver repository (opens in new window):

"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 (opens in new window), 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 (opens in new window)).
• 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 (opens in new window)).
• 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 (opens in new window):

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

Download the latest WinAppDriver installer from the releases page (opens in new window) (latest stable per wad (opens in new window): 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 (opens in new window), 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 (opens in new window):

Per wadauth (opens in new window), 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 (opens in new window):

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 (opens in new window) which states the upstream "has not been maintained since 2022"). The latest official release per wad (opens in new window) 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 (opens in new window).
• WinAppDriver authoring guide - wadauth (opens in new window).
• Appium ecosystem drivers page (maintenance status note) - appiumdrivers (opens in new window).
• 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.