Verisoft Wiki

The Desktop Dictionary provides ready-made Cucumber steps for automating native Windows desktop applications via wincore — UI Automation element and window actions, pointer gestures, PowerShell execution, clipboard, file system operations, window switching, app lifecycle, and AI-vision element finding — for both single-driver and multi-driver scenarios.

Available since version: 4.0.8

Prerequisite: the active driver must be a VerisoftDesktopDriver session on appium-wincore-driver 3.0.0 or later (automationName=Wincore).

ℹ️ Info: Desktop: every element identifier must be registered in the Object Repository.

Given:

Key Sentence Type Description Example
user switches to driver {string} Setup Switch the active driver, used only in multi-driver scenarios Givenuser switches to driver "Desktop"

When:

Key Sentence Type Description Example
user clicks button {string} Action Click an element with a real Windows mouse click. {string} is an Object Repository key, or literal "x,y" screen coordinates Whenuser clicks button "OkButton"
Whenuser clicks button "450,300"
user clicks button {string} if it exists Action Click the element only if it is on screen. If it isn't, the step is skipped and the test carries on — for things that are not always there, such as a "What's new" dialog. Waits the full configured timeout before giving up Whenuser clicks button "WhatsNewCloseButton" if it exists
user clicks {string} with options: Action Same as user clicks button, with a key/value options table — see Pointer action options Whenuser clicks "OkButton" with options:
| button | right |
| times | 2 |
user enters value {string} in field {string} Action Type a value into a field Whenuser enters value "john" in field "usernameField"
user deletes value in field {string} Action Clear a field's value Whenuser deletes value in field "usernameField"
user selects date {string} in field {string} Action Enter a date into a date field. Accepts a fixed date, or a dynamic one such as "today plus 5 days" — see Dynamic values in any sentence Whenuser selects date "15/10/2025" in field "dateField"
Whenuser selects date "{{$dd/MM/yyyy+5d}}" in field "dateField"
user {checkAction} checkbox {string} Action Tick or untick a checkbox. {checkAction} is checks or unchecks — written without quotes. It clicks only if the checkbox isn't already in that state Whenuser checks checkbox "AutoUpdateCheckbox"
user checks radio button {string} Action Select a radio button. It clicks only if it isn't already selected. To clear one, select another in its group — there is no sentence for clearing Whenuser checks radio button "ExpressOption"
user selects option {string} in field {string} Action Open a dropdown/list field and pick the option whose Name matches the given value (UI Automation list item / menu item). If the value is empty (""), the first available option is selected instead Whenuser selects option "Male" in field "genderDropdown"
user waits for {string} element to be visible within {string} seconds Action Wait up to the given number of seconds for one element, instead of the project-wide timeout Whenuser waits for "ReportGrid" element to be visible within "60" seconds
user logs in with username {string} and password {string} Action Quick login shortcut. Requires locators named usernameField, passwordField and loginButton Whenuser logs in with username "john" and password "1234"
user hovers over {string} Action Move the pointer to an element or "x,y" coordinates Whenuser hovers over "menuItem"
user hovers over {string} with options: Action Same as above, with a key/value options table — see Pointer action options Whenuser hovers over "menuItem" with options:
| durationMs | 800 |
user drags {string} to {string} Action Drag from one element or coordinates to another Whenuser drags "fileIcon" to "trashIcon"
user drags {string} to {string} with options: Action Same as above, with a key/value options table — see Pointer action options Whenuser drags "fileIcon" to "trashIcon" with options:
| durationMs | 500 |
user {elementAction} element {string} Action Perform a UI Automation element pattern action. {elementAction} is one of: invokes, expands, collapses, toggles, selects, adds to selection, removes from selection, scrolls into view, sets focus to — written without quotes.
scrolls into view uses the control's own UI Automation ScrollItemPattern; for controls without it, use user scrolls {direction} to element {string}		 Whenuser toggles element "darkModeCheckbox"
Whenuser scrolls into view element "lastRow"
user scroll {direction} Action Scroll the app window one step with the mouse wheel. {direction} is one of: up, down, left, right — written without quotes. The direction is the same as in the Web Dictionary: down moves the content down, revealing what is above it Whenuser scroll up
user scrolls {direction} to element {string} Action Scroll with the mouse wheel until the element is on screen, up to 10 attempts. Stops early when the content reaches its end, and fails if the element still isn't on screen Whenuser scrolls up to element "lastRow"
user {windowAction} window {string} Action Perform a UI Automation window pattern action. {windowAction} is one of: maximizes, minimizes, restores, closes — written without quotes Whenuser maximizes window "MainWindow"
user switches to window {string} Action Switch to the top-level window whose title matches the given text Whenuser switches to window "Settings"
user sets clipboard to {string} Action Set the Windows clipboard's plaintext content Whenuser sets clipboard to "hello world"
user deletes file at {string} Action Delete the file at the given path on the machine running the desktop driver Whenuser deletes file at "C:\temp\report.txt"
user launches the application Action Re-launch the application configured in the active driver session's capabilities Whenuser launches the application
user closes the application Action Close the current application window Whenuser closes the application
user finds {string} using AI vision Action Locate an element on screen from a plain-language description, and store its center coordinates as "x,y" in {{AIELEMENT}} for later steps. Uses the model configured via llm.model in ai-config.properties Whenuser finds "the blue Submit button" using AI vision
Whenuser clicks button "{{AIELEMENT}}"
user executes powershell {string} Action Execute a PowerShell script or command; its output is stored in {{POWERSHELL_OUTPUT}}.
Tag the scenario@dangerous — it runs arbitrary scripts on the host. The Appium server must also enable the power_shell insecure feature, and CI should exclude such scenarios by default (e.g. -Dcucumber.filter.tags="not @dangerous")		 Whenuser executes powershell "Get-Process"

Then:

Key Sentence Type Description Example
user sees element {string} {onPageState} Assertion Verify an element's presence. {onPageState} is is on page or is not on page — written without quotes Thenuser sees element "errorMsg" is not on page
user sees element {string} {compareType} text {string} Assertion Compare an element's text with the given text. {compareType} is one of: equals, not equals, contains, not contains, greater then, smaller then — written without quotes. The same words the API and Generic dictionaries use. The last two compare numbers Thenuser sees element "statusMsg" contains text "Success"
Thenuser sees element "statusMsg" not contains text "Error"
user sees element {string} {enabledState} Assertion Verify whether an element can be used. {enabledState} is is enabled or is disabled — written without quotes. The element must be on screen either way Thenuser sees element "OkButton" is disabled
user sees checkbox {string} {checkedState} Assertion Verify whether a checkbox is ticked. {checkedState} is is checked or is unchecked — written without quotes Thenuser sees checkbox "AutoUpdateCheckbox" is checked
user sees radio button {string} {checkedState} Assertion Verify whether a radio button is selected. {checkedState} is is checked or is unchecked — written without quotes Thenuser sees radio button "ExpressOption" is unchecked
user sees field {string} {fieldState} Assertion Verify whether a field holds a value. {fieldState} is is empty or is not empty — written without quotes Thenuser sees field "CommentsField" is empty
user sees {string} selected in {string} Assertion Verify the given value is (one of) the currently selected item(s) of a selection-pattern element Thenuser sees "Male" selected in "genderDropdown"
user sees clipboard contains {string} Assertion Verify the Windows clipboard's plaintext content contains the given text Thenuser sees clipboard contains "hello world"
user defines variable from field {string} as name {string} Utility Save what a field currently holds in the Store under a name, and use it later in any sentence as {{name}} — see Dynamic values in any sentence on the parent page Thenuser defines variable from field "OrderIdField" as name "orderId"
user reports info {string} Utility Write a custom message to the test report Thenuser reports info "Checkpoint reached"

Pointer action options

The key/value table passed to the with options: steps above:

Step Key Value
user clicks ... with options: button left (default), right, middle, back, forward
times Number of clicks (default 1)
durationMs Milliseconds to hold the button down (long-press)
interClickDelayMs Delay in ms between consecutive clicks when times is greater than 1 (default 100)
modifierKeys Comma-separated: shift, ctrl, alt, win
user hovers over ... with options: durationMs Duration of the pointer move animation in ms (default 500)
modifierKeys Comma-separated: shift, ctrl, alt, win
user drags ... with options: button left (default), right, middle, back, forward
durationMs Duration of the drag animation in ms
modifierKeys Comma-separated: shift, ctrl, alt, win

Example

Given user switches to driver "Desktop"
When user clicks button "OpenSettingsButton"
When user checks checkbox "AutoUpdateCheckbox"
Then user sees checkbox "AutoUpdateCheckbox" is checked
When user enters value "C:\exports" in field "ExportPathField"
Then user sees field "ExportPathField" is not empty
When user clicks button "SaveButton"
Then user sees element "StatusLabel" contains text "Saved"

Defining Locators

See Using Cucumber Dictionary — section "Defining Locators (UI Dictionaries)" — for how element identifiers are resolved. On Desktop, only the Object Repository applies.