appium-windows-driver

Overview

Per the appium-windows-driver repository:

"Appium Windows Driver is a test automation tool for Windows devices and acts as a proxy to Microsoft's WinAppDriver server."

It is the Appium-ecosystem wrapper in front of Microsoft's WinAppDriver.exe (awd). The Node.js driver itself is actively maintained (see awd for the current release), while the underlying WinAppDriver service is described on the Appium ecosystem driver page as "has not been maintained since 2022", which is why the wrapper now includes a built-in installer (appium driver run windows install-wad) to pin a known-good WinAppDriver version.

Sibling differentiation: winappdriver drives the same UIA surface directly via the Microsoft service - pick that skill if the project does not already use Appium or wants no Node.js dependency on the test host. Pick appium-windows-driver when the project already runs Appium for iOS / Android / Mac2 (per desktop-test-strategy-reference for the Mac2 sibling) and Windows is the next platform to add.

When to use

• Project already runs Appium 2.x for mobile + Mac2 - add Windows with the same client.
• Tests need Windows-specific gestures (windows: scroll, windows: clickAndDrag) beyond raw W3C WebDriver.
• Tests need to execute PowerShell at session boundaries (appium: prerun / appium:postrun).
• A consistent capability schema across platforms matters more than minimizing test-host dependencies.

How to use

1. Install Appium + the Windows driver (appium driver install windows), pin the underlying WinAppDriver via appium driver run windows install-wad, then launch the server on 127.0.0.1:4723 (Install). Verify: curl http://127.0.0.1:4723/status returns HTTP 200 before proceeding; if it fails, the server is not listening - re-check the appium --port 4723 launch and the driver install.
2. Declare session capabilities with the appium: vendor prefix - platformName: windows, appium:automationName: windows, appium:app (Declare session capabilities).
3. Author a test that resolves a UIA element by Name / AccessibilityId and drives it end to end (Worked example).
4. Add Windows-namespaced gestures (windows: scroll / clickAndDrag / keys), multi-window switching, and appium:prerun / appium:postrun PowerShell hooks as the suite needs them - see references/gestures-hooks-and-ci.md.
5. Gate CI on a Windows runner; JUnit output feeds junit-xml-analysis - full workflow in references/gestures-hooks-and-ci.md.

Install

Per awd:

npm install -g appium
appium driver install windows

Then install the underlying WinAppDriver server via the driver- provided helper (awd):

appium driver run windows install-wad
# Or pin a version:
appium driver run windows install-wad 1.2.1

The helper downloads the pinned WinAppDriver installer to C:\Program Files (x86)\Windows Application Driver\ - the standard Microsoft install path described in winappdriver.

Launch the Appium server:

appium --port 4723

Standard Appium 2.x defaults - listens on 127.0.0.1:4723. Sessions to this port forward Windows-specific calls to the WinAppDriver service, which Appium spawns automatically when the first session is created.

Declare session capabilities

Per awd:

Example capability JSON:

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

Worked example

Drive one element end to end - launch Notepad, type into its editor, read the value back, and quit the session (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')
assert 'Hello from Appium Windows' in editor.text

driver.quit()

Locators (AccessibilityId, Name, ClassName, etc.) carry the same UIA semantics as in winappdriver - the driver proxies them through to WinAppDriver unchanged.

Anti-patterns

Limitations

• Windows-only. The driver runs Appium against UIA on Windows 10/11. Cross-OS test sharing relies on parallel drivers (mac2, xcuitest, uiautomator2).
• Underlying WinAppDriver maintenance gap. Per appiumdrivers, the WinAppDriver server "has not been maintained since 2022"; bugs in the UIA-to-WebDriver layer itself can only be patched in the Appium driver, not in the upstream service. NovaWindows is referenced on appiumdrivers as "a drop-in replacement for the partially unmaintained Windows driver" - consider for new heavy use.
• Appium server overhead. Adds a Node.js process layer in front of WinAppDriver - slightly slower session start than direct winappdriver. For tests where session startup time dominates (very short tests, large suites), direct WinAppDriver is faster.
• PowerShell hooks run as the test user. They cannot bypass UAC or other security boundaries; design fixtures around the test user's permissions.
• Same UIA constraints as direct WinAppDriver. GPU-rendered surfaces, DirectComposition, and apps that don't publish UIA are uncovered (see winappdriver limitations).

References

• appium-windows-driver README - awd.
• Appium ecosystem drivers page - appiumdrivers.
• Deep reference (gestures, multi-window sessions, PowerShell hooks, CI wiring): references/gestures-hooks-and-ci.md.
• Sibling skill (direct service): winappdriver.
• Strategic frame: desktop-test-strategy-reference.
• Downstream: junit-xml-analysis.