NovaWindows Driver is a custom Appium driver designed to tackle the limitations of existing Windows automation solutions like WinAppDriver. NovaWindows Driver supports testing Universal Windows Platform (UWP), Windows Forms (WinForms), Windows Presentation Foundation (WPF), and Classic Windows (Win32) apps on Windows 10 PCs. Built to improve performance and reliability for traditional desktop applications, it offers:

Faster XPath locator performance — Reduces element lookup times, even in complex UIs. RawView element support — Access elements typically hidden from the default ControlView/ContentView. Enhanced text input handling — Solves keyboard layout issues while improving input speed. Platform-specific commands — Supports direct window manipulation, advanced UI interactions, and more. It’s designed to handle real-world scenarios where traditional drivers fall short — from tricky dropdowns to missing elements and unreliable clicks — making it an ideal choice for automating legacy Windows apps.

Note

This driver is built for Appium 2 and is not compatible with Appium 1. To get started, clone the repository and run npm install to resolve dependencies. Then, use npm run build to build the driver. Finally, add it to your Appium 2 distribution with the command: appium driver install --source=npm appium-novawindows-driver

Beside of standard Appium requirements NovaWindows Driver adds the following prerequisites:

• Appium Windows Driver only supports Windows 10 and later as the host.

Note

The driver is currently uses a PowerShell session as a back-end, and should not require Developer Mode to be on, or any other software. There's a plan to update to a better, .NET-based backend for improved realiability and better code and error management, as well as supporting more features, that are currently not possible using PowerShell alone. It is unlikely for the prerequisites to change, as this is one of the main goals of NovaWindows driver – seamless setup on any PC.

NovaWindows Driver supports the following capabilities:

Please note that more capabilities will be added as the development of this driver progresses. Since it is still in its early stages, some features may be missing or subject to change. If you need a specific capability or encounter any issues, please feel free to open an issue.

# Python3 + PyTest
import pytest

from appium import webdriver
from appium.options.windows import WindowsOptions

def generate_options():
    uwp_options = WindowsOptions()
    # How to get the app ID for Universal Windows Apps (UWP):
    # https://www.securitylearningacademy.com/mod/book/view.php?id=13829&chapterid=678
    uwp_options.app = 'Microsoft.WindowsCalculator_8wekyb3d8bbwe!App'
    uwp_options.automation_name = 'NovaWindows'

    classic_options = WindowsOptions()
    classic_options.app = 'C:\\Windows\\System32\\notepad.exe'
    classic_options.automation_name = 'NovaWindows'

    use_existing_app_options = WindowsOptions()
    # Active window handles could be retrieved from any compatible UI inspector app:
    # https://docs.microsoft.com/en-us/windows/win32/winauto/inspect-objects
    # or https://accessibilityinsights.io/.
    # Also, it is possible to use the corresponding WinApi calls for this purpose:
    # https://referencesource.microsoft.com/#System/services/monitoring/system/diagnosticts/ProcessManager.cs,db7ac68b7cb40db1
    #
    # This capability could be used to create a workaround for UWP apps startup:
    # https://github.com/microsoft/WinAppDriver/blob/master/Samples/C%23/StickyNotesTest/StickyNotesSession.cs
    use_existing_app_options.app_top_level_window = hex(12345)
    use_existing_app_options.automation_name = 'NovaWindows'

    return [uwp_options, classic_options, use_existing_app_options]


@pytest.fixture(params=generate_options())
def driver(request):
    drv = webdriver.Remote('http://127.0.0.1:4723', options=request.param)
    yield drv
    drv.quit()


def test_app_source_could_be_retrieved(driver):
    assert len(driver.page_source) > 0

Just like in Appium Windows Driver (version 1.15.0 and above) there is a possibility to run custom Power Shell scriptsfrom your client code. This feature is potentially insecure and thus needs to beexplicitly enabled when executing the server by providing power_shell key to the listof enabled insecure features. Refer to Appium Security document for more details. It is possible to ether execute a single Power Shell command or a whole script and get its stdout in response. If the script execution returns non-zero exit code then an exception is going to be thrown. The exception message will contain the actual stderr. Unlike, Appium Windows Driver, there is no difference if you paste the script with command or script argument. For ease of use, you can even pass the script as a string only, it will work the same way. Here's an example code of how to control the Notepad process:

// java
String psScript =
  "$sig = '[DllImport(\"user32.dll\")] public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow);'\n" +
  "Add-Type -MemberDefinition $sig -name NativeMethods -namespace Win32\n" +
  "Start-Process Notepad\n" +
  "$hwnd = @(Get-Process Notepad)[0].MainWindowHandle\n" +
  "[Win32.NativeMethods]::ShowWindowAsync($hwnd, 2)\n" +
  "[Win32.NativeMethods]::ShowWindowAsync($hwnd, 4)\n" +
  "Stop-Process -Name Notepad";
driver.executeScript("powerShell", psScript);

Another example, which demonstrates how to use the command output:

# python
cmd = 'Get-Process outlook -ErrorAction SilentlyContinue'
proc_info = driver.execute_script('powerShell', cmd)
if proc_info:
    print('Outlook is running')
else:
    print('Outlook is not running')

Note

NovaWindows Driver runs on a single PowerShell session, therefore you may share variables between executed PowerShell scripts. Unless the PowerShell session exits or crashes for some reason, you should be able to reuse the variables that you create.

Appium Windows Driver supports the same location strategies the WinAppDriver supports, but also includes Windows UIAutomation conditoons:

Beside of standard W3C APIs the driver provides the below custom command extensions to execute platform specific scenarios. Use the following source code examples in order to invoke them from your client code:

Note

In most cases, commands implemented in NovaWindows driver can be used more intuitively by just the element as a second argument and the value (if such is needed) as the thrid argument and so on. For example: driver.executeScript("windows: setValue", element, "valueToSet") or driver.executeScript("windows: invoke", element). Commands that are created as fallbacks to Appium Windows Driver should work as is. Open an issue if some command that you need is missing or is not behaving as it should.

// Java 11+
var result = driver.executeScript("windows: <methodName>", Map.of(
    "arg1", "value1",
    "arg2", "value2"
    // you may add more pairs if needed or skip providing the map completely
    // if all arguments are defined as optional
));

// WebdriverIO
const result = await driver.executeScript('windows: <methodName>', [{
    arg1: "value1",
    arg2: "value2",
}]);

# Python
result = driver.execute_script('windows: <methodName>', {
    'arg1': 'value1',
    'arg2': 'value2',
})

# Ruby
result = @driver.execute_script 'windows: <methodName>', {
    arg1: 'value1',
    arg2: 'value2',
}

// Dotnet
object result = driver.ExecuteScript("windows: <methodName>", new Dictionary<string, object>() {
    {"arg1", "value1"},
    {"arg2", "value2"}
});

This is a shortcut for a single mouse click gesture.

This is a shortcut for a mouse wheel scroll gesture. The API is a thin wrapper over the SendInput WinApi call. It emulates the mouse cursor movement and/or horizontal/vertical rotation of the mouse wheel. Thus make sure the target control is ready to receive mouse wheel events (e.g. is focused) before invoking it.

This is a shortcut for a hover gesture.

This is a shortcut for a customized keyboard input. Selenium keys should also work as modifier keys, unless forceUnicode option is set to true.

Sets Windows clipboard content to the given text or a PNG image.

Retrieves Windows clipboard content.

Base-64 encoded content of the Windows clipboard.

This is an asynchronous function that sends cache requests based on specific conditions. This is useful for revealing RawView elements in the element tree. Note that cached elements aren't supported by NovaWindows driver yet.

Invokes a UI element pattern, simulating an interaction like clicking or activating the element.

Expands a UI element that supports the ExpandPattern, typically used for elements that can be expanded (like trees or combo boxes).

Collapses a UI element that supports the CollapsePattern, typically used for collapsible elements (like tree nodes).

Scrolls the UI element into view using the ScrollItemPattern, ensuring that the element is visible within its container.

Checks if a UI element supports multiple selection using the SelectionPattern. Returns true if the element supports multiple selections, otherwise false.

• boolean: true if the element supports multiple selection, otherwise false.

Gets the selected item from a UI element that supports the SelectionPattern.

• Element: The selected item of the element as an Appium element.

Gets all selected items from a UI element that supports the SelectionPattern, useful for lists or combo boxes.

• Element[]: An array of selected items as Appium elements.

Adds an element to the current selection on a UI element that supports the SelectionPattern.

Removes an element from the current selection on a UI element that supports the SelectionPattern.

Selects a UI element using the SelectionPattern, simulating the action of choosing the element in a selection context.

Toggles a UI element’s state using the TogglePattern, typically used for elements like checkboxes or radio buttons.

Sets the value of a UI element using the ValuePattern (for elements like text boxes, sliders, etc.).

Gets the current value of a UI element that supports the ValuePattern (e.g., a text box).

Maximizes a window or UI element using the WindowPattern.

Minimizes a window or UI element using the WindowPattern.

Restores a window or UI element to its normal state (if it was maximized or minimized) using the WindowPattern.

Closes a window or UI element using the WindowPattern.

Sets focus to the specified UI element using UIAutomationElement's SetFocus method.

To be implemented.

To be implemented.

To be implemented.

To be implemented.

To be implemented.

To be implemented.

To be implemented.

it is recommended to use Matt Bierner's Comment tagged templates Visual Studio Code plugin so it highlights the powershell and C code used throughout the project.

# Checkout the current repository and run
npm install
# Run linting to check for code quality
npm run lint
# Transpile TypeScript files to build the project
npm run build