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 "center".

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(result)

Parameters:

Name	Type	Description
result	boolean	Confirmation result, `true` or `false`.

DoSetExpectedPromptResult¶

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

Navigator.DoSetExpectedPromptResult(result)

Parameters:

Name	Type	Description
result	string \| object	Expected prompt result.

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()

Navigate¶

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.