Navigator

Navigator object. This is used to provide functions for manipulating the web browser when using the HTML libraries.

Property Summary

Property Description
AutoOpen During playback when Rapise connects to a browser for the first time and can not locate an object and AutoOpen is 'true' it launches a new browser instance.
EnsureVisibleHorizontalAlignment One of "start", "center", "end", or "nearest".
EnsureVisibleVerticalAlignment One of "start", "center", "end", or "nearest".
QuitIfNotConnected If connection to browser fails - open plugin page and quit.

Action Summary

Action Description
CheckObjectExists Checks if object is found on the screen by its id or XPath.
Close Closes browser.
Detach Disconnects from a browser.
DoCheckAlert Waits until browser alert with a given text.
DoCheckConfirmation Waits until browser confirmation with a given text.
DoCheckPrompt Waits until browser prompt with a given text.
DOMFindByAttributeValue Looks for a web element by specific attribute value through all frames.
DOMFindByName Looks for a web element by its name through all frames.
DOMFindByText Looks for a web element by its text contents through all frames.
DOMFindByXPath Looks for a web element by specific local XPath value through all frames.
DoScreenshot Makes screenshot of the browser window.
DoSetExpectedConfirmResult Set boolean value to return as a result of next browser 'confirm' request.
DoSetExpectedPromptResult Set text to return as a result of next browser 'prompt' request.
ExecJS Executes given JavaScript statement in a browser and returns results.
Find Returns HTMLObject wrapping DOM element for a given 'xpath'.
GetPerformance Reads performance information from currently used browser.
GetPosition Gets position of the top-left corner of the browser window.
GetSize Gets size of the browser window.
Maximize Maximizes browser window.
Navigate Redirects browser to a specified URL.
Open Opens a browser.
SelectBrowserProfile Selects browser profile to use for testing.
SetPosition Positions top-left corner of the browser window at specifid location.
SetSize Sets size if the browser window.

Property Detail

AutoOpen

During playback when Rapise connects to a browser for the first time and can not locate an object and AutoOpen is 'true' it launches a new browser instance. If AutoOpen is 'false' it does nothing. Default value is 'true'. Applicable to Chrome, Firefox and Internet Explorer. Selenium targets are not affected by this property. Use Navigator.GetAutoOpen() to read the value and Navigator.SetAutoOpen(true|false) to set the value.

Type: boolean

EnsureVisibleHorizontalAlignment

One of "start", "center", "end", or "nearest". Defaults to "nearest".

Type: string

EnsureVisibleVerticalAlignment

One of "start", "center", "end", or "nearest". Defaults to "start".

Type: string

QuitIfNotConnected

If connection to browser fails - open plugin page and quit. If set to 'false' - just return 'false' in Open call.

Type: boolean

Action Detail

CheckObjectExists(xpathOrObjId)

Checks if object is found on the screen by its id or XPath.

Parameters:

Name Type Description
xpathOrObjId string XPath or ID. XPath is detected by leading "." or "/".

Returns:

'true' if browser alert had occurred, 'false' otherwise.

Close(url)

Closes browser. Finishes session.

Parameters:

Name Type Description
url string Not used - can leave empty

Detach()

Disconnects from a browser. Make Navigator ready for a new browser instance connection.

DoCheckAlert(msg)

Waits until browser alert with a given text. Wait timeout is 10 seconds.

Parameters:

Name Type Description
msg string alert text. Can be exact text or regular expression.

Returns:

'true' if browser alert had occurred, 'false' otherwise.

DoCheckConfirmation(msg, result)

Waits until browser confirmation with a given text. Wait timeout is 10 seconds.

Parameters:

Name Type Description
msg string confirmation text. Can be exact text or regular expression.
result string Not used - can leave empty.

Returns:

'true' if browser confirmation popup is shown, 'false' otherwise.

DoCheckPrompt(msg, result)

Waits until browser prompt with a given text. Wait timeout is 10 seconds.

Parameters:

Name Type Description
msg string prompt text. Can be exact text or regular expression.
result string Not used - can leave empty.

Returns:

'true' if browser prompt popup is shown, 'false' otherwise.

DOMFindByAttributeValue(attrName, attrValue, findAll, timeout, timeout)

Looks for a web element by specific attribute value through all frames. [attrValue] is checked agains each element's [attrName] attribute.

Parameters:

Name Type Description
attrName string name of the attribute to check. May be @attr or attr.
Optional.
attrValue string expected attribute value.
Optional.
findAll string optional, bool. Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout boolean , number. Timeout in milliseconds to keep trying to find an element. Default behavior is just do single attempt.
Optional.
timeout number

Returns:

array |
object: If [findAll] is set to false then just first found element or null is returned. Else search is done for all matching elements and array is returned (empty array if nothing found).

DOMFindByName(name, tagName, findAll, timeout)

Looks for a web element by its name through all frames. Name is checked agains @name and @id attribute of each element

Parameters:

Name Type Description
name string expected element name to search for
Optional.
tagName Sring optional tag name, default is * (any tag)
Optional.
findAll boolean optional, bool. Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout number , number. Timeout in milliseconds to keep trying to find an element. Default behavior is just do single attempt.
Optional.

Returns:

array |
object: If [findAll] is set to false then just first found element or null is returned. Else search is done for all matching elements and array is returned (empty array if nothing found).

DOMFindByText(text, tagName, findAll, timeout)

Looks for a web element by its text contents through all frames. [text] is checked agains each element text contents.

Parameters:

Name Type Description
text string expected text to search for
Optional.
tagName string optional tag name, default is * (any tag)
Optional.
findAll boolean optional, bool. Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout number , number. Timeout in milliseconds to keep trying to find an element. Default behavior is just do single attempt.
Optional.

Returns:

array |
object: If [findAll] is set to false then just first found element or null is returned. Else search is done for all matching elements and array is returned (empty array if nothing found).

DOMFindByXPath(xpath, findAll, timeout)

Looks for a web element by specific local XPath value through all frames. If XPath is local (i.e. //img) then search will be performed for all images in all nested frames.

Parameters:

Name Type Description
xpath string local XPath to execute for each frame.
Optional.
findAll boolean optional, bool. Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout number , number. Timeout in milliseconds to keep trying to find an element. Default behavior is just do single attempt.
Optional.

Returns:

array |
object: If [findAll] is set to false then just first found element or null is returned. Else search is done for all matching elements and array is returned (empty array if nothing found).

DoScreenshot(fileName)

Makes screenshot of the browser window.

Parameters:

Name Type Description
fileName string Save the screenshot to a file if name is specified. Otherwise - add to report.
Optional.

DoSetExpectedConfirmResult(expectedRes)

Set boolean value to return as a result of next browser 'confirm' request.

Parameters:

Name Type Description
expectedRes string The text to be returned in the next request.

DoSetExpectedPromptResult(expectedRes)

Set text to return as a result of next browser 'prompt' request.

Parameters:

Name Type Description
expectedRes string The text to be returned in the next request.

ExecJS(scriptText, obj)

Executes given JavaScript statement in a browser and returns results.

Parameters:

Name Type Description
scriptText string JavaScript code.
obj SeSObject

Returns:

Find(xpath, url, title, objInfo)

Returns HTMLObject wrapping DOM element for a given 'xpath'. HTMLObject is a {SeSObject} constructed by matching one of browser rules: IEHTMLObject, MozillaHTMLObject, etc.

Parameters:

Name Type Description
xpath string location path of a DOM element.
url string URL. If new navigator is launched, the URL is used.
Optional.
title string The title of the HTML document that is being searched.
objInfo SeSObjectInfo A populated SeSObjectInfo object.

Returns:

HTMLObject wrapping DOM element for a given 'xpath', 'null' if 'xpath' is invalid.

GetPerformance(resources, dontWriteReport)

Reads performance information from currently used browser. Performance numbers are based on output from window.performance structure of the web page. See also http://www.w3.org/TR/navigation-timing/#processing-model

Parameters:

Name Type Description
resources boolean optional, bool. Set to true if you want to dump information about resource timing into the report
Optional.
dontWriteReport boolean optional, Set to true if you want just return page load time and write nothing to report
Optional.

Returns:

number: page open time (in milliseconds)

GetPosition()

Gets position of the top-left corner of the browser window. This function is DPI aware.

Returns:

object: {X, Y}

GetSize()

Gets size of the browser window. This function is DPI aware.

Returns:

object: {Width, Height}

Maximize()

Maximizes browser window.

Redirects browser to a specified URL.

Parameters:

Name Type Description
url string The URL to navigate to.

Open(url)

Opens a browser. If URL is specified, goes to URL.

Parameters:

Name Type Description
url string start URL for opening browser. Can be 'null'.

SelectBrowserProfile(profileName)

Selects browser profile to use for testing.

Parameters:

Name Type Description
profileName string name of a browser profile.

SetPosition(x, y)

Positions top-left corner of the browser window at specifid location. This function is DPI aware.

Parameters:

Name Type Description
x number X-offset from the top-left corner of the screen.
y number Y-offset from the top-left corner of the screen.

SetSize(width, height)

Sets size if the browser window. This function is DPI aware.

Parameters:

Name Type Description
width number New width of the browser window.
height number New height of the browser window.