The Selenium Library

/* @provengo summon selenium */

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 --dry flag, like so:

provengo run --dry PATH_TO_PROJECT`.

Or, set the run.dry property in the configuration file to true.

The provengo tool will not execute the instructions using Selenium. Instead, it will print them to the console.

Classes

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.

SeleniumSession Methods

sn.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.assertNotEditable(xpath)

Assert that the element pointed by xpath is not editable.

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

Click the browser’s "back" button.

sn.click(xpath, timeout)

Click the element pointed by xpath. optional: timeout milliseconds to wait for the element to become clickable. Defaults to the value specified by the selenium.implicit-wait configuration key (normally 500 msec).

sn.close()

Close the browser window currently in focus.

sn.contextClick(xpath)

Perform a context click at the middle of the element pointed by xpath.

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.doubleClick(xpath, timeout)

Perform a double-click on the element pointed by xpath. optional: timeout milliseconds to wait for the element to become clickable. Defaults to the value specified by the selenium.implicit-wait configuration key (normally 500 msec).

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

Click the browser’s "forward" button.

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.putPropertyInDom(xpath, property)

Put property in the DOM, at location xpath.

sn.quit()

quits the entire browser session with all its tabs and windows.

sn.refresh()

Refresh the browser window.

sn.runCode([params],aFunction)

Runs a function in the browser. The function can report back and write to the runtime log through pvg, an object made available to it during execution. The paramsObj is used for passing parameters to the executed function.

This method is useful for validating variable data whose structure is not known while creating the model. For example, checking that the sum of cells at a given table column matches a certain value, while the number of rows at said table is unknown at modeling time. Because the number of rows is unknown, the model developer cannot create a loop for going over table rows at the model. However, using sn.runCode, model developers can iterate over the rows at execution time, and validate their sum.

params

Optional. Any Value. Allows passing data to aFunction, where it can be accessed using pvg.params.

aFunction

Function. A function that runs in the browser and reports back to provengo. Does not take any parameters. To pass data to it, use the params parameter. aFunction can be either an inline/anonymous function, or a name of a function defined elsewhere in the model. aFunction reports back to provengo using pvg callback service object (see below), available as a global variable.

aFunction is sent to the browser and executed there - not at the provengo engine. This means it cannot directly access variables from the model. If such values need to tag along with aFunction, wrap them in an object and pass that as the params parameter.

pvg Callback Service Object

This object allows the function sent to the browser to interact with provengo environment - report test results, read and write runtime variables, and print to the log. The object is made available to the function via a global variable, named pvg.

Methods
pvg.params

The params object passed to the runCode as a parameter.

pvg.success(aMessage)

Marks the test step as a success. Terminates the function’s execution.

pvg.fail(aMessage)

Marks the test step as a failure. Terminates the function’s execution.

pvg.error(aMessage)

Marks that the test step has encountered an error. Terminates the function’s execution.

pvg.log(aMessage)

Writes the passed message to provengo's log. Useful for writing intermediate values, e.g. for debugging.

pvg.rtv.set(key, value)

Sets the value of the key runtime variable to value. Note: This call takes effect only after runCode finishes execution.

Example
A fully-functional project showing various runCode is available at Provengo’s TechDemos repository.

Here we use runCode to count the number of <li> elements in two lists. The ids of the lists are passed via the params object.

/**
 * Defined at the program global scope, runs in the browser.
 */
function countLiElements(){
    let listOneId = pvg.params.id1; (1)
    let listOneItemCount = document.querySelectorAll(`#${listOneId} li`).length;
    let listTwoId = pvg.params.id2;
    let listTwoItemCount = document.querySelectorAll(`#${listTwoId} li`).length;
    pvg.log(`Item count on 2nd list: ${listTwoItemCount}`); (2)
    if ( listOneItemCount === listTwoItemCount ){
        pvg.success("Lists identical length"); (3)
    } else {
        pvg.fail(`List lengths differ. List 1: ${listOneItemCount}, List 2: ${listTowItemCount}`);
    }
}

const session = new SeleniumSession("main");

bthread("runCodeExample", function(){
    let listNameSet = waitFor(...); // waiting for an event that will have the list names
    session.runCode({
            id1: listNameSet.data.list1,
            id2: listNameSet.data.list2
        },
        countLiElements
    );
});

  1. Using the params to read the list id passed from the model.

  2. Logging intermediate data using pvg.log

  3. Great success!!

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

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

sn.scrollToTop()

Scroll to the top of the page.

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

Opens a new browser window at the passed url.

sn.store(xpath, rtvVariableName)

Stores the text contents of the element pointed by xpath to the runtime variable rtvVariableName. See Runtime Variables.

sn.switchFrame(frameName)

Switch to the frame whose name is frameName.

sn.switchTab(tabIndex)

Switch to the tab whose index is tabIndex.

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.

sn.waitForVisibility(xpath, millis)

Wait up to millis milliseconds for the element pointed by xpath to become visible. If millis is omitted, a default value of 5,000 will be used.

sn.writeText(xpath, text, clearBeforeWrite)

Write the text into the element pointed by xpath.

xpath

Points to the element into which the text will be written

text

The text to write

clearBeforeWrite

When true, clear the content of the destination element before writing to it.

Events and Event Sets

EventsInOtherSessions(sessionName)

An event set of all selenium events that do not belong to the session sessionName. This is a utility class for advanced use.