appium-windows-driver v2.12.21

Appium Windows Driver

Appium Windows Driver is a test automation tool for Windows devices and acts as a proxy to Microsoft's WinAppDriver server. Appium Windows Driver supports testing Universal Windows Platform (UWP), Windows Forms (WinForms), Windows Presentation Foundation (WPF), and Classic Windows (Win32) apps on Windows 10 PCs. The server itself is maintained by Microsoft at https://github.com/microsoft/WinAppDriver. Check its release notes and the vendor documentation to get more details on the supported features and possible pitfalls.

Note

Since version 2.0.0 Windows driver has dropped the support of Appium 1, and is only compatible to Appium 2. Use the appium driver install --source=npm appium-windows-driver command to add it to your Appium 2 dist.

Note

This project is actively looking for maintainers with DotNet experience.

Usage

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

• Appium Windows Driver only supports Windows 10 as the host.
• Developer mode must be enabled
• Appium downloads and installs WinAppDriver package automatically upon executing its installation scripts, although, the actual binary version could be out of date. In such case you could download and install the most recent version of WinAppDriver manually from the GitHub releases page.

Appium Windows Driver supports the following capabilities:

Example

# Python3 + PyTest
import pytest

from appium import webdriver
# Options are available in Python client since v2.6.0
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'

    classic_options = WindowsOptions()
    classic_options.app = 'C:\\Windows\\System32\\notepad.exe'
    # Make sure arguments are quoted/escaped properly if necessary:
    # https://ss64.com/nt/syntax-esc.html
    classic_options.app_arguments = 'D:\\log.txt'
    classic_options.app_working_dir = 'D:\\'

    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)

    return [uwp_options, classic_options, use_existing_app_options]


@pytest.fixture(params=generate_options())
def driver(request):
    # The default URL is http://127.0.0.1:4723/wd/hub in Appium 1
    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

You could find more examples for different programming languages at https://github.com/microsoft/WinAppDriver/tree/master/Samples

Power Shell commands execution

Since version 1.15.0 of the driver there is a possibility to run custom Power Shell scripts from your client code. This feature is potentially insecure and thus needs to be explicitly enabled when executing the server by providing power_shell key to the list of enabled insecure features. Refer to Appium Security document for more details. It is possible to ether execute a single Power Shell command (use the command argument) or a whole script (use the script argument) 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. 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", ImmutableMap.of("script", psScript));

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

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

Element Location

Appium Windows Driver supports the same location strategies the WinAppDriver supports:

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:

// 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"}
});

windows: startRecordingScreen

Record the display in background while the automated test is running. This method requires FFMPEG to be installed and present in PATH. The resulting video uses H264 codec and is ready to be played by media players built-in into web browsers.

Arguments

windows: stopRecordingScreen

Stop recording the screen. If no screen recording has been started before then the method returns an empty string.

Arguments

Returns

Base64-encoded content of the recorded media file if remotePath parameter is falsy or an empty string.

windows: deleteFile

Remove the file from the file system. This feature is potentially insecure and thus needs to be explicitly enabled when executing the server by providing modify_fs key to the list of enabled insecure features. Refer to Appium Security document for more details.

Arguments

windows: deleteFolder

Remove the folder from the file system. This feature is potentially insecure and thus needs to be explicitly enabled when executing the server by providing modify_fs key to the list of enabled insecure features. Refer to Appium Security document for more details.

Arguments

windows: launchApp

(Re)launch app under test in the same session using the same capabilities configuration given on the session startup. Generally this API would create a new app window and point the current active session to it, but the actual result may vary depending on how the actual application under test handles multiple instances creation. Check AppiumAppLaunch.cs for more examples. It is possible to switch between app windows using WebDriver Windows API

windows: closeApp

Close the active window of the app under test. Check AppiumAppClose.cs for more examples. It is possible to switch between opened app windows using WebDriver Windows API. After the current app window is closed it is required to use the above API to switch to another active window if there is any. windows: closeApp call does not perform the switch automatically. An error is thrown if the app under test is not running.

windows: click

This is a shortcut for a single mouse click gesture.

Arguments

windows: scroll

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

windows: clickAndDrag

This is a shortcut for a drag and drop gesture.

Arguments

windows: hover

This is a shortcut for a hover gesture.

Arguments

windows: keys

This is a shortcut for a customized keyboard input.

Arguments

KeyAction

windows: setClipboard

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

Arguments

windows: getClipboard

Retrieves Windows clipboard content.

Arguments

Returns

Base-64 encoded content of the Windows clipboard.

Environment Variables

Appium Windows Driver supports the following environment variables:

Troubleshooting

Various WinAppDriver calls don't work as expected or throw weird errors

Unfortunately we cannot do much about it from the Appium Windows Drive side. It is just a thin wrapper over Microsoft's WinAppDriver closed-source REST server binary, which solely performs all the heavy lifting. This driver does handle some API calls on its own, for example PowerShell scripts execution, but the overall amount of such calls is quite limited.

Eventually your best bet would be to report the issue to WAD issues tracker and hope there is some workaround for it as Microsoft has not been regularly maintaining the driver. If it turns out the issue is just a driver regression, and it was working properly in another WAD version, then you could always replace WAD binary supplied with Appium Windows Driver by default with a custom one. Simply fetch it from Releases page and install it locally. Ideally it should transparently replace the previously installed WAD and no further actions are expected. If that did not happen though, consider providing APPIUM_WAD_PATH environment variable pointing to the recently installed WAD binary path as described in Environment Variables section.

Development

# Checkout the current repository and run
npm install

Test

You can run unit and e2e tests locally:

# unit tests
npm run unit-test

# e2e tests
npm run e2e-test