Desktop Driver (Windows Native App Automation)

Overview

VerisoftDesktopDriver and DesktopBasePage provide automation for Windows native (desktop) applications via appium-wincore-driver. This is the desktop analog of the mobile/web drivers in the framework — page objects extend DesktopBasePage instead of WebBasePage / MobileBasePage.

You can find a detailed documentation for the driver in here

You’ll also find a general description in here

Requirements:

• Appium server with appium-wincore-driver 3.0.0 or newer installed: appium driver install appium-wincore-driver

• Capabilities must include:

  • platformName = "Windows"
  • automationName = "Wincore"

• macOS is not supported.

Page Object HierarchyPage Object Hierarchy

BasePage
├── WebBasePage
├── WebBasePageJS
├── MobileBasePage
└── DesktopBasePage   ← Windows native apps

Supported Functions

UI Automation Patterns (element-based)

Window Management

App Lifecycle

Pointer Input

Options builders (WindowsClickOptions, WindowsHoverOptions, WindowsScrollOptions, WindowsClickAndDragOptions, WindowsKeysOptions) are static factory + fluent builders on VerisoftDesktopDriver, e.g.:

getDesktopDriver().windowsClick(
    WindowsClickOptions.onElement(myButton)
        .button("right")
        .modifierKeys(ModifierKey.CTRL, ModifierKey.SHIFT)
        .times(2)
        .durationMs(300));

WindowsClickOptions also supports interClickDelayMs(ms) (default 100), the delay between clicks when times > 1. WindowsClickAndDragOptions supports button(...) and durationMs(ms) (default 500)

driver.windowsKeys("username", Keys.TAB, "password", Keys.ENTER);
driver.windowsKeys(Keys.chord(Keys.CONTROL, "a"));

driver.windowsKeys(WindowsKeysOptions.create()
        .keyDown(Keys.CONTROL).pressKey("a").pressKey("c").keyUp(Keys.CONTROL));

driver.windowsKeys(WindowsKeysOptions.create()
        .type("search term").pause(200).pressKey(Keys.ENTER));

Supported modifier keys (ModifierKey enum): SHIFT, CTRL, ALT, WIN.

Scrolling (mouse wheel)

The direction works the same way as in the swipe methods: DOWN moves the content down, which reveals what is above it. UP reveals what is below.
If the target never comes on screen, the method throws ElementNotInteractableException.
The scrollInToViewElement variants work only in the native context.

Clipboard

Browser Address Bar (best-effort)

Caveat: These go through keyboard shortcuts, not a native extension command — there is no reliable way to detect "is this actually a browser window." Only meaningful when the focused top-level window is a browser exposing a standard address bar bound to CTRL+L.

System / Environment

File System

Screen Recording

Vision-Based Element Finding

model is the vision LLM id (for example claude-sonnet-4-6). See the appium-wincore-driver API.md for the supported prefixes and the API-key environment variables.

Standard Selenium (partially supported)

Context Switching (WebView Support)

VerisoftDesktopDriver implements SupportsContextSwitching, so context(name), getContext(), and getContextHandles() are supported. This matters for apps that embed a web renderer (Electron, CEF-based apps, etc.) — the driver can enumerate and switch into a WEBVIEW_* context the same way VerisoftMobileDriver does for hybrid mobile apps. WEBVIEW_* contexts require the webviewEnabled capability.

Once switched into a WEBVIEW_* context, appium-wincore-driver transparently proxies most standard WebDriver commands to a real chromedriver/edgedriver session attached via CDP. Concretely, the following are supported while a WEBVIEW_* context is active (and will fail/throw in the default native context, since appium-desktop-driver has no native handler for them):

• get(url)
• navigate() — back/forward/refresh/to
• switchTo().frame(...) (all overloads), switchTo().parentFrame(), switchTo().defaultContent()
• switchTo().newWindow(typeHint) — note: a window opened this way isn't auto-tracked as the current context; call getContextHandles() / context(name) again to pick it up
• switchTo().alert()
• manage().addCookie(), deleteCookieNamed(), deleteCookie(), deleteAllCookies(), getCookies(), getCookieNamed()
• print(printOptions)
• addVirtualAuthenticator(), removeVirtualAuthenticator()
• executeScript(String, Object...) (plain JS execution)
• getCurrentUrl(()
• swipe* touch helpers and W3C wheel scrolling

windows:-prefixed extension commands and executePowerShell() always target the native UIA layer regardless of the active context.

Unsupported Operations

Calling any of these throws UnsupportedOperationException, regardless of active context — appium-wincore-driver has no implementation for them at all, native or WEBVIEW_*:

• pin(script), unpin(key), getPinnedScripts() — BiDi script pinning; the plugin has no BiDi bridging code in either context
• executeScript(ScriptKey, args...) — same BiDi gap as above (note: this only blocks the ScriptKey-pinned-script overload; plain executeScript(String, Object...) works fine in a WEBVIEW_* context, see above)

Touch/gesture (mobile-specific)

swipe* helpers fail in the native context, because appium-wincore-driver synthesizes no touch input. They work in a WEBVIEW_* context, where the call is proxied to chromedriver/edgedriver. On native UI, use windowsClick, windowsHover, windowsScroll, windowsClickAndDrag, scrollByDirection, scrollInsideContainer or scrollInToViewElement instead

Notes

• Coordinate-based methods (windowsClick(x, y), windowsScroll(x, y, ...), etc.) expect physical pixel coordinates. If working from logical UIAutomation coordinates, convert using windowsGetDpiScale() first.
• windowsGetUrl() / windowsSetUrl() have no verification that the focused window is actually a browser — use with that caveat in mind.

Example

package co.verisoft.examples.drivers;

import co.verisoft.fw.selenium.drivers.VerisoftDesktopDriver;
import co.verisoft.fw.selenium.drivers.factory.DriverCapabilities;
import co.verisoft.fw.selenium.drivers.factory.DriverUrl;
import co.verisoft.fw.selenium.junit.extensions.DriverInjectionExtension;
import co.verisoft.fw.selenium.junit.extensions.ScreenShotExtension;
import co.verisoft.fw.selenium.junit.extensions.SeleniumLogExtesion;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.By;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;

import static org.junit.jupiter.api.Assertions.assertEquals;

/**
 * Self-contained example of a VerisoftDesktopDriver test.
 * Everything a dev needs is in this one file, split into three parts
 * that normally live in three separate files in a real project:
 *
 *   1. CapabilitiesConfig  - a Spring @Configuration bean per named capability set
 *                            (normally: src/main/java/.../dependencyinjection/DesktopCapabilitiesConfig.java)
 *   2. BaseTest            - registers the JUnit extensions that make driver
 *                            injection, screenshots-on-failure and log capture work
 *                            (normally: src/test/java/.../DriverBaseTest.java, extended by every UI test class)
 *   3. ExampleTest         - the actual test, extends BaseTest and asks for a
 *                            VerisoftDesktopDriver via @DriverCapabilities/@DriverUrl
 *
 * Requires an Appium server running on localhost:4723 with appium-wincore-driver installed.
 */
class VerisoftDesktopDriverExampleTest {

    @Configuration
    static class CapabilitiesConfig {

        @Bean("windows-notepad")
        public DesiredCapabilities windowsNotepad() {
            DesiredCapabilities caps = new DesiredCapabilities();
            caps.setCapability("platformName", "Windows");
            caps.setCapability("appium:automationName", "Wincore");
            caps.setCapability("appium:app", "C:/Windows/System32/notepad.exe");
            caps.setCapability("ms:waitForAppLaunch", 5);
            return caps;
        }
    }

    @ExtendWith({DriverInjectionExtension.class, ScreenShotExtension.class, SeleniumLogExtesion.class})
    static class BaseTest {
        // Body stays empty here: the extensions above handle driver injection,
        // screenshots and log capture on their own. This is the place to add
        // shared @BeforeAll / @AfterAll hooks common to all UI tests, if needed.
    }

    @ExtendWith(SpringExtension.class)
    @ContextConfiguration(classes = CapabilitiesConfig.class)
    static class ExampleTest extends BaseTest {

        @Test
        void shouldTypeTextIntoNotepad(
                @DriverCapabilities("windows-notepad")
                @DriverUrl("http://127.0.0.1:4723")
                VerisoftDesktopDriver driver) {

            WebElement editArea = driver.findElement(By.xpath("//Document"));
            editArea.sendKeys("hello world");

            assertEquals("hello world", editArea.getText());
        }
    }
}