---
name: winappdriver
description: "Authors and runs Windows UI tests against WinAppDriver, Microsoft's W3C-WebDriver service for UWP / WPF / WinForms / Win32 apps: installing + launching `WinAppDriver.exe` on `127.0.0.1:4723`, declaring `app` / `platformName` / `appArguments` / `appTopLevelWindow` capabilities, finding elements by `AccessibilityId` / `Name` / `ClassName`, and Windows-runner CI. Use when driving a native Windows app from a Selenium-style client (C#, Java, Python, Ruby, JS); for the actively-maintained Appium 2.x wrapper over the same server use appium-windows-driver, for a C#-only FlaUI client use flaui-tests, and to choose among Windows desktop drivers first use desktop-test-strategy-reference."
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.

## 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](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](references/locators-and-ci.md).

## Install + enable

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\`.

## Launch the service

Per [wad][wad], launch on the default endpoint:

```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
W3C-WebDriver session requests. Custom IP / port / URL-prefix bindings
(which require an admin shell) are in
[references/locators-and-ci.md](references/locators-and-ci.md).

## Declare session capabilities

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`).

## 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][wadauth]:

```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 `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](references/locators-and-ci.md).

## 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 |
| Running tests with Developer Mode disabled | Session creation fails with cryptic error | Enable Developer Mode (Install + enable) ([wad][wad]) |
| 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].
- Appium ecosystem drivers page (maintenance status note) -
  [appiumdrivers][appiumdrivers].
- Deep reference (locator-strategy table, `Inspect.exe` discovery,
  custom service bindings, attach-to-running-window, CI wiring):
  [references/locators-and-ci.md](references/locators-and-ci.md).
- Sibling skill:
  `appium-windows-driver` - the
  Appium proxy in front of WinAppDriver.
- Strategic frame:
  `desktop-test-strategy-reference`.