Appium NovaWindows Desktop Automation: A Practical Guide

Appium NovaWindows desktop automation is quickly becoming a modern alternative to the traditional WinAppDriver-based stack. NovaWindows Driver is a community Appium driver that communicates with Windows UI Automation and supports native Windows applications including Win32, WinForms, WPF, and UWP applications. For QA teams, the attraction is straightforward: existing Appium concepts sessions, capabilities, locators, WebDriver clients, and assertions can be applied to Windows desktop testing while gaining access to Windows-specific UI Automation features such as RawView and control pattern operations. The important caveat is that NovaWindows is still evolving. Treat adoption as an engineering proof of concept rather than assuming every WinAppDriver test will migrate unchanged. This guide explores how to approach Appium NovaWindows desktop automation pragmatically, from version pinning to locator strategy and migration planning. If your team is new to desktop app automation testing, the fundamentals covered here will help you build a reliable foundation.

Table of Content

• What Is NovaWindows Driver?
• Choose a Stable Version Baseline
• How Appium + NovaWindows Works
• Install and Configure
• Inspect UI Elements & Choose Locators
• Build Your First Test
• Use UI Automation Patterns
• Migrating from WinAppDriver
• Practical Automation Checklist
• Conclusion

What Is NovaWindows Driver, and Why Use It with Appium?

Appium itself does not directly automate Windows controls. It hosts platform-specific drivers. A test client sends WebDriver commands to the Appium server, Appium routes them to NovaWindows, and NovaWindows interacts with the application’s Windows UI Automation tree.

NovaWindows currently documents support for:

• Classic Win32 applications
• Windows Forms applications
• WPF applications
• UWP applications
• Windows 10 or later hosts
• Appium 2 and Appium 3

The stable 1.x architecture uses a PowerShell-backed implementation. The NovaWindows 2.0 previews replace that backend with a compiled C# UI Automation server, which is a significant architectural change and should not be mixed into a stable 1.x implementation guide.

Appium’s own documentation provides additional context for considering NovaWindows. Its standard Windows Driver proxies Microsoft’s WinAppDriver server, and Appium notes that the Microsoft server component has not been maintained since 2022. NovaWindows is listed separately as a community-maintained Windows-native driver.

Choose a Stable Version Baseline Before You Start

Desktop automation is sensitive to combinations of the Appium server, driver, client library, Windows build, display configuration, and AUT technology. Record those versions instead of simply installing “latest” on every build agent.

As of September 24, 2026, the stable Appium package is 3.7.0. NovaWindows needs slightly more care. GitHub Releases still marks v1.4.3 as its latest formal release, but the repository’s current package.json reports 1.4.5. An open issue from September 18 reports that NovaWindows 1.4.5 could not load with Appium 3.7.0 in one environment because @appium/logger was missing. That report is not proof that every installation fails, but it is sufficient reason to pin and validate versions rather than auto-updating a CI environment.

For this article, the implementation baseline is therefore:

• Windows: Windows 10+ (Validate the exact Windows build used by your test agents)
• Appium: 3.7.0 (Current stable package at research time)
• NovaWindows: 1.4.3 (Latest formal GitHub release; pin until newer combinations are verified)
• Test language: Python (Example uses pytest)
• Appium client: Appium Python Client (Pin a client/Selenium combination after validation)

How Appium NovaWindows desktop automation Works

The execution flow for Appium NovaWindows desktop automation looks like this:

• Python / pytest test
• Appium Python Client
• W3C WebDriver
• Appium 3 Server
• NovaWindows Driver
• Microsoft UI Automation
• Windows Desktop Application

Microsoft UI Automation exposes application interfaces as a hierarchy of automation elements. Those elements have properties such as AutomationId, Name, ControlType, and ClassName, while control patterns describe what a control can actually do. For example, a button may expose Invoke, a checkbox may expose Toggle, and an editable field may expose Value.

Install and Configure Appium NovaWindows desktop automation

Install Appium globally using npm. Appium does not bundle platform drivers, so NovaWindows must be installed separately. Appium’s extension CLI supports installing a specific npm version, which is useful for reproducible build agents.

npm install -g [email protected]
appium --version
appium driver install [email protected] --source=npm
appium driver list --installed --updates
  

For the Python example:

python -m pip install Appium-Python-Client pytest
  

Then start the Appium server:

appium
  

By default, a locally started Appium server listens on port 4723 and prints its usable connection URLs to the console.

Core NovaWindows capabilities

NovaWindows requires platformName to identify Windows and automationName to be NovaWindows. It can either launch an application or attach to an existing top-level window.

• platformName: Set to Windows
• appium:automationName: Set to NovaWindows
• appium:app: Executable path or supported application identifier
• appium:appTopLevelWindow: Attach to an existing application’s window handle
• appium:shouldCloseApp: Control whether the application closes after the session
• appium:appArguments: Pass startup arguments
• appium:appWorkingDir: Set the application’s working directory
• appium:webviewEnabled: Enable WebView automation
• appium:webviewDevtoolsPort: Control the DevTools communication port

Inspect UI Elements and Choose Locator Strategies

A desktop test becomes difficult to maintain when locators are guessed from screenshots or visible labels. Use Accessibility Insights for Windows to inspect the target application first. Microsoft recommends moving toward Accessibility Insights rather than relying exclusively on older Windows SDK inspection tools.

For every control you plan to automate, record at least:

• AutomationId: Usually the first property to evaluate for a stable locator
• Name: Useful for semantics, but may change with localization
• ControlType: Distinguishes buttons, documents, edit boxes, trees, etc.
• ClassName: Helpful for framework-specific controls
• Supported patterns: Determines whether Invoke, Value, Toggle, Selection, etc. can be used
• Parent/child structure: Helps avoid ambiguous locators
• IsControlElement / IsContentElement: Helps explain why a control appears in one UIA view but not another

NovaWindows documents Accessibility ID, class name, RuntimeId through id, Name, tag name, XPath 1.0, and a custom windows uiautomation strategy. A practical locator order is:

• Accessibility ID / AutomationId: First choice when meaningful and stable (Risk: Developers may change it between releases)
• UI Automation conditions: Complex property-based targeting (Risk: More framework-specific)
• Name: Useful when the label itself is contractual (Risk: Localization and duplicate names)
• Class name: Useful when combined with context (Risk: Often shared by many controls)
• XPath: Last-resort structural queries (Risk: Sensitive to hierarchy changes)
• RuntimeId: Runtime comparisons/debugging (Risk: Not a persistent cross-run identifier)

Build Your First NovaWindows Desktop Test

The following example launches Notepad, finds its editable area, writes deterministic text, reads the UI Automation value back, asserts it, and closes the session.

Preconditions:

• Appium: Running at 127.0.0.1:4723
• NovaWindows: Installed and visible in appium driver list –installed
• Application: C:\Windows\System32\notepad.exe exists
• Locator: Accessibility Insights confirms the editor locator on your Windows build

import pytest
from appium import webdriver
from appium.options.windows import WindowsOptions
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait

APPIUM_URL = "http://127.0.0.1:4723"
NOTEPAD_PATH = r"C:\Windows\System32\notepad.exe"
TEST_TEXT = "NovaWindows desktop automation smoke test"

@pytest.fixture
def driver():
    options = WindowsOptions()
    options.platform_name = "Windows"
    options.automation_name = "NovaWindows"
    options.app = NOTEPAD_PATH
    options.set_capability("appium:shouldCloseApp", True)
    session = webdriver.Remote(APPIUM_URL, options=options)
    yield session
    session.quit()

def test_notepad_text_round_trip(driver):
    editor = WebDriverWait(driver, 10).until(
        lambda d: d.find_element(By.CLASS_NAME, "Edit")
    )
    driver.execute_script("windows: setValue", editor, TEST_TEXT)
    actual_value = driver.execute_script("windows: getValue", editor)
    assert actual_value == TEST_TEXT
  

Use Windows UI Automation Patterns for More Reliable Interactions

A common mistake in desktop automation is to reproduce every user action as pointer movement plus a click. UI Automation control patterns expose the behaviour of a control. Microsoft documents Invoke for invokable controls, Selection for selectable elements, Scroll for scrollable areas, Value for editable values, Toggle for toggleable states, and other patterns.

NovaWindows exposes corresponding platform commands:

# Activate a button through InvokePattern
driver.execute_script("windows: invoke", save_button)

# Set and retrieve a ValuePattern value
driver.execute_script("windows: setValue", username_field, "qa_user")
current_value = driver.execute_script("windows: getValue", username_field)

# Toggle a checkbox
driver.execute_script("windows: toggle", remember_me_checkbox)

# Expand a tree or combo-box control
driver.execute_script("windows: expand", account_tree)
  

These methods should only be used when the target control exposes the associated pattern. If a custom control does not expose a meaningful UI Automation pattern, that is important testability information in its own right.

Why Invoke can matter on scaled displays: NovaWindows has an open issue reporting that physical element.click() operations missed their target on a HiDPI display while UI Automation Invoke worked correctly. DPI scaling belongs in your desktop automation test matrix.

Migrating Existing WinAppDriver Tests to NovaWindows

Appium describes NovaWindows as a replacement option for its partially unmaintained Windows stack, but “drop-in replacement” for Appium NovaWindows desktop automation should not be interpreted as “change one string and skip regression testing.”

A migration typically begins with these changes:

• automationName: Windows → NovaWindows
• Driver: Appium Windows Driver → NovaWindows Driver
• Server: External WinAppDriver server → NovaWindows’ own backend
• Locators: WinAppDriver locator set → Similar strategies plus NovaWindows UIA conditions
• Interactions: Generic pointer interaction → Generic interaction plus UIA-pattern extensions
• Lifecycle: WinAppDriver-specific assumptions → Revalidate startup, attach, handles and shutdown

The normal migration process should be:

• Freeze the current WinAppDriver suite as a baseline.
• Select a small but difficult set of workflows.
• Install NovaWindows in a separate environment.
• Change the driver/session configuration.
• Re-run existing AutomationId locators before rewriting them.
• Replace fragile physical interactions with UIA patterns where appropriate.
• Exercise dialogs and multi-window cases.
• Test display scaling.
• Compare runtime using the same application build and machine.
• Migrate incrementally only after functional equivalence is demonstrated.

For teams maintaining the older stack, Codoid’s existing WinAppDriver implementation guide provides setup and locator context. For a broader choice between desktop automation frameworks, Codoid also maintains a desktop automation testing tools decision framework.

Practical NovaWindows Automation Checklist

Before moving a suite into CI, verify that:

• The Appium, NovaWindows, Python-client, Selenium, Windows, and AUT versions are pinned or recorded.
• Every important locator has been inspected rather than guessed.
• AutomationId is preferred where it is genuinely stable.
• Localized Name properties are not treated as immutable identifiers.
• RuntimeId is not persisted as a cross-run locator.
• XPath is reserved for cases where simpler properties cannot identify the element.
• UI Automation patterns are used where they provide a more semantic interaction.
• Display scaling is included in the environment matrix.
• Multi-window workflows verify window identity before switching.
• WebView2 runtime and driver compatibility are controlled.
• Explicit waits represent actual application state.
• Tests leave the workstation in a clean state.
• Screenshots, Appium logs, application version, and key UI state are captured on failure.
• PowerShell execution is disabled unless a test genuinely requires it.
• Driver upgrades are validated in a staging test agent before reaching the main CI pool.

Conclusion

Appium NovaWindows desktop automation gives QA teams a modern path for Windows desktop testing without abandoning the WebDriver/Appium model they may already use elsewhere. The largest improvement in test design comes from thinking in terms of Windows UI Automation semantics, not simply replacing manual clicks with automated clicks. Inspect the automation tree, establish stable locator contracts, use control patterns where they fit, manage application and window lifecycle explicitly, and test environmental factors especially DPI scaling and WebView runtimes that affect real desktop systems.

NovaWindows is promising, but it is also actively evolving. Pin versions, monitor release and issue activity, and require a representative proof of concept before migrating a large production suite. To explore how Codoid can help you build a maintainable desktop automation strategy, visit our desktop app automation testing services page, or learn more about our broader test automation services.

Ready to Scale Your Desktop Automation Strategy?

Talk to an Expert

Frequently Asked Questions