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".
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
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.
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.
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.
DOMQueryValue Executes an xpath query that may return a value of string, number or boolean type.
DoScreenshot Makes screenshot of the browser window.
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 on screen.
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.
KillBrowser Kills the browser process.
Maximize Maximizes browser window.
Navigate Redirects browser to a specified URL.
Open Opens a browser.
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

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

CheckObjectExists(xpathOrObjId)

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

Parameters:

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

Returns:

true if object exists, false otherwise.

CheckObjectVisible(xpathOrObjId)

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

Parameters:

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

Returns:

true if object is visible, 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.
Optional.

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.
Optional.

Returns:

true if browser prompt popup is shown, false otherwise.

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

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

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 successfull, otherwise - null.

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

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

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.

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

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

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

DOMQueryValue(xpathOrObjId, query)

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+

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.

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)

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

Sets 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.

DoWaitFor(xpathOrObjId, timeout, params)

Waits for object to appear on screen. Requires Rapise 6.3+

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(scriptText, obj)

Executes given JavaScript statement in a browser and returns results.

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.

Find(xpath, url, title, objInfo)

Returns HTMLObject wrapping DOM element for a given xpath.

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}

KillBrowser()

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

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.

SeSFind(xpathOrObjId, params)

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

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