win

Provides methods for Windows native applications automation.

Locators:

  • /XPATH - Locates element using an XPath 1.0 expression.

  • ~AccessibilityId - Locates element by its Accessibility ID. Attribute name in inspect.exe - AutomationId.

  • name=NAME - Locates element by its name. Attribute name in inspect.exe - Name.

  • id=ID - Locates element by its ID. Attribute name in inspect.exe - RuntimeID.

Pattern arguments:

Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise:

  • regex:PATTERN - Match using regular expression.

  • PATTERN - Verbatim matching.

assertText

Asserts element's inner text.

Text pattern can be any of the supported string matching patterns(on the top of page). If the element is not interactable, then it will allways return empty string as its text.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

pattern

String

Assertion text or pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

assertTitle

Asserts the page title.

Assertion pattern can be any of the supported string matching patterns(on the top of page).

Parameters:

Name
Type
Description

pattern

String

Assertion text or pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

assertValue

Asserts element's value.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

pattern

String

Value pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

back

Navigate backwards in the browser history or simulates back button on Android device.

clear

Clears element's value or content

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

click

Clicks on an element.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

clickLong

Performs a long click/touch on an element.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

duration

Number

Touch duration in milliseconds.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

clickMultipleTimes

Performs tap on an element multiple times in quick succession.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

taps

Number

Number of taps.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

dispose

Ends the current session.

findElement

Finds an element.

Parameters:

Name
Type
Description

locator

String

Element locator.

parent

Element

optional Optional parent element for relative search.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Element - A Element object.

findElements

Finds elements.

Parameters:

Name
Type
Description

locator

String

Element locator.

parent

Element

optional Optional parent element for relative search.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Array.<Element> - Collection of Element objects.

getAppiumLogs

Collects logs from the Appium server.

Returns:

Array.<Object> - A list of logs.

getCapabilities

Returns currently defined capabilities.

Returns:

Object - Current capabilities object.

getCurrentWindowHandle

Gets current window handle.

** Usage example:**

win.init();
win.getCurrentWindowHandle();

Returns:

String - A window handle.

getDriver

Returns the underlying WDIO driver.

Returns:

Object - WDIO driver.

getLocation

Get element's location.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Object - X and Y location of the element relative to top-left page corner.

getSource

Gets the source code of the page.

Returns:

String - HTML in case of web or hybrid application or XML in case of native.

getText

Returns the text (rendered text shown to the user; whitespace-trimmed) of an element.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

String - Element's text.

getValue

Gets element's value (whitespace-trimmed).

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

String - Element's value.

getWindowHandles

Gets handles of currently open windows.

** Usage example:**

win.init();//Opens WinAppDriver session.
win.getWindowHandles();//Gets the window handles of currently open application.

Returns:

Array.<String> - Array of all available window handles.

init

Initializes a new Appium session.

Parameters:

Name
Type
Description

caps

String

optional Desired capabilities. If not specified capabilities will be taken from suite definition.

appiumUrl

String

optional Remote Appium server URL (default: http://localhost:4723/wd/hub).

isCheckable

Determines if checkbox or radio element is checkable.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Boolean - true if element is checkable. false otherwise.

isChecked

Determines if checkbox or radio element is checked.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Boolean - true if element is checked. false otherwise.

isClickable

Determines if an element is clickable.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Boolean - true if element is clickable. false otherwise.

isExist

Wait for an element to become available.

The element is not necessary needs to be visible.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Time in milliseconds to wait for the element. Default is 60 seconds.

Returns:

Boolean - true if the element exists. false otherwise.

isSelected

Determines if an element is selected.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Boolean - true if element is selected. false otherwise.

isVisible

Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout.

Parameters:

Name
Type
Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds to wait for element to appear. Default is 60 seconds.

Returns:

Boolean - True if element was found and it was visible. False otherwise.

open

Opens an URL.

The open command waits for the page to load before proceeding.

Parameters:

Name
Type
Description

url

String

The URL to open; may be relative or absolute.

pause

Pause test execution for the given amount of milliseconds.

Parameters:

Name
Type
Description

ms

Number

Milliseconds to pause the execution for.

rightClick

Perform right click on an element.

Parameters:

Name
Type
Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

selectWindow

Selects window. Once window has been selected, all commands go to that window.

windowLocator can be:

  • title=TITLE Switch to the first window which matches the specified title. TITLE can be any ofthe supported string matching patterns (see top of the page). When using title locator, this commandwill wait for the window to appear first similarly to waitForWindow command.

  • windowHandle Switch to a window using its unique handle.

** Usage example:**

win.init();
win.selectWindow("title=FolderName");// Selects and focus a window.

Parameters:

Name
Type
Description

windowLocator

String

optional Window locator.

timeout

Number

optional Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds.

Returns:

String - windowHandle of the previously selected window.

sendKeys

Send a sequence of keyboard strokes to the active window or element.

Refer to Key Codes for the list of supported raw keyboard key codes.

** Usage example:**

win.init();//Opens browser session.
win.open("www.yourwebsite.com");// Opens a website.
win.sendKeys("Hello World");
win.sendKeys(["Backspace", "Backspace", "Enter"]); // send two Backspace key codes and Enter.
// Unicode representation can be used directly as well:
win.sendKeys("Hello World\uE003\uE003\uE007");

Parameters:

Name
Type
Description

value

String|Array.<String>

Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes.

setTimeout

Specifies the amount of time that Oxygen will wait for actions to complete.

This includes the open command, waitFor* commands, and commands which wait for elements to appear in DOM or become visible before operating on them. If command wasn't able to complete within the specified period it will fail the test. The default time-out is 60 seconds.

Parameters:

Name
Type
Description

timeout

Number

A time-out in milliseconds.

takeScreenshot

Take a screenshot of the current page or screen and return it as base64 encoded string.

** Usage example:**

win.init(caps);
var ss = win.takeScreenshot();//Take a screenshot and return it as base64 encoded string.
require("fs").writeFileSync("c:\\screenshot.png", ss, 'base64');

Returns:

String - Screenshot image encoded as a base64 string.

tap

Perform tap at the specified coordinate.

Parameters:

Name
Type
Description

x

Number

x offset.

y

Number

y offset.

transaction

Opens new transaction.

The transaction will persist till a new one is opened. Transaction names must be unique.

Parameters:

Name
Type
Description

name

String

The transaction name.

type

Send a sequence of key strokes to an element (clears value before).

Refer to Key Codes for the list of supported raw keyboard key codes.

Parameters:

Name
Type
Description

locator

String|Element

An element locator.

value

String

The value to type.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForExist

Wait for an element for the provided amount of milliseconds to exist in DOM.

The element is not necessary needs to be visible.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Time in milliseconds to wait for the element. Default is 60 seconds.

waitForInteractable

Waits for element to become interactable.

** Usage example:**

win.init();//Opens browser session.
win.waitForInteractable("id=UserName");//Waits for an element is clickable in DOM.

Parameters:

Name
Type
Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForVisible

Waits for element to become visible.

Parameters:

Name
Type
Description

locator

String|Element

Element locator.

timeout

Number

optional Time in milliseconds to wait for the element. Default is 60 seconds.

Last updated