NovaWindows Driver
===================

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/3 and is not compatible with Appium 1. To install
> the driver, simply run:
> appium driver install --source=npm appium-novawindows-driver

Usage

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 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:

Capability Name | Description
--- | ---
platformName | Must be set to Windows (case-insensitive).
automationName | Must be set to NovaWindows (case-insensitive).
smoothPointerMove | CSS-like easing function (including valid Bezier curve). This controls the smooth movement of the mouse for delayBeforeClick ms. Example: ease-in, cubic-bezier(0.42, 0, 0.58, 1).
delayBeforeClick | Time in milliseconds before a click is performed.
delayAfterClick | Time in milliseconds after a click is performed.
appTopLevelWindow | The handle of an existing application top-level window to attach to. It can be a number or string (not necessarily hexadecimal). Example: 12345, 0x12345.
shouldCloseApp | Whether to close the window of the application in test after the session finishes. Default is true.
appArguments | Optional string of arguments to pass to the app on launch.
appWorkingDir | Optional working directory path for the application.
prerun | An object containing either script or command key. The value of each key must be a valid PowerShell script or command to be executed prior to the WinAppDriver session startup. See Power Shell commands execution for more details. Example: {script: 'Get-Process outlook -ErrorAction SilentlyContinue'}
postrun | An object containing either script or command key. The value of each key must be a valid PowerShell script or command to be executed after WinAppDriver session is stopped. See Power Shell commands execution for more details.
isolatedScriptExecution | Whether PowerShell scripts are executed in an isolated session. Default is false.

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.

Example

``python


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
`




Power Shell commands execution

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 pass the script as a string when executing a PowerShell command directly via the driver. Note: This shorthand does not work when using the prerun or postrun capabilities, which require full object syntax.
Here's an example code of how to control the Notepad process:

`java
// 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


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.

Element Location

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

Name | Description | Example
--- | --- | ---
accessibility id | This strategy is AutomationId attribute in inspect.exe | AppNameTitle
class name | This strategy is ClassName attribute in inspect.exe | TextBlock
id | This strategy is RuntimeId (decimal) attribute in inspect.exe | 42.333896.3.1
name | This strategy is Name attribute in inspect.exe | Calculator
tag name | This strategy is LocalizedControlType (upper camel case) attribute in inspect.exe since Appium Windows Driver 2.1.1 | Text
xpath | This strategy allows to create custom XPath queries on any attribute exposed by inspect.exe. Only XPath 1.0 is supported | (//Button)[2]
windows uiautomation | This strategy allows to create custom Windows UIAutomation conditions on any attribute exposed by inspect.exe. Both C# and PowerShell syntax is supported | new PropertyCondition(AutomationElement.HelpTextProperty, "Info")

Platform-Specific Extensions

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
// Java 11+
var result = driver.executeScript("windows: ", 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
));
`

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

`python


Python


result = driver.execute_script('windows: ', {
'arg1': 'value1',
'arg2': 'value2',
})
`

`ruby


Ruby


result = @driver.execute_script 'windows: ', {
arg1: 'value1',
arg2: 'value2',
}
`

`csharp
// Dotnet
object result = driver.ExecuteScript("windows: ", new Dictionary() {
{"arg1", "value1"},
{"arg2", "value2"}
});
`

$3

This is a shortcut for a single mouse click gesture.

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
elementId | string | no | Hexadecimal identifier of the element to click on. If this parameter is missing then given coordinates will be parsed as absolute ones. Otherwise they are parsed as relative to the top left corner of this element. | 123e4567-e89b-12d3-a456-426614174000
x | number | no | Integer horizontal coordinate of the click point. Both x and y coordinates must be provided or none of them if elementId is present. In such case the gesture will be performed at the center point of the given element. The screen scale (if customized) is not taken into consideration while calculating the coordinate. The coordinate is always calculated for the virtual screen. | 100
y | number | no | Integer vertical coordinate of the click point. Both x and y coordinates must be provided or none of them if elementId is present. In such case the gesture will be performed at the center point of the given element. The screen scale (if customized) is not taken into consideration while calculating the coordinate. The coordinate is always calculated for the virtual screen. | 100
button | string | no | Name of the mouse button to be clicked. An exception is thrown if an unknown button name is provided. Supported button names are: left, middle, right, back, forward. The default value is left | right
modifierKeys | string[] or string | no | List of possible keys or a single key name to depress while the click is being performed. Supported key names are: Shift, Ctrl, Alt, Win. For example, in order to keep Ctrl+Alt depressed while clicking, provide the value of ['ctrl', 'alt'] | win
durationMs | number | no | The number of milliseconds to wait between pressing and releasing the mouse button. By default no delay is applied, which simulates a regular click. | 500
times | number | no | How many times the click must be performed. One by default. | 2
interClickDelayMs | number | no | Duration of the pause between each click gesture. Only makes sense if times is greater than one. 100ms by default. | 10

$3

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.

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
elementId | string | no | Same as in windows: click | 123e4567-e89b-12d3-a456-426614174000
x | number | no | Same as in windows: click | 100
y | number | no | Same as in windows: click | 100
deltaX | number | no | The amount of horizontal wheel movement measured in wheel clicks. A positive value indicates that the wheel was rotated to the right; a negative value indicates that the wheel was rotated to the left. Either this value or deltaY must be provided, but not both. | -5
deltaY | number | no | The amount of vertical wheel movement measured in wheel clicks. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user. Either this value or deltaX must be provided, but not both. | 5
modifierKeys | string[] or string | no | Same as in windows: click | win

$3

This is a shortcut for a hover gesture.

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
startElementId | string | no | Same as in windows: click | 123e4567-e89b-12d3-a456-426614174000
startX | number | no | Same as in windows: click | 100
startY | number | no | Same as in windows: click | 100
endElementId | string | no | Same as in windows: click | 123e4567-e89b-12d3-a456-426614174000
endX | number | no | Same as in windows: click | 100
endY | number | no | Same as in windows: click | 100
modifierKeys | string[] or string | no | Same as in windows: click | win
durationMs | number | no | The number of milliseconds between moving the cursor from the starting to the ending hover point. 500ms by default. | 700

$3

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

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
actions | KeyAction[] or KeyAction | yes | One or more KeyAction dictionaries | `json [{"virtualKeyCode": 0x10, "down": true}, {'text': "appium likes you"}, {"virtualKeyCode": 0x10, "down": false}]`
forceUnicode | boolean | no | Forces the characters to be sent as unicode characters. Note that they won't work in keyboard shortcut combinations, but it makes them keyboard-layout independent. | true

##### KeyAction

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
pause | number | no | Allows to set a delay in milliseconds between key input series. Either this property or text or virtualKeyCode must be provided. | 100
text | string | no | Non-empty string of Unicode text to type (surrogate characters like smileys are not supported). Either this property or pause or virtualKeyCode must be provided. | Привіт Світ!
virtualKeyCode | number | no | Valid virtual key code. The list of supported key codes is available at Virtual-Key Codes page. Either this property or pause or text must be provided. | 0x10
down | boolean | no | This property only makes sense in combination with virtualKeyCode. If set to true then the corresponding key will be depressed, false - released. By default the key is just pressed once. ! Do not forget to release depressed keys in your automated tests. | true

$3

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

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
b64Content | string | yes | Base64-encoded content of the clipboard to be set | QXBwaXVt
contentType | 'plaintext' or 'image' | no | Set to 'plaintext' in order to set the given text to the clipboard (the default value). Set to 'image' if b64Content contains a base64-encoded payload of a PNG image. | image

$3

Retrieves Windows clipboard content.

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
contentType | 'plaintext' or 'image' | no | Set to 'plaintext' in order to set the given text to the clipboard (the default value). Set to 'image' to retrieve a base64-encoded payload of a PNG image. | image

#### Returns

Base-64 encoded content of the Windows clipboard.

$3

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.

#### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
treeFilter | string | yes | Defines the filter that is applied when walking the automation tree. You can use any UI Automation conditions. For simplicity, you can omit the namespace and/or the Condition word at the end. | RawView
treeScope | string | no | Defines the scope of the automation tree to be cached. It determines how far to search for elements, such as just the element itself, its children, descendants or the entire subtree. | SubTree
automationElementMode | string | no | Specifies the mode of automation element (e.g., None, Full). Determines whether the UI element is fully cached or only partially cached. | Full

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element on which the InvokePattern is called to simulate activation. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element on which the ExpandPattern is called to expand the element. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element on which the CollapsePattern is called to collapse the element. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element on which the ScrollItemPattern is called to bring the element into view. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to check for multiple selection support. | element

#### Returns

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

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element from which to retrieve the selected item. | element

#### Returns

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

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element from which to retrieve all selected items. | element

#### Returns

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

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to add to the selection. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to remove from the selection. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to select. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to toggle. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element whose value will be set. | element
2 | string | The value to be set on the element. | "new value"

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element from which to retrieve the value. | element

$3

Maximizes a window or UI element using the WindowPattern.

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The window or UI element to maximize. | element

$3

Minimizes a window or UI element using the WindowPattern.

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The window or UI element to minimize. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The window or UI element to restore. | element

$3

Closes a window or UI element using the WindowPattern.

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The window or UI element to close. | element

$3

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

#### Arguments

Position | Type | Description | Example
| --- | --- | --- | --- |
1 | Element | The UI element to set focus on. | element

$3

To be implemented.

$3

To be implemented.

$3

To be implemented.

$3

To be implemented.

$3

To be implemented.

$3

To be implemented.

$3

To be implemented.

Development

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.

`bash


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