Since: API Level v2
public final class

WinAppPlugin

com.webmbt.plugin.WinAppPlugin

Class Overview

WinApp plugin (in beta) provides a set of MScript methods to test windows UI applications through WinAppDriver, it currently requires Windows 10 where AUT will be installed. You must install WinAppDriver either on the local Windows 10 machine or on a remote Windows 10 machine where AUT will be tested. More info at: WinAppDriver Info.

If you have WinAppDriver server running on a remote machine, you will need to add setting WinAppURL=http://host:port/wd/hub to webdriver_WinApp.properties file in /www/config/ folder.

You may locate an element in the window control:

  • by automation id: find element with matching id, e.g.id=abc or just abc
  • by element name: find element by matching name attribute, e.g. name=abc

Additionally you can qualify the element locator with any or all of the following separated with a semi-colon ";" and no white spaces allowed around the semi-colon.

  • window=mywindow

For example: window=win1;id=xyz to find the element with id of xyz on window named win1.

Copyright © 2017 TestOptimal LLC. All Rights Reserved.

Summary

Public Constructors
WinAppPlugin()
Public Methods
String WebDriver(String... params_p)
calls a method in org.openqa.selenium.WebDriver class that accepts String parameter(s) or no parameters.
String[] WebDriverElement(String... params_p)
calls a method in org.openqa.selenium.WebElement class that accepts String parameter(s) or no parameters.
String WebDriverManage(String... params_p)
calls a method in org.openqa.selenium.WebDriver.Options class that accepts String parameter(s) or no parameters.
String WebDriverNavigate(String... params_p)
calls a method in org.openqa.selenium.WebDriver.Navigation class that accepts String parameter(s) or no parameters.
String WebDriverSwitchTo(String... params_p)
calls a method in org.openqa.selenium.WebDriver.TargetLocator class that accepts String parameter(s) or no parameters.
void clear(String locator_p)
clears the input field.
void click(String locator_p, String coordX_p, String coordY_p)
simulate click on the first element found.
void click(String locator_p)
simulate click on the first element found.
void click(String locator_p, String shiftCtrlAlt_p)
simulate click on the first element found with option of holding down shift, ctrl or alt key.
void closeWindow(String windowName_p)
closes a window
boolean containsText(String loc_p, String text_p)
returns true if the element of the locator passed in contains the text specified.
int count(String locator_p)
returns count of number of objects for the element locator passed in.
void doubleClick(String locator_p)
double click on the first element found.
void dragAndDrop(String fromLocator_p, String toLocator_p)
drag an element and drop it onto another element.
String getAllWindows()
return the information of all windows currently open.
String[] getAllWindowsID()
returns a list of window handles.@return
String[] getAttr(String locator_p, String attrName_p)
Returns the value of HTML attribute value defined in the element.
String[] getText(String locator_p)
Returns the text of the element.
String getTitle()
returns the title of the current window.
String[] getValue(String locator_p)
Returns the value of the first element found with the locator_p.
boolean isChecked(String locator_p)
returns true if the first element found with locator_p is checked: radio button or checkbox only.
boolean isDisabled(String locator_p)
returns true if any of the elements found is disabled.
boolean isPresent(String locator_p)
returns true if the element exists in the current page/frame/window.
boolean isVisible(String locator_p)
returns true if any of the elements is visible.
String locate(String loc_p)
locates the element and pass back the local locator that can be used by selenium native method.
void mouseDown(String locator_p)
trigger mouse down event on the first element found with locator_p.
void mouseOver(String locator_p)
trigger mouse over event on the first element found with locator_p.
void mouseUp(String locator_p)
trigger mouse up event on the first element found locator_p.
void restartAUT()
close AUT and restart AUT with specified URL.
void rightClick(String locator_p)
rightClick on the first element found with locator_p.
void selectOption(String locator_p, String optionLocator_p)
selects an option for the Select element.
void selectWindow(String windowName_p)
selects a specified window as the current target window which all future commands to be directed to.
void sendKey(String locator_p, String keyString_p)
type the string to the first element found with locator_p.
void setCapabilityBoolean(String capKey_p, String capVal_p)
void setCapabilityInteger(String capKey_p, String capVal_p)
void setCapabilityList(String capKey_p, String capVal_p, String delChar_p)
void setCapabilityLong(String capKey_p, String capVal_p)
void setCapabilityString(String capKey_p, String capVal_p)
sets a capability setting for the selected browser.
void setCheckBox(String locator_p, String checked_p)
sets the checkbox.
void setImplicitWait(String millis_p)
sets the implicitWait parameter for WebDriver.
void setRadioButton(String locator_p, String checked_p)
sets the first radio button found with locator_p.
void setWindowMaximized()
maximizes the browser window.
void setWindowPosition(String left_p, String top_p)
sets the window home position.
void setWindowSize(String width_p, String height_p)
sets the browser window size to the specified dimension: width and height.
int sizeOf(String locator_p)
returns the number options in the first select element found
String snapScreen(String fn_p)
Take a snapshot of current AUT window.
void type(String locator_p, String shiftCtrlAlt_p, String keyString_p)
type the string to the first element found with locator_p with the option to have shift/control/alt key pressed.
void type(String locator_p, String keyString_p)
type the string to the first element found with locator_p.
void typeKeys(String locator_p, String keyString_p)
type the string to the first element found with locator_p.
boolean waitForCondition(String locator_p, String condType_p, String condResult_p, String timeoutMillis_p)
waits for a condition specified on the element up to the specified timeout in milliseconds.
boolean waitForElement(String locator_p, String timeoutMillis_p)
waits for an element to be visible up to the specified timeout in milliseconds.
boolean waitForWindow(String winName_p, String timeoutMillis_p)
waits for a window to open/appear up to the specified timeout in milliseconds.
boolean windowExists(String winNameTitle_p)
returns true if the window with specified name/title is found.

Public Constructors

public WinAppPlugin ()

Since: API Level v2

Public Methods

public String WebDriver (String... params_p)

Since: API Level v2

calls a method in org.openqa.selenium.WebDriver class that accepts String parameter(s) or no parameters.

Example:

$WebDriver('getPageSource')
The above expression calls org.openqa.selenium.WebDriver.getPageSource().

Parameters
params_p 0, 1 or many parameters
Throws
MBTException

public String[] WebDriverElement (String... params_p)

Since: API Level v2

calls a method in org.openqa.selenium.WebElement class that accepts String parameter(s) or no parameters.

Example:

$WebDriverElement('id=f1','click')
The above expression calls org.openqa.selenium.WebElement.click()@return

Parameters
params_p String parameters
Throws
MBTException

public String WebDriverManage (String... params_p)

Since: API Level v2

calls a method in org.openqa.selenium.WebDriver.Options class that accepts String parameter(s) or no parameters.

Example:

$WebDriverManage('getCookieNamed','xyz')
The above expression calls org.openqa.selenium.WebDriver.Options.getCookieNamed("xyz") returns the cookie value.@return

Throws
MBTException

public String WebDriverNavigate (String... params_p)

Since: API Level v2

calls a method in org.openqa.selenium.WebDriver.Navigation class that accepts String parameter(s) or no parameters.

Example:

$WebDriverNavigate('back')
The above expression calls org.openqa.selenium.WebDriver.Navigation.back()@return

Throws
MBTException

public String WebDriverSwitchTo (String... params_p)

Since: API Level v2

calls a method in org.openqa.selenium.WebDriver.TargetLocator class that accepts String parameter(s) or no parameters.

Example:

$WebDriverSwitchTo('frame','ABC')
The above expression calls org.openqa.selenium.WebDriver.TargetLocator.frame("ABC")@return

Throws
MBTException

public void clear (String locator_p)

Since: API Level v2

clears the input field.

Example:

<action code="$clear('id=F1')"/> 

Throws
MBTException

public void click (String locator_p, String coordX_p, String coordY_p)

Since: API Level v2

simulate click on the first element found. Element must supports coordinates, for example an image.

Example:

<action code="$click('id=F1','100','200')"/> 

Notice that even though coordX_p and coordY_p are integer parameters, they must be enclosed by a set of single quote.

Throws
MBTException

public void click (String locator_p)

Since: API Level v2

simulate click on the first element found.

Example:

<action code="$click('id=F1')"/> 

Throws
MBTException

public void click (String locator_p, String shiftCtrlAlt_p)

Since: API Level v2

simulate click on the first element found with option of holding down shift, ctrl or alt key.

Not available for remote testing using selenium/appium/saucelabs servers.

Example:

<action code="$click('id=F1','S')"/> 

Throws
MBTException

public void closeWindow (String windowName_p)

Since: API Level v2

closes a window

Throws
MBTException

public boolean containsText (String loc_p, String text_p)

Since: API Level v2

returns true if the element of the locator passed in contains the text specified. The text must be static text string only.

Example:

<log msg="Control contains text XXXX? $containsText('id=xyz', 'XXXX')"/>

Throws
MBTException

public int count (String locator_p)

Since: API Level v2

returns count of number of objects for the element locator passed in.

Example:

<log msg="$found $count('name=paymentType') payment types on the screen"/>

Throws
MBTException

public void doubleClick (String locator_p)

Since: API Level v2

double click on the first element found.

Example:

<action code="$doubleClick('id=F1')"/>

Throws
MBTException

public void dragAndDrop (String fromLocator_p, String toLocator_p)

Since: API Level v2

drag an element and drop it onto another element. Only the first element found for both drag source and drop source locators are acted on.

Example:

<action code="$dragAndDrop('id=F1','id=f2')"/> 
The above MScript drags element F1 and drops it on the element f2.

Parameters
fromLocator_p element locator
toLocator_p element locator
Throws
MBTException

public String getAllWindows ()

Since: API Level v2

return the information of all windows currently open.

Each window is described in the following format, multiple windows are separated with a semi-colon ";". :
name:title[idx]

public String[] getAllWindowsID ()

Since: API Level v2

returns a list of window handles.@return

Throws
MBTException
MBTException
See Also

public String[] getAttr (String locator_p, String attrName_p)

Since: API Level v2

Returns the value of HTML attribute value defined in the element.

Example:

<log msg="Field attribute: $getAttr('id=F1','class')."/>

Each type of element has a set of attributes but it also allows user defined attributes.

Throws
MBTException

public String[] getText (String locator_p)

Since: API Level v2

Returns the text of the element. If multiple elements found, return a String with all text strung together separated by semicolon.

Example:

<log msg="$getText('id=rowTitle')"/> 

Throws
MBTException

public String getTitle ()

Since: API Level v2

returns the title of the current window.

Example:

<log msg="Window title is: $getTitle()"/>

Throws
MBTException

public String[] getValue (String locator_p)

Since: API Level v2

Returns the value of the first element found with the locator_p. If element does not have value attribute, it returns the text. If element still does not have text attribute, it returns blank.

Example:

<log msg="userid is: $getValue('userid')"/>

Throws
MBTException

public boolean isChecked (String locator_p)

Since: API Level v2

returns true if the first element found with locator_p is checked: radio button or checkbox only.

Example:

<log msg="The checkbox F1 checked? $isChecked('id=F1')"/>

Parameters
locator_p locator to the checkbox
Throws
MBTException

public boolean isDisabled (String locator_p)

Since: API Level v2

returns true if any of the elements found is disabled.

Example:

<log msg="Field F1 disabled?: $isDisabled('id=F1')."/>

Throws
MBTException

public boolean isPresent (String locator_p)

Since: API Level v2

returns true if the element exists in the current page/frame/window. Invisible elements are considered present.

Example:

<if val1="$isPresent('checkbox1')" op="eq" val2="true"/> 
    <log msg="checkbox1 is present on this page">
</if>

Throws
MBTException

public boolean isVisible (String locator_p)

Since: API Level v2

returns true if any of the elements is visible.

Example:

<log msg="Field F1 visible?: $isVisible('id=F1')."/> 

Throws
MBTException

public String locate (String loc_p)

Since: API Level v2

locates the element and pass back the local locator that can be used by selenium native method. This method should only be used inside the parameter of the native method call.

Example:

$_keyPress('$locate('win=abc;xpath=id(\'id123\')', 'A') which set the focus
to window abc and passes xpath=id(\'id123\') to $_keyPress('xpath=id(\'id123\')', 'A')@return

Throws
MBTException

public void mouseDown (String locator_p)

Since: API Level v2

trigger mouse down event on the first element found with locator_p.

Example:

<action code="$mouseDown('id=F1')"/> 

Throws
MBTException

public void mouseOver (String locator_p)

Since: API Level v2

trigger mouse over event on the first element found with locator_p.

Example:

<action code="$mouseOver('id=F1')"/> 

Throws
MBTException

public void mouseUp (String locator_p)

Since: API Level v2

trigger mouse up event on the first element found locator_p.

Example:

<action code="$mouseUp('id=F1')"/>

Throws
MBTException

public void restartAUT ()

Since: API Level v2

close AUT and restart AUT with specified URL.

Throws
Exception

public void rightClick (String locator_p)

Since: API Level v2

rightClick on the first element found with locator_p.

Example:

<action code="$rightClick('id=F1')"/> 

Throws
MBTException

public void selectOption (String locator_p, String optionLocator_p)

Since: API Level v2

selects an option for the Select element.

Example:

<action code="$selectOption('id=selectF1','value=2')"/> 

Parameters
locator_p locator for the element
optionLocator_p locator for the option to be selected.
  • label=labelPattern: matches options based on their labels, i.e. the visible text. (This is the default.)

    For example, label=regexp:^[Oo]ther

  • value=valuePattern: matches options based on their values.

    For example, value=other

  • id=id: matches options based on their ids.

    id=option1

  • index=index: matches an option based on its index (offset from zero).

    index=2

Throws
MBTException

public void selectWindow (String windowName_p)

Since: API Level v2

selects a specified window as the current target window which all future commands to be directed to. Pass empty string for the window name to reset current target window to the main window.

You may also select window by window title (rel 4.0.8).

Example:

<action code="$selectWindow('mainWin')"/> 

Parameters
windowName_p name of the window, pass empty string for main window. You may pass in an integer (1-based) to select window by its index or regular expression with syntax /regExpr/ or use suffix/prefix "*" for startsWith and endsWith.
Throws
MBTException

public void sendKey (String locator_p, String keyString_p)

Since: API Level v2

type the string to the first element found with locator_p. The element must be an input field. It does not clear the content/value of the element if it's not empty.

Example:

<action code="$sendKey('id=F1','abc')"/>

Use the following tokens to simulate special keyboard key:

  • [KEYS.BACK_SPACE]
  • [KEYS.TAB]
  • [KEYS.CLEAR]
  • [KEYS.RETURN]
  • [KEYS.ENTER]
  • [KEYS.SHIFT]
  • [KEYS.LEFT_SHIFT]
  • [KEYS.CONTROL]
  • [KEYS.LEFT_CONTROL]
  • [KEYS.ALT]
  • [KEYS.LEFT_ALT]
  • [KEYS.PAUSE]
  • [KEYS.ESCAPE]
  • [KEYS.SPACE]
  • [KEYS.PAGE_UP]
  • [KEYS.PAGE_DOWN]
  • [KEYS.END]
  • [KEYS.HOME]
  • [KEYS.LEFT]
  • [KEYS.ARROW_LEFT]
  • [KEYS.UP]
  • [KEYS.ARROW_UP]
  • [KEYS.RIGHT]
  • [KEYS.ARROW_RIGHT]
  • [KEYS.NULL]
  • [KEYS.CANCEL]
  • [KEYS.HELP]
  • [KEYS.BACK_SPACE]
  • [KEYS.DOWN]
  • [KEYS.ARROW_DOWN]
  • [KEYS.INSERT]
  • [KEYS.DELETE]
  • [KEYS.SEMICOLON]
  • [KEYS.EQUALS]
  • [KEYS.NUMPAD0]
  • [KEYS.NUMPAD1]
  • [KEYS.NUMPAD2]
  • [KEYS.NUMPAD3]
  • [KEYS.NUMPAD4]
  • [KEYS.NUMPAD5]
  • [KEYS.NUMPAD6]
  • [KEYS.NUMPAD7]
  • [KEYS.NUMPAD8]
  • [KEYS.NUMPAD9]
  • [KEYS.MULTIPLY]
  • [KEYS.ADD]
  • [KEYS.SEPARATOR]
  • [KEYS.SUBTRACT]
  • [KEYS.DECIMAL]
  • [KEYS.DIVIDE]
  • [KEYS.F1]
  • [KEYS.F2]
  • [KEYS.F3]
  • [KEYS.F4]
  • [KEYS.F5]
  • [KEYS.F6]
  • [KEYS.F7]
  • [KEYS.F8]
  • [KEYS.F9]
  • [KEYS.F10]
  • [KEYS.F11]
  • [KEYS.F12]
  • [KEYS.META]
  • [KEYS.COMMAND]
  • [KEYS.ZENKAKU_HANKAKU]
Key token must be used alone or attached to the end of the string. For example, $sendKey('id=field1','[KEYS.ENTER]') or $sendKey('id=field1','abc[KEYS.TAB]')

Throws
MBTException
See Also
  • type(loc, keyString)

public void setCapabilityBoolean (String capKey_p, String capVal_p)

Since: API Level v2

public void setCapabilityInteger (String capKey_p, String capVal_p)

Since: API Level v2

public void setCapabilityList (String capKey_p, String capVal_p, String delChar_p)

Since: API Level v2

public void setCapabilityLong (String capKey_p, String capVal_p)

Since: API Level v2

public void setCapabilityString (String capKey_p, String capVal_p)

Since: API Level v2

sets a capability setting for the selected browser. Must supply the exact key and value in an appropriate format. This method is only valid in MBT_start trigger. Calling this method outside MBT_start trigger has no effect.

This method has variations for different data type. Choose the correct variation that is appropriate for the capability setting according to the browser's specific requirement.

For more information about capability setting supported by the specific browser, please visit WebDriver support page at: http://code.google.com/p/selenium/wiki

Optionally you can set capabilities by editing webdriver.properties in Config folder.

public void setCheckBox (String locator_p, String checked_p)

Since: API Level v2

sets the checkbox.

Example:

<action code="$setCheckBox('id=F1','true')"/> 

Parameters
locator_p locator to the checkbox element
checked_p true or false
Throws
MBTException

public void setImplicitWait (String millis_p)

Since: API Level v2

sets the implicitWait parameter for WebDriver. Implicit wait is the maximum amount of WebDriver will wait for the element to appear in the document. This setting applies to WebDriver directly and is used for all operations that require finding an element in the document.

You may need to use other wait method to supplement this global setting to meet specific needs in different part of the model.

Parameters
millis_p number of milliseconds

public void setRadioButton (String locator_p, String checked_p)

Since: API Level v2

sets the first radio button found with locator_p.

Example:

<action code="$setRadioButton('id=F1','true')"/> 

Parameters
locator_p locator to the radiobutton element
checked_p true or false
Throws
MBTException

public void setWindowMaximized ()

Since: API Level v2

maximizes the browser window.

Example:

$setWindowMaximized()

public void setWindowPosition (String left_p, String top_p)

Since: API Level v2

sets the window home position. Typically you would call this method in MBT_start trigger to position the browser at the desired position.

Example:

$setWindowPosition('100', '400')

public void setWindowSize (String width_p, String height_p)

Since: API Level v2

sets the browser window size to the specified dimension: width and height. Inavalid width or height value will default to 1000.

Example:

$setWindowSize('1000','2000')

public int sizeOf (String locator_p)

Since: API Level v2

returns the number options in the first select element found

Throws
MBTException

public String snapScreen (String fn_p)

Since: API Level v2

Take a snapshot of current AUT window.

Typical use of this method is to call it in or trigger to take a snapshot of the screen of the error.

The screen shot will be marked with the first exception (if multiple exceptions) triggered by current mScript and thus available from the exception popup.

Example:

<action code="$WinApp.snapScreen('myFileName')"/>

Returns
  • file path of the screen shot file
Throws
Exception

public void type (String locator_p, String shiftCtrlAlt_p, String keyString_p)

Since: API Level v2

type the string to the first element found with locator_p with the option to have shift/control/alt key pressed. It clears the current value before issuing typing the string into the field.

Not available for remote testing using selenium/appium/saucelabs servers.

Example:

<action code="$type('id=F1','S','abc')"/> 

Parameters
shiftCtrlAlt_p include char "c" for control key, "a" for alt key and "s" for shift key. For example "cs" to have control and shift keys pressed.
Throws
MBTException
MBTException
See Also
  • sendKey(loc, keystring)

public void type (String locator_p, String keyString_p)

Since: API Level v2

type the string to the first element found with locator_p. The element must be an input field. It clears the current value before issuing typing the string into the field.

Example:

<action code="$type('id=F1','abc')"/> 

Parameters
locator_p element locator
keyString_p string to be typed into the field. You may use key token as described in sendKey(loc, keyString) function to enter special keyboar key.
Throws
MBTException
See Also
  • sendKey(loc, keystring)

public void typeKeys (String locator_p, String keyString_p)

Since: API Level v2

type the string to the first element found with locator_p. The element must be an input field. It does not clear the content/value of the element if it's not empty. This is equivalent to sendKey().

Example:

<action code="$sendKey('id=F1','abc')"/> 

Throws
MBTException
See Also
  • sendKey(locator, keyString)
  • typeKey(locator, keyString)
  • type(locator, keyString)

public boolean waitForCondition (String locator_p, String condType_p, String condResult_p, String timeoutMillis_p)

Since: API Level v2

waits for a condition specified on the element up to the specified timeout in milliseconds. Returns true if the condition becomes true, false if it times out.

Parameters
condType_p text, visible, enabled or name of the attribute e.g. 'class', 'style', 'width', etc.
condResult_p expected state/value of the found element. e.g. for 'text' type, specify the expected string or regular expression, for 'visible' type, specify true or false, etc.
Returns
  • true if condition is found to be true within timeout duration, else return false.
Throws
MBTException

public boolean waitForElement (String locator_p, String timeoutMillis_p)

Since: API Level v2

waits for an element to be visible up to the specified timeout in milliseconds. Returns true if the element is found, false it times out.

Returns
  • true if element is found
Throws
MBTException

public boolean waitForWindow (String winName_p, String timeoutMillis_p)

Since: API Level v2

waits for a window to open/appear up to the specified timeout in milliseconds. Returns true if the window is found, false it times out waiting.

Parameters
winName_p name of the window or window handle (obtained with $getAllWindows()
Returns
  • true if element is found
Throws
MBTException

public boolean windowExists (String winNameTitle_p)

Since: API Level v2

returns true if the window with specified name/title is found. Else return false.

Parameters
winNameTitle_p name of the window, pass empty string for main window. You may pass in an integer (1-based) to select window by its index or regular expression with syntax /regExpr/ or use suffix/prefix "*" for startsWith and endsWith.