Skip to content
QiTASC.com / UI Steps Language /
UI Steps Built-ins
/ .. /
UI Steps Built-ins





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

1
2
3
4
5
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

1
2
3
4
// 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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

1
2
3
4
5
6
7
8
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

1
2
3
4
5
6
7
8
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

1
2
3
4
5
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

1
2
3
4
5
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.

1
2
3
4
5
6
7
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")