winappdriver

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.

Step 1 - 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\.

Step 2 - Launch the service

Per wad:

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

:: Custom port (admin shell)
WinAppDriver.exe 4727

:: Bind to LAN IP (admin shell)
WinAppDriver.exe 10.0.0.10 4725

:: Bind to URL prefix (admin shell)
WinAppDriver.exe 10.0.0.10 4723/wd/hub

The service prints Press ENTER to exit. and listens for incoming W3C-WebDriver session requests.

Step 3 - Declare session capabilities

Per the WinAppDriver authoring guide:

Capability	Purpose
app	Application identifier (UWP family name) or full executable path (wadauth)
appArguments	Launch arguments string (wadauth)
appWorkingDir	Working directory for classic Win32 apps (wadauth)
appTopLevelWindow	Hexadecimal handle of an existing window to attach to (wadauth)
platformName	Target platform - set to Windows
platformVersion	Platform version string

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

Step 4 - Author a test (C#)

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.

Step 5 - Element-locator strategies

Per wadauth:

C# / Java method	UIA attribute
FindElementByAccessibilityId	AutomationId
FindElementByClassName	ClassName
FindElementById	RuntimeId (decimal)
FindElementByName	Name
FindElementByTagName	LocalizedControlType
FindElementByXPath	any attribute (XPath over the UIA tree)

To discover the right id during authoring, use Inspect.exe (ships with the Windows SDK) or Accessibility Insights for Windows - both walk the same UIA tree the driver sees.

Step 6 - Attaching to an already-running window

For tests where the app is launched externally:

var capabilities = new AppiumOptions();
// Hex window handle from Inspect.exe / Spy++
capabilities.AddAdditionalCapability("appTopLevelWindow", "0xB822E2");
capabilities.AddAdditionalCapability("platformName", "Windows");
var session = new WindowsDriver<WindowsElement>(
    new Uri("http://127.0.0.1:4723"),
    capabilities);

Per wadauth, the appTopLevelWindow capability takes a hex window handle. This is the path for testing apps that don't support fresh-launch (apps with single-instance locks, or apps requiring authenticated login flows that run outside the test).

Step 7 - Run

:: Build + test (NUnit example)
dotnet test --logger "trx;LogFileName=results.trx"

:: With session retry on flaky launches
dotnet test --filter "Category=Smoke" -- RunConfiguration.TestSessionTimeout=600000

Tests assume WinAppDriver.exe is running on 127.0.0.1:4723. A Setup fixture per test class should start the driver if it isn't already, then dispose at TearDown.

Step 8 - Parsing results

The C# Selenium client emits standard NUnit / MSTest / xUnit results (TRX, XML, or JUnit depending on logger choice). Pair with junit-xml-analysis for the cross-runner aggregation pipeline.

Step 9 - CI integration

Windows-only runner required - WinAppDriver does not run on Linux or macOS:

# .github/workflows/winappdriver.yml
jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v5
      - name: Install WinAppDriver
        # Choco installs to default path + adds shortcut
        run: choco install winappdriver -y
      - name: Enable Developer Mode (Win 10/11 runners)
        run: |
          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" `
            /t REG_DWORD /f /v AllowDevelopmentWithoutDevLicense /d 1
      - name: Start WinAppDriver
        run: |
          Start-Process -FilePath "C:\Program Files (x86)\Windows Application Driver\WinAppDriver.exe" `
            -PassThru
          Start-Sleep -Seconds 3   # Let the service bind to 4723
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.0.x' }
      - name: Test
        run: dotnet test --logger "trx;LogFileName=results.trx"
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: trx-results
          path: '**/results.trx'

WinAppDriver runs interactive - GitHub-hosted windows-latest runners have an interactive session by default, but headless self- hosted Windows containers need additional setup (the service refuses to start under Session 0).

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)
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 (Step 1) (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)
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 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.
• Sibling skill: appium-windows-driver - the Appium proxy in front of WinAppDriver.
• Strategic frame: desktop-test-strategy-reference.