Appium Windows Driver

repository·master·Indexed 41 days ago

https://github.com/appium/appium-windows-driver

A test automation tool and bridge to Microsoft's WinAppDriver server for testing UWP, WinForms, WPF, and Win32 applications on Windows 10. Version 6.3.0 provides platform-specific custom commands for screen recording, file management, clipboard access, and advanced mouse and keyboard gestures.

Tokens
13.2K
Snippets
54
Records
66
Agent score
50%

What's inside Appium Windows Driver

  1. Invoke platform-specific custom commands

    master

    The Appium Windows Driver provides custom command extensions prefixed with windows: to execute platform-specific scenarios that go beyond standard W3C APIs. You can invoke these using the executeScript method in your client library of choice.

    // Java 11+
    var result = driver.executeScript("windows: <methodName>", Map.of(
        "arg1", "value1",
        "arg2", "value2"
    ));
    // WebdriverIO
    const result = await driver.executeScript('windows: <methodName>', [{
        arg1: "value1",
        arg2: "value2",
     de}]);
    # 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"}
    });
  2. Install Appium Windows Driver

    master

    Since version 5.0.0, this driver is only compatible with Appium 3. Use the Appium CLI to install it into your distribution.

    Prerequisites:

    • Host must be running Windows 10.
    • Developer mode must be enabled on the host.
    • Note: As of version 3.0.0, the driver does not automatically install the WinAppDriver server. You must install it manually or use the provided driver script.
    appium driver install windows
  3. Configure the WinAppDriver executable path

    master

    The Appium Windows Driver assumes the WinAppDriver.exe is located at %PROGRAMFILES%\Windows Application Driver\WinAppDriver.exe. If you have installed WinAppDriver in a custom location, you must set the APPIUM_WAD_PATH environment variable to the full path of the executable.

    You can set this via CMD or PowerShell.

    setx APPIUM_WAD_PATH "D:\New Folder\Windows Application Driver\WinAppDriver.exe"
  4. Use environment variables in file paths

    master

    When providing paths to file movement commands (pushFile, pullFile, pullFolder, windowsDeleteFile, windowsDeleteFolder), you can use Windows environment variables wrapped in percent signs (e.g., %TEMP%).

    For security reasons, only the following environment variables are supported for expansion:

    • APPDATA
    • LOCALAPPDATA
    • PROGRAMFILES
    • PROGRAMFILES(X86)
    • PROGRAMDATA
    • ALLUSERSPROFILE
    • TEMP
    • TMP
    • HOMEPATH
    • USERPROFILE
    • PUBLIC
    // Example using the TEMP environment variable
    await driver.pullFile('%TEMP%\log.txt');
  5. Troubleshoot WinAppDriver errors

    master

    The Appium Windows Driver is a thin wrapper over Microsoft's closed-source WinAppDriver REST server. If you encounter errors where WinAppDriver calls do not work as expected, the issue likely resides within the WAD binary itself rather than the Appium driver.

    Recommended steps:

    1. Report to Microsoft: Issues should be reported to the WAD issues tracker.
    2. Replace the WAD binary: If a specific WAD version is buggy, you can download a different version from the WinAppDriver Releases page. After installing, if the driver does not pick up the new version automatically, manually point to it using the APPIUM_WAD_PATH environment variable.
    3. Try an alternative driver: Consider using the NovaWindows Driver if WinAppDriver is insufficient for your needs.
  6. Manage application windows with windows: launchApp and windows: closeApp

    master

    windows: launchApp

    (Re)launches the app under test in the same session using the same capabilities configuration used at startup. This may create a new window or point the current session to an existing one depending on how the application handles multiple instances.

    windows: closeApp

    Closes the active window of the app under test.

    Note: windows: closeApp does not automatically switch to another active window if one exists. You must use the WebDriver Windows API to switch windows manually after closing one.

  7. Execute PowerShell commands via the driver

    master

    Since version 1.15.0, you can execute PowerShell scripts or commands directly from your client code using the powerShell script name.

    Security Note: This feature is considered insecure and must be explicitly enabled by providing the power_shell key to the list of enabled insecure features in your Appium server configuration.

    • Use the command key for a single command.
    • Use the script key for a full script.
    • The driver returns stdout in response. If the script returns a non-zero exit code, an exception is thrown containing the stderr.
    # Python example
    cmd = 'Get-Process outlook -ErrorAction SilentlyContinue'
    proc_info = driver.execute_script('powerShell', {'command': cmd})
    if proc_info:
        print('Outlook is running')
    
    # Java example
    String psScript = "..."
    driver.executeScript("powerShell", ImmutableMap.of("script", psScript));
  8. Manage clipboard with windows: setClipboard and windows: getClipboard

    master

    windows: setClipboard

    Sets the Windows clipboard content.

    • b64Content (string, required): Base64-encoded content.
    • contentType (string, optional): 'plaintext' (default) or 'image' (if content is a PNG).

    windows: getClipboard

    Retrieves the Windows clipboard content.

    • contentType (string, optional): 'plaintext' (default) or 'image' (to retrieve a Base64-encoded PNG).

    Returns: Base-64 encoded content of the clipboard.

  9. Scroll with windows: scroll

    master

    A shortcut for a mouse wheel scroll gesture using the WinApi SendInput. Ensure the target control is focused before invoking.

    Arguments:

    • elementId (string, optional): Target element ID.
    • x (number, optional): Horizontal coordinate.
    • y (number, optional): Vertical coordinate.
    • deltaX (number, optional): Horizontal wheel movement (positive = right, negative = left).
    • deltaY (number, optional): Vertical wheel movement (positive = forward/away from user, negative = backward/toward user).
    • Note: You must provide either deltaX or deltaY, but not both.
    • modifierKeys (string[] or string, optional): Keys to depress during scroll.
  10. Custom keyboard input with windows: keys

    master

    A shortcut for customized keyboard input using KeyAction objects.

    Arguments:

    • actions (KeyAction[] or KeyAction, required): One or more dictionaries defining the input sequence.

    KeyAction Object Structure:

    • pause (number, optional): Delay in milliseconds between key inputs.
    • text (string, optional): Unicode text to type. (Note: surrogate characters like smileys are not supported).
    • virtualKeyCode (number, optional): A valid Windows Virtual-Key Code.
    • down (boolean, optional): If true, the key is depressed; if false, it is released. Important: Always release depressed keys in your tests.

    Example actions payload:

    [
      {"virtualKeyCode": 0x10, "down": true},
      {"text": "appium likes you"},
      {"virtualKeyCode": 0x10, "down": false}
    ]
  11. Drag and drop with windows: clickAndDrag

    master

    A shortcut for a drag and drop gesture.

    Arguments:

    • startElementId (string, optional): The element to start dragging from.
    • startX (number, optional): Starting X coordinate.
    • startY (number, optional): Starting Y coordinate.
    • endElementId (string, optional): The element to drop onto.
    • endX (number, optional): Ending X coordinate.
    • endY (number, optional): Ending Y coordinate.
    • modifierKeys (string[] or string, optional): Keys to depress during drag.
    • durationMs (number, optional): Time in ms between press and movement. Default is 5000ms.
    • button (string, optional): Mouse button to use. Default is left.