UI Steps Built-ins ¶

There are three types of UI Steps Built-ins: Generic, Cookies Built-ins and Page Built-ins.

UI Steps Built-ins
Generic UI Steps Built-ins
Get Browser Name
Get Session Name
Take Screenshot
Switch To Window
Page Built-ins
Close Windows
Go Back
Refresh Page
Inject JS
Manage Browser Window Properties
Maximize Browser Window
Set Browser Window Size
Get Browser Window Size
Set Browser Window Position
Get Browser Window Position
Get Source
Get Text
Cookies Built-ins
Get Cookies
Get Cookie (Named)
Delete All Cookies
Delete All Cookies (Named)
Add Cookie
Appium Built-ins
Switch Context

Generic UI Steps Built-ins ¶

Generic UI Steps Built-ins provide functionality for interacting with web sessions. They are not enclosed in any named model and therefore do not require a prefix.

Get Browser Name ¶

Syntax

1	getBrowserName()

Example

model aModel
  func retrieveBrowserName()
    return getBrowserName()
  end
end

Get Session Name ¶

This Built-in returns the device's session name if it is a device session. Otherwise it returns the name of the browser session.

Syntax

1	getSessionName()

Example

1
2
3

stepdef "what session is this?"
    println("this session is " + getSessionName())
end

Feature File Example

1
2
3

Given an Android phone as A
...
And on A, what session is this?

The result will be printed as:

1	this session is A

Note: If using an Android phone, an App must be opened before getSessionName() can be used. Otherwise, the function will fail. This will result in its associated step also failing.

Take Screenshot ¶

This Built-in takes screenshots of a browser during a UI Steps, which will be saved into the test case's reports folder.

Syntax

1	takeScreenshot(<name String>)

Parameter

name - The name assigned to the screenshot

Example

1	takeScreenshot("someScreenshot")

Switch To Window ¶

There are two functions to switch to another open window, depending on whether the windows have a name or not.

Syntax

// Switch to a named window.
switchToWindow(<name String>)
// Switch to an unnamed window.
switchToWindowIndex(<index Number>)

Parameters

name - The window's name
index - The window's number
- The index starts at 1, which refers to the window from which additional links were opened
- All further windows are numbered in the order they were opened

Example

stepdef "window test"
    v := open WindowOpener
    v.newWin0()
    v.newWin1()
    v.newWin2()
    v.newWin3()
    v.newWin4()

    switchToWindow("newwin")
    switchToWindowIndex(6)
    await Window4
  end

view WindowOpener
    url "file:///Users/yourPath/uisteps/webWindow/README"

    elem newWin0    := "id('new_window_link0')"
    elem newWin1    := "id('new_window_link1')"
    elem newWin2    := "id('new_window_link2')"
    elem newWin3    := "id('new_window_link3')"
    elem newWin4    := "id('new_window_link4')"

    action (newWin0)    newWin0     := click
    action (newWin1)    newWin1     := click
    action (newWin2)    newWin2     := click
    action (newWin3)    newWin3     := click
    action (newWin4)    newWin4     := click
end

view Window3
    elem dd := "id('d3')"
end
view Window4
    elem dd := "id('d4')"
end

Page Built-ins ¶

The Page Built-ins provide functionality for the accessed webpage.

Close Windows ¶

Closes the accessed page.

Syntax

1	Page.close()

Go Back ¶

Goes back to the previous page.

Syntax

1	Page.goBack()

Refresh Page ¶

Refreshes the current page.

Syntax

1	Page.refresh()

Inject JS ¶

Occasionally, the page rendered in a browser needs to be modified slightly. The Inject JS Built-in performs the required modification.

Syntax

1	Page.injectJS(<jsCode String>)

Parameter

jsCode - The JavaScript code to be injected

Example

1	Page.injectJS("alert('Hello world!');")

Manage Browser Window Properties ¶

The following browser window properties may be managed:

Maximize browser window
Set and get the window size
Set and get the window position

Maximize Browser Window ¶

Maximizes the browser window.

Syntax

1	Page.maximizeWindow()

Set Browser Window Size ¶

Sets the size of the browser window in pixels.

Syntax

1	Page.setWindowSize(<width Number>, <height Number>)

Parameters

width - The width of the browser window in pixels
height - The height of the browser window in pixels

Example

1	Page.setWindowSize(1024, 768)

Get Browser Window Size ¶

Retrieves the window size in pixels. getWindowSize(). After, getWidth() or getHeight() may be called.

Syntax

1	<windowSize Dimension> := Page.getWindowSize()

Returns
The window size represented as an instance of Dimension type.

Example

stepdef "get window size"
  size := Page.getWindowSize()
  size.getWidth()
  size.getHeight()
  println(size.toString())
  println(size.getWidth().toString())
  println(size.getHeight().toString())
end

Get Browser Window Width¶

Retrieves the window's width in pixels. It must be called on a Dimension type instance created in getWindowSize().

Syntax

1	<width Number> := <windowSize Dimension>.getWidth()

Returns
The window's width.

Parameter

windowSize - The window size object created by Page.getWindowSize()

Example

1 2	size := Page.getWindowSize() size.getWidth()

Get Browser Window Height¶

Retrieves the window's height in pixels. It must be called on a Dimension type instance created in getWindowSize().

Syntax

1	<height Number> := <windowSize Dimension>.getHeight()

Returns
The window's height.

Parameter

windowSize - The window size object created by Page.getWindowSize()

Example

1 2	size := Page.getWindowSize() size.getHeight()

Set Browser Window Position ¶

Sets this browser position by specifying the x-axis (horizontal) and y-axis (vertical).

Syntax

1	Page.setWindowPosition(<x Number>, <y Number>)

Parameters

x - x-axis position of the browser window's left upper corner
y - y-axis position of the browser window's left upper corner

Example

1	Page.setWindowPosition(10, 10)

Get Browser Window Position ¶

Retrieves the window position in pixels. After, getX() or getY() may be called.

Syntax

1	<windowPosition Point> := Page.getWindowPosition()

Returns

The browser window's position.

Example

stepdef "get window position"
  position := Page.getWindowPosition()
  position.getX()
  position.getY()
  println(position.toString())
  println(position.getY().toString())
  println(position.getX().toString())
end

Get Browser Window X-Axis¶

Retrieves the X-axis position from the browser window's left upper corner. Page.getWindowPosition() must first be defined.

Syntax

1	<xAxis Number> := <windowPosition Point>.getX()

Returns
The X-axis position.

Parameter

windowPosition - The window position object created by Page.getWindowPosition

Example

1 2	position := Page.getWindowPosition() position.getX()

Get Browser Window X-Axis¶

Retrieves the Y-axis position from the browser window's left upper corner. Page.getWindowPosition() must first be defined.

Syntax

1	<yAxis Number> := <windowPosition Point>.getY()

Returns
The Y-axis position.

Parameter

windowPosition - The window position object created by Page.getWindowPosition

Example

1 2	position := Page.getWindowPosition() position.getY()

Get Source ¶

Returns the page source code as a string.

Syntax

1	<sourceString String> := Page.getSource()

Returns

The source code text of the page as a string.

Example

stepdef "download source text"
    text := Page.getSource()
    setContextObject("sourceText", text)
    println(text)
end

Get Text ¶

Returns the page text as a string. This includes any returned characters and may possibly include plain text preceding a file, for instance, XML.

Syntax

1	<textString String> := Page.getText()

Returns

The text of the page as a string.

Download Page Text Example

stepdef "download page text"
    text := Page.getText()
    setContextObject("pageText", text)
    println(text)
end

Parse Result as a Specific File Type Example

To parse the result as a specific file type, for instance, XML, the result must be processed before being fed to the respective parser.

stepdef "download page text and trim characters before opening bracket"
  text := Page.getText().replace("This XML file does not appear to have any style information associated with it. The document tree is shown below.", "")
  setContextObject("text", text)
  println(text)
  xmlResult := Xml.evaluateXpathToString("//*[xpath-example()='params']", text)
  ...
end

The example above processes the result so that text preceding the first occurrence of an opening angle bracket (<) is omitted.

Cookies Built-ins ¶

The following Built-ins are used for managing cookies in using UI Steps. Each use the Cookies. prefix.

Get Cookies ¶

Gets all the cookies for the current domain.

Syntax

1	Cookies.getCookies()

Gets a cookie with a given name.

Syntax

1	Cookies.getCookieNamed(<cookieName String>)

Parameter

cookieName - The name of the cookie

Example

1 2	myCookie := Cookies.getCookieNamed("test") myCookie.getValue()

In the example above, after getting a cookie named "test", its value is retrieved using the getValue() function.

Delete All Cookies ¶

Deletes all the cookies for the current domain.

Syntax

1	Cookies.deleteAllCookies()

Delete All Cookies (Named) ¶

Deletes the named cookie from the current domain. This is equivalent to setting the named cookie's expiry date to some time in the past.

Syntax

1	Cookies.deleteAllCookiesNamed(<cookieName String>)

Parameter

cookieName - The name of the cookie

Example

1	Cookies.deleteAllCookiesNamed("mycookies")

Adds a specific cookie. A cookie name and value must be specified, while additional parameters can be added.

Syntax

1 2	Cookies.addCookie(<cookieName String>, <value String>, <path String>, <domain String>, <dateExpiry Date>, <isSecure Boolean>)

Parameters

cookieName - The name of the cookie
value - The cookie's value
path (optional) - The URL/path on the domain for which the cookie is valid
- The cookie is only valid for pages that reside within the given path
- For example, http://example.com/accounts
- If unspecified, /
domain (optional) - The top-level domain and its subdomains that the cookie is valid for
- For example, http://example.com
- If unspecified, the domain will be set to the sever's hostname
dateExpiry (optional ) - The cookie's expiration date, which means when the browser deletes the cookie
isSecure (optional) - Defines whether the cookie requires a secure connection or not
- May be one of true or false

Note: addCookie uses a fixed parameter order. For example, if specifying a dateExpiry parameter, this must follow the cookieName value, path and domain parameters, which all must be defined.

Example

1
2
3

Cookies.addCookie("myCookie", "sessionID123", "http://example.com")

Cookies.addCookie("mySecondCookie", "sessionID100s", "http://example.com", "", "", date("2017-02-24 09:00:00.000"))

Appium Built-ins ¶

The following Built-ins are used specifically for phones using the Appium automation tool. The Appium Configuration must be active.

Switch Context¶

This Built-in allows for switching contexts on hybrid Android apps. For example, using an app that switches from an app View to a webview. The function will fail if the current driver is not Appium. For Selenium/Selendroid, use Switch To Window.

Syntax

1	switchContext(<name String>)

Parameter

name - The name of the context to switch to

Example

1	switchContext("NATIVE_APP")

UI Steps Built-ins ¶

Generic UI Steps Built-ins ¶

Get Browser Name ¶

Get Session Name ¶

Take Screenshot ¶

Switch To Window ¶

Page Built-ins ¶

Close Windows ¶

Go Back ¶

Refresh Page ¶

Inject JS ¶

Manage Browser Window Properties ¶

Maximize Browser Window ¶

Set Browser Window Size ¶

Get Browser Window Size ¶

Get Browser Window Width¶

Get Browser Window Height¶

Set Browser Window Position ¶

Get Browser Window Position ¶

Get Browser Window X-Axis¶

Get Browser Window X-Axis¶

Get Source ¶

Get Text ¶

Cookies Built-ins ¶

Get Cookies ¶

Get Cookie (Named) ¶

Delete All Cookies ¶

Delete All Cookies (Named) ¶

Add Cookie ¶

Appium Built-ins ¶

Switch Context¶