The Selenium Library
The Selenium library is used for browser automation. It is uses the Selenium project to perform the automation. For this automation to work, it is required to have a running Selenium Grid/Server available.
This library is build around a "Session" concept. Client code first initializes a Selenium session, and then interacts with it.
// @provengo summon selenium (1)
const session = new SeleniumSession("dave"); (2)
session.start("https://test.hal.com"); (3)
session.click("//a[contains(text(),'Sign In')]"); (4)
session.writeText("//input[@id='username']", "dave"); (5)
session.writeText("//input[@id='password']", "dave-pass");
session.click("//button[@id='Open pod bay doors']")
session.waitForVisibility("//div[contains(text(),'I am sorry, Dave')]"); (6)
session.close(); (7)| 1 | Bring in the Selenium library into scope. |
| 2 | Starts a new session (no browser window opened yet). |
| 3 | Opens a browser window at the passed URL. |
| 4 | Clicks an <a> element whose text is "Sign In". |
| 5 | writes dave in the username input. |
| 6 | Waits for a div with the text "I am sorry, Dave" to appear. |
| 7 | Closes the browser window. |
|
Dry Runs
To turn off Selenium actuations for a run, use the provengo run --dry PATH_TO_PROJECT`. Or, set the The provengo tool will not execute the instructions using Selenium. Instead, it will print them to the console. |
Classes and Methods
SeleniumSession(sessionName, browserType)
Constructs a new SeleniumSession in browserType. Both parameters are optional.
browserType must be one of the following: chrome, firefox, edge, safari. If not specified, browserType defaults to the browser defined by the --selenium-browser parameter (chrome if not specified).
| Different sessions must have different names. Sessions with the same name will be considered identical. |
Safari browsers do not support headless mode - they must run with a visible window. Thus, when using a Safari browser, the controlled windows are shown regardless of the --show-sessions switch.
|
acceptAlert(timeout, promptText)
Accept an alert. promptText is returned if defined and if the alert includes a prompt. The command fails if the alert does not appear within timeout millisecond. If timeout is omitted, a default value of 1,000 will be used.
sn.assertText(xpath, expected, modifiers…)
Assert that the text in the element pointed by xpath matches text.
xpath-
Points to the element whose content will be asserted ("target element").
expected-
The value expected to be in the target element.
modifiers-
A list of parameters affecting how the comparison between the actual content of the target element and the expected value. This list can be empty. Possible list values:
TextAssertions.modifiers.Negate-
Negates the condition.
TextAssertions.modifiers.Regex-
Considers the expected be a regular expression against which the actual string is matched.
TextAssertions.modifiers.Trim-
Trims trailing and leading white spaces from the actual value.
TextAssertions.modifiers.IgnoreWhiteSpace-
Deletes all white spaces before comparison.
TextAssertions.modifiers.IgnoreCase-
converts both the actual and the expected strings to lowercase before comparison.
TextAssertions.modifiers.Contains-
Checks if the expected string is contained in the actual string.
sn.dismissAlert(timeout)
Dismiss an alert. The command fails if the alert does not appear within timeout millisecond. If timeout is omitted, a default value of 1,000 will be used.
sn.fileUpload(xpath, files)
Upload files to the element pointed by xpath. Absolute paths are used as-is; relative paths are resolved from the project’s root directory.
sn.moveToElement(xpath) Deprecated
Scroll the element pointed by xpath into view, and move the mouse to its center. Deprecated. Use `scrollToElement(xpath)`
sn.pressShiftTabKey(xpath)
Press the Shift and Tab keys.
xpath-
Points to the element which will be focused while the key press is happening.
sn.screenshot()
Take a screenshot of the session’s window. The screenshot will be shown in the run report.
sn.scrollByAmount(deltaX, deltaY)
Scroll browser window by a given amount.
deltaX-
Amount to scroll in the right direction. Negative values mean "scroll left".
deltaY-
Amount to scroll in the down direction. Negative values mean "scroll up".
sn.scrollFromOrigin(origin, deltaX, deltaY, offsetX, offsetY)
Scrolls by provided amount based on a provided origin, which can be either 'viewport' or an xpath of an element. If the scroll origin is 'viewport', then the upper left of the viewport is used as the origin. If the scroll origin is an element, then the origin is either the center of the element.
offsetX and offsetY define how much to offset the origin in the right and down directions.
Similarly, deltaX and deltaY define how much to scroll in the right and down directions.
Negative values represent left and up, respectively.
sn.scrollToBottom(xpath)
If xpath is not null, scrolls the element pointed by xpath into view. If xpath is null, scrolls to the bottom of the page.
sn.scrollToElement(xpath)
Scroll page to an element, represented by a given xpath.
Regardless of whether the element is above or below the current viewscreen, the viewport will be scrolled so the bottom of the element is at the bottom of the screen.
sb.selectByValue(xpath, value)
Select an option whose value is value in the select element pointed by xpath.
sn.selectByVisibleText(xpath, text)
Select an option whose visible text is text in the select element pointed by xpath.
sn.sleep(millis) Deprecated
Pause the program for the given duration (in milliseconds).
This method is deprecated, use Ctrl.doSleep(millis) instead.
|
sn.store(xpath, rtvVariableName)
Stores the text contents of the element pointed by xpath to the runtime variable rtvVariableName. See Runtime Variables.
sn.waitForClickability(xpath, millis)
Wait up to millis milliseconds for the element pointed by xpath to become clickable.
If millis is omitted, a default value of 5,000 will be used.
sn.waitForInvisibility(xpath, millis)
Wait up to millis milliseconds for the element pointed by xpath to become invisible.
If millis is omitted, a default value of 5,000 will be used.