Skip to content

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".
EnsureVisibleScrollBehavior One of default scroll behaviors: "auto", "smooth" or "instant".
EnsureVisibleVerticalAlignment One of "start", "center", "end", or "nearest".
NativeEvents Set it to true to use native keyboard and mouse input.
QuitIfNotConnected If connection to browser fails - open plugin page and quit.

Action Summary

Action Description
Back Goes back to the previous page in the browser history.
CheckObjectActive Checks if object is active by its id or XPath.
CheckObjectEnabled Checks if object is enabled by its id or XPath.
CheckObjectExists Checks if object is found on the screen by its id or XPath.
CheckObjectVisible Checks if object is visible on the screen by its id or XPath.
Close Closes browser.
Detach Disconnects from a browser.
DoActivateWindow Makes specified browser window active and focused.
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.
DoClickUntilOnScreen Clicks on a given element until another element appears on screen.
DoClickWhileOnScreen Clicks on an element until it disappears.
DoCloseTab Closes currently selected tab.
DoCloseWindow Closes currently active browser window.
DoCreateTab Creates new browser tab.
DoCreateWindow Creates a new browser window.
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.
DoMoveWindow Sets the position of the active browser window.
DOMQueryValue Executes an xpath query that may return a value of string, number or boolean type.
DoResizeWindow Sets size of the active browser window.
DoScreenshot Makes screenshot of the browser window.
DoSelectTab Selects browser tab by title or URL.
DoSendKeys Sends keys to an active element on a page.
DoSetExpectedConfirmResult Sets boolean value to return as a result of next browser confirm request.
DoSetExpectedPromptResult Sets text to return as a result of next browser prompt request.
DoWaitFor Waits for object to appear in the current browser.
DoWaitForEnabled Waits for object to become enabled.
DoWaitForVisible Waits for object to appear in the screen.
ExecJS Executes given JavaScript statement in a browser and returns results.
ExecPageJS Executes given JavaScript statement in a browser in the context of the current page.
Find Returns HTMLObject wrapping DOM element for a given xpath.
Forward Goes forward to the next page in the browser history.
GetActiveTabId Gets Id of active browser tab.
GetActiveTabTitle Gets title of active browser tab.
GetActiveTabUrl Gets URL of active browser tab.
GetActiveWindowId Gets active browser window Id.
GetActiveWindowTitle Gets active browser window title.
GetActiveWindowUrl Gets active browser window URL.
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.
GetTabIdAt Gets browser tab Id.
GetTabIndexById Gets index of the browser tab by Id.
GetTabsCount Gets number of browser tabs.
GetTabTitleAt Gets browser tab title.
GetTabUrlAt Gets browser tab URL.
GetWindowIdAt Gets browser window Id.
GetWindowsCount Gets the number of browser windows.
GetWindowTitleAt Gets browser window title.
GetWindowUrlAt Gets browser window URL.
KillBrowser Kills the browser process.
LaunchBrowser Launches browser, but does not connect to it.
Maximize Maximizes browser window.
Navigate Redirects browser to a specified URL.
Open Opens a browser.
Refresh Reloads the current page.
SelectBrowserProfile Selects browser profile to use for testing.
SeSFind Waits for object to appear on screen.
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

EnsureVisibleScrollBehavior

One of default scroll behaviors: "auto", "smooth" or "instant". Defaults ot "instant".

Type: string

EnsureVisibleVerticalAlignment

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

Type: string

NativeEvents

Set it to true to use native keyboard and mouse input. Overrides browser profile settings. Does not affect Selenium targets. Requires Rapise 6.3+

Type: boolean

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

Back

Goes back to the previous page in the browser history. Requires Rapise 8.0+.

Navigator.Back()

CheckObjectActive

Checks if object is active by its id or XPath.

Navigator.CheckObjectActive(xpathOrObjId)

Parameters:

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

Returns:

true if object is active, false otherwise.

CheckObjectEnabled

Checks if object is enabled by its id or XPath.

Navigator.CheckObjectEnabled(xpathOrObjId)

Parameters:

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

Returns:

true if object is available and enabled, false otherwise.

CheckObjectExists

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

Navigator.CheckObjectExists(xpathOrObjId)

Parameters:

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

Returns:

true if object exists, false otherwise.

CheckObjectVisible

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

Navigator.CheckObjectVisible(xpathOrObjId)

Parameters:

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

Returns:

true if object is available and visible, false otherwise.

Close

Closes browser. Finishes session.

Navigator.Close(url)

Parameters:

Name Type Description
url string Not used - can leave empty.
Returns true if the browser closed successfully, otherwise - false.

Detach

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

Navigator.Detach()

DoActivateWindow

Makes specified browser window active and focused. Requires Rapise 6.5+

Navigator.DoActivateWindow(titleOrUrl)

Parameters:

Name Type Description
titleOrUrl string string or regex matching URL or window title.

DoCheckAlert

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

Navigator.DoCheckAlert(msg)

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

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

Navigator.DoCheckConfirmation(msg, result)

Parameters:

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

Returns:

true if browser confirmation popup is shown, false otherwise.

DoCheckPrompt

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

Navigator.DoCheckPrompt(msg, result)

Parameters:

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

Returns:

true if browser prompt popup is shown, false otherwise.

DoClickUntilOnScreen

Clicks on a given element until another element appears on screen. Requires Rapise 6.3+

Navigator.DoClickUntilOnScreen(xpathOrObjIdToClick, xpathOrObjIdToExpect, attempts, delay, x, y, forceEvent)

Parameters:

Name Type Description
xpathOrObjIdToClick objectId Object Id or XPath of an element to click.
xpathOrObjIdToExpect objectId Object Id or XPath of an element that should appear on screen.
attempts number Max number of clicks. Default is 2.
Optional.
delay number Delay between attempts. Default is 1000 milliseconds.
Optional.
x number X-offset from the top-left corner of the object. Default is object width/2.
Optional.
y number Y-offset from the top-left corner of the object. Default is object height/2.
Optional.
forceEvent boolean Default is false. Set to true to use browser level event for the click. Overrides browser profile settings.
Optional.

Returns:

expected object if successful, otherwise - null.

DoClickWhileOnScreen

Clicks on an element until it disappears. Requires Rapise 6.3+

Navigator.DoClickWhileOnScreen(xpathOrObjId, attempts, delay, x, y, forceEvent)

Parameters:

Name Type Description
xpathOrObjId objectid Object Id or XPath of an element to click.
attempts number Max number of clicks. Default is 2.
Optional.
delay number Delay between attempts. Default is 1000 milliseconds.
Optional.
x number X-offset from the top-left corner of the object. Default is object width/2.
Optional.
y number Y-offset from the top-left corner of the object. Default is object height/2.
Optional.
forceEvent boolean Default is false. Set to true to use browser level event for the click. Overrides browser profile settings.
Optional.

Returns:

true if object disappeared, otherwise - false.

DoCloseTab

Closes currently selected tab. Requires Rapise 6.5+

Navigator.DoCloseTab()

DoCloseWindow

Closes currently active browser window. Requires Rapise 6.5+

Navigator.DoCloseWindow()

DoCreateTab

Creates new browser tab. Requires Rapise 6.5+

Navigator.DoCreateTab(url)

Parameters:

Name Type Description
url string new page URL

DoCreateWindow

Creates a new browser window. Requires Rapise 6.5+

Navigator.DoCreateWindow(url)

Parameters:

Name Type Description
url string page URL.

DOMFindByAttributeValue

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

Navigator.DOMFindByAttributeValue(attrName, attrValue, tagName, findAll, timeout)

Parameters:

Name Type Description
attrName string Name of the attribute to check. May be @attr or attr.
attrValue string Expected attribute value.
tagName string Tag name, default is * (any tag).
Optional.
findAll boolean Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout 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 of elements is returned (empty array if nothing found).

DOMFindByName

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

Navigator.DOMFindByName(name, tagName, findAll, timeout)

Parameters:

Name Type Description
name string Expected element name to search for.
tagName string Tag name, default is * (any tag).
Optional.
findAll boolean Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout 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 of elements is returned (empty array if nothing found).

DOMFindByText

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

Navigator.DOMFindByText(text, tagName, findAll, timeout)

Parameters:

Name Type Description
text string Expected text to search for.
tagName string Tag name, default is * (any tag).
Optional.
findAll boolean Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout 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 of elements is returned (empty array if nothing found).

DOMFindByXPath

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.

Navigator.DOMFindByXPath(xpath, findAll, timeout)

Parameters:

Name Type Description
xpath string Local XPath to execute for each frame.
findAll boolean Defines if we return just first element (false, default) or all found elements (true). Default is false.
Optional.
timeout 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 of elements is returned (empty array if nothing found).

DoMoveWindow

Sets the position of the active browser window. Requires Rapise 6.5+

Navigator.DoMoveWindow(left, top)

Parameters:

Name Type Description
left number offset in pixels from the corner of the display.
top number offset in pixels from the corner of the display.

DOMQueryValue

Executes an xpath query that may return a value of string, number or boolean type. If the result of the query is an array of nodes - a combined string is returned (;-separated text values of nodes). If the query returns nothing (invalid query or nothing matches) then null is returned. Requires Rapise 6.4+

Navigator.DOMQueryValue(xpathOrObjId, query)

Parameters:

Name Type Description
xpathOrObjId objectId XPath or ID. XPath is detected by leading '.' or '/'. If the value is empty then this parameter defaults to /html.
query string Absolute or relative xpath query. e.g. count(//div), //a[1]/@href='/Home', ./li/text()

Returns:

string |
number |
boolean: Result of the query or null in the case if the query is invalid or nothing matches.

DoResizeWindow

Sets size of the active browser window. Requires Rapise 6.5+

Navigator.DoResizeWindow(width, height)

Parameters:

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

DoScreenshot

Makes screenshot of the browser window.

Navigator.DoScreenshot(fileName)

Parameters:

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

DoSelectTab

Selects browser tab by title or URL. Requires Rapise 6.5+

Navigator.DoSelectTab(titleOrUrl)

Parameters:

Name Type Description
titleOrUrl string string or regex matching tab URL or title.

DoSendKeys

Sends keys to an active element on a page. Requires Rapise 8.0+.

Navigator.DoSendKeys(txt)

Parameters:

Name Type Description
txt string Keys to send. Supports patterns like in Global.DoSendKeys.

DoSetExpectedConfirmResult

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

Navigator.DoSetExpectedConfirmResult(expectedRes)

Parameters:

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

DoSetExpectedPromptResult

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

Navigator.DoSetExpectedPromptResult(expectedRes)

Parameters:

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

DoWaitFor

Waits for object to appear in the current browser. Object may be hidden or disabled. Requires Rapise 6.3+

Navigator.DoWaitFor(xpathOrObjId, timeout, params)

Parameters:

Name Type Description
xpathOrObjId objectid Object Id or XPath of an element to check.
timeout number Max time to wait. Default is 10000 milliseconds.
Optional.
params object Overrides locator options.
Optional.

Returns:

found object, otherwise - false.

DoWaitForEnabled

Waits for object to become enabled. Requires Rapise 7.4+

Navigator.DoWaitForEnabled(xpathOrObjId, timeout, params)

Parameters:

Name Type Description
xpathOrObjId objectid Object Id or XPath of an element to check.
timeout number Max time to wait. Default is 10000 milliseconds.
Optional.
params object Overrides locator options.
Optional.

Returns:

found object, otherwise - false.

DoWaitForVisible

Waits for object to appear in the screen. Requires Rapise 7.4+

Navigator.DoWaitForVisible(xpathOrObjId, timeout, params)

Parameters:

Name Type Description
xpathOrObjId objectid Object Id or XPath of an element to check.
timeout number Max time to wait. Default is 10000 milliseconds.
Optional.
params object Overrides locator options.
Optional.

Returns:

found object, otherwise - false.

ExecJS

Executes given JavaScript statement in a browser and returns results.

Navigator.ExecJS(scriptText, obj)

Parameters:

Name Type Description
scriptText string JavaScript code.
obj HTMLObject You may pass object to use in the JavaScript statement. Reference it as el or arguments[0].
Optional.

Returns:

Result of code execution.

ExecPageJS

Executes given JavaScript statement in a browser in the context of the current page. It means the script may access JS variables and functions declared on the page. Requires Rapise 6.5+

Navigator.ExecPageJS(scriptText, obj)

Parameters:

Name Type Description
scriptText string JavaScript code.
obj HTMLObject You may pass object to use in the JavaScript statement. The script will be executed in a frame, containing given obj.
Optional.

Returns:

Result of code execution.

Find

Returns HTMLObject wrapping DOM element for a given xpath.

Navigator.Find(xpath, url, title, objInfo)

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.

Forward

Goes forward to the next page in the browser history. Requires Rapise 8.0+.

Navigator.Forward()

GetActiveTabId

Gets Id of active browser tab. Id may be used as parameter to Navigator.DoSelectTab(). Requires Rapise 6.5+

Navigator.GetActiveTabId()

GetActiveTabTitle

Gets title of active browser tab. Requires Rapise 6.5+

Navigator.GetActiveTabTitle()

GetActiveTabUrl

Gets URL of active browser tab. Requires Rapise 6.5+

Navigator.GetActiveTabUrl()

GetActiveWindowId

Gets active browser window Id. Id is an internal identifier. May be used as a parameter to Navigator.DoActivateWindow(). Requires Rapise 6.5+

Navigator.GetActiveWindowId()

GetActiveWindowTitle

Gets active browser window title. Requires Rapise 6.5+

Navigator.GetActiveWindowTitle()

GetActiveWindowUrl

Gets active browser window URL. Requires Rapise 6.5+

Navigator.GetActiveWindowUrl(index)

Parameters:

Name Type Description
index number

GetPerformance

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

Navigator.GetPerformance(resources, dontWriteReport)

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.

Navigator.GetPosition()

Returns:

object: {X, Y}

GetSize

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

Navigator.GetSize()

Returns:

object: {Width, Height}

GetTabIdAt

Gets browser tab Id. Id may be used as parameter to Navigator.DoSelectTab(). Requires Rapise 6.5+

Navigator.GetTabIdAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetTabsCount()

GetTabIndexById

Gets index of the browser tab by Id. Index may be used as param to GetTabIdAt/GetTabUrlAt/GetTabTitleAt. Requires Rapise 6.5+

Navigator.GetTabIndexById(tabId)

Parameters:

Name Type Description
tabId number

GetTabsCount

Gets number of browser tabs. Requires Rapise 6.5+

Navigator.GetTabsCount()

GetTabTitleAt

Gets browser tab title. Requires Rapise 6.5+

Navigator.GetTabTitleAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetTabsCount()

GetTabUrlAt

Gets browser tab URL. Requires Rapise 6.5+

Navigator.GetTabUrlAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetTabsCount()

GetWindowIdAt

Gets browser window Id. Id is an internal identifier. May be used as a parameter to Navigator.DoActivateWindow(). Requires Rapise 6.5+

Navigator.GetWindowIdAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetWindowsCount()

GetWindowsCount

Gets the number of browser windows. Requires Rapise 6.5+

Navigator.GetWindowsCount()

GetWindowTitleAt

Gets browser window title. Requires Rapise 6.5+

Navigator.GetWindowTitleAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetWindowsCount()

GetWindowUrlAt

Gets browser window URL. Requires Rapise 6.5+

Navigator.GetWindowUrlAt(index)

Parameters:

Name Type Description
index number number from 0 to Navigator.GetWindowsCount()

KillBrowser

Kills the browser process. The browser to kill is detected from browser profile settings. Requires Rapise 6.4+

Navigator.KillBrowser()

LaunchBrowser

Launches browser, but does not connect to it. Recommended for applications with basic authentication. Requires Rapise 6.5+

Navigator.LaunchBrowser(url)

Parameters:

Name Type Description
url Initial url, may be empty.
Optional.

Maximize

Maximizes browser window.

Navigator.Maximize()

Redirects browser to a specified URL.

Navigator.Navigate(url)

Parameters:

Name Type Description
url string The URL to navigate to.

Open

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

Navigator.Open(url)

Parameters:

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

Refresh

Reloads the current page. Requires Rapise 8.0+.

Navigator.Refresh()

SelectBrowserProfile

Selects browser profile to use for testing.

Navigator.SelectBrowserProfile(profileName)

Parameters:

Name Type Description
profileName string name of a browser profile.

SeSFind

Waits for object to appear on screen. Uses test ObjectLookup... settings. Requires Rapise 6.4+

Navigator.SeSFind(xpathOrObjId, params)

Parameters:

Name Type Description
xpathOrObjId objectid Object Id or XPath of an element to check.
params object Overrides locator options.
Optional.

Returns:

found object, otherwise - false.

SetPosition

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

Navigator.SetPosition(x, y)

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

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

Navigator.SetSize(width, height)

Parameters:

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