git:20260724.d4db756 to git:20260725.09af35b

---

name: winappdriver

description: "Authors and runs Windows UI tests against WinAppDriver - Microsoft's W3C-WebDriver service for UWP, WPF, WinForms, and Win32 applications. Covers installing + launching `WinAppDriver.exe` on the default `127.0.0.1:4723` endpoint, declaring `app` / `platformName` / `appArguments` / `appTopLevelWindow` capabilities, finding elements by `AccessibilityId` / `Name` / `ClassName`, and CI integration on Windows runners. Use when driving a native Windows desktop app from a Selenium-style client (C#, Java, Python, Ruby, JavaScript)."

metadata:

keywords: "windows, winappdriver, uia, webdriver, wpf, uwp"

---

# winappdriver

## Overview

Per the [WinAppDriver repository][wad]:

[wad]: https://github.com/microsoft/WinAppDriver

> "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][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][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][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.

Per [wad][wad]:

1. **Windows 10 machine** with the application under test installed.

2. **Enable Developer Mode** - Settings → Update & Security → For

developers → Developer mode ([wad][wad]).

3. **Administrator privileges** are required to run on a custom

IP / port ([wad][wad]); default `127.0.0.1:4723` runs as a normal

user.

Download the latest WinAppDriver installer from the

[releases page][wad] (latest stable per [wad][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\`.

```cmd

:: 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

Per the [WinAppDriver authoring guide][wadauth]:

[wadauth]: https://github.com/microsoft/WinAppDriver/blob/master/Docs/AuthoringTestScripts.md

| Capability | Purpose |

|---|---|

| `app` | Application identifier (UWP family name) or full executable path ([wadauth][wadauth]) |

| `appArguments` | Launch arguments string ([wadauth][wadauth]) |

| `appWorkingDir` | Working directory for classic Win32 apps ([wadauth][wadauth]) |

| `appTopLevelWindow` | Hexadecimal handle of an existing window to attach to ([wadauth][wadauth]) |

| `platformName` | Target platform - set to `Windows` |

| `platformVersion` | Platform version string |

Per [wadauth][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`).

```csharp

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 stable locator per the

`desktop-test-strategy-reference`

## Anti-patterns

| Anti-pattern | Why it fails | Fix |

|---|---|---|

| Locating by `FindElementByName` for localised apps | Element name changes per language | Use `AccessibilityId` (UIA `AutomationId`) - stable across locales ([wadauth][wadauth]) |

| Hard-coded screen coordinates via `MouseAction` | DPI / window-state / multi-monitor break | Resolve element via accessibility tree; the driver computes hit-test centre |

| Custom IP / port without admin privileges | Service refuses to bind to non-default address | Run admin shell or stay on default `127.0.0.1:4723` ([wad][wad]) |

| One mega-session that drives multiple apps | UIA tree gets stale between app switches | One session per app; close + recreate on app change |

| Forgetting `session.Quit()` | Orphaned WinAppDriver child processes accumulate | `try/finally` around session lifecycle |

| Driving Edge / Chrome via WinAppDriver | Browser apps need a real WebDriver (Selenium / Playwright) | Use a browser driver, not WinAppDriver |

| Pixel-image matching for primary assertions | Brittle to font / theme / DPI changes | Accessibility tree first; image matching only for canvas-rendered content (per `desktop-test-strategy-reference`) |

## Limitations

- **WinAppDriver is community-described as unmaintained** since

~2022 (per the

[Appium ecosystem driver page][appiumdrivers] which states the

upstream "has not been maintained since 2022"). The latest

official release per [wad][wad] is v1.2.1 (2020-11-05). For new

projects on actively-maintained tooling, see

`appium-windows-driver`.

[appiumdrivers]: https://appium.io/docs/en/latest/ecosystem/drivers/

- **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][wad].

- WinAppDriver authoring guide - [wadauth][wadauth].

[appiumdrivers][appiumdrivers].

- Sibling skill:

`appium-windows-driver` - the

Appium proxy in front of WinAppDriver.

- Strategic frame:

`desktop-test-strategy-reference`.