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 same UIA surface has two invocation paths: talking to the Microsoft-maintained WinAppDriver.exe service directly from a Selenium client, or going through the Appium ecosystem's actively-maintained Node.js proxy that sits in front of it and adds gestures, multi-window helpers, and PowerShell hooks. This skill covers both - the direct path in the sections below, the Appium path in "Invoking via Appium". Go direct when no Appium (or Node.js) install is wanted on the test host; go via Appium when the project already runs Appium for other platforms.

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.

Invoking via Appium

Per the appium-windows-driver repository (opens in new window), "Appium Windows Driver is a test automation tool for Windows devices and acts as a proxy to Microsoft's WinAppDriver server." The Node.js driver itself is actively maintained while the underlying service is described on the Appium ecosystem drivers page (opens in new window) as "has not been maintained since 2022" - which is why the wrapper ships a built-in installer to pin a known-good WinAppDriver version. Same UIA surface, same locator semantics; what Appium adds: windows: gestures (scroll / clickAndDrag / keys / launchApp), multi-window session switching, and appium:prerun / appium:postrun PowerShell hooks.

Install and launch (awd (opens in new window)):

npm install -g appium
appium driver install windows
appium driver run windows install-wad   # pins + installs WinAppDriver.exe
appium --port 4723

Session capabilities carry the appium: vendor prefix required by Appium 2.x for non-W3C-standard caps (awd (opens in new window)):

{
  "platformName": "windows",
  "appium:automationName": "windows",
  "appium:app": "C:\\Windows\\System32\\notepad.exe",
  "appium:appArguments": "MyTestFile.txt"
}

platformName and appium:automationName must both be windows (case-insensitive); appium:appTopLevelWindow attaches to an existing window by hex handle; appium:prerun / appium:postrun run short, non-interactive PowerShell around the session (awd (opens in new window)). Python client:

from appium import webdriver
from appium.options.windows import WindowsOptions
from selenium.webdriver.common.by import By

options = WindowsOptions()
options.platform_name = 'windows'
options.automation_name = 'windows'
options.app = r'C:\Windows\System32\notepad.exe'

driver = webdriver.Remote('http://127.0.0.1:4723', options=options)
editor = driver.find_element(By.NAME, 'Text editor')
editor.send_keys('Hello from Appium Windows')
driver.quit()

Appium-path traps: omitting the appium: prefix (session rejected); legacy automationName: WinAppDriver (use windows); hand-installing a random WinAppDriver MSI instead of install-wad (version mismatch with the proxy); hard-coding appTopLevelWindow (hex handle is per-launch); windows: scroll with positive deltaY to scroll down (negative scrolls down). The gestures API, multi-window flows, PowerShell hook recipes, and the Appium-path CI workflow are in references/gestures-hooks-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, prefer the Appium 2.x invocation path above; NovaWindows is referenced on appiumdrivers (opens in new window) as "a drop-in replacement for the partially unmaintained Windows driver" for new heavy use.

• 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).
• appium-windows-driver README - awd (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.
• Deep reference (Appium windows: gestures, multi-window sessions, PowerShell hooks, Appium-path CI): references/gestures-hooks-and-ci.md.
• Strategic frame: desktop-test-strategy-reference.