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)

bthread( "automator", function(){
  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.

Selectors

Selenium uses selectors to detect web page components to inspect or interact with. To make automation more robust, Provengo supports two types of selectors (CSS and XPATH), and allows specifying multiple selectors for each command. This way, you can specify fallback selectors in case different versions of the SUT use different page structure or component naming scheme. The run reports will list which selector was used to perform the automation.

To use a specific selector scheme, prefix the selector with the scheme name and double-colon (e.g. css::#bigRedButton). If no prefix is used, Provengo defaults to XPATH. So writing xpath:://button[@id="bigRedButton"] is the same as writing //button[@id="bigRedButton"].

Example

Clicking a big red button. An updated version had a proper ID on that button, but some older versions require a more fragile selector. The following code will support both.

// @provengo summon selenium
const session = new SeleniumSession("dave");

bthread( "automator", function(){
  session.start("https://test.hal.com");
  session.click(["css::#signIn", "//a[contains(text(),'Sign In')]"]); (1)
}
1 Passing an array of selectors to the click method. Provengo will to use the selector in order, and use the first one it finds on the page.
All methods that accept a single selector, also accept an array of selectors. So go ahead, make your automations more robust :-).

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

Assert that the element pointed by selectors is not editable.

sn.assertText(selectors, expected, modifiers…​)

Assert that the text in the element pointed by selectors matches text.

selectors

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(selectors, timeout)

Click the element pointed by selectors. 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(selectors)

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

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(selectors, timeout)

Perform a double-click on the element pointed by selectors. 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(selectors, files)

Upload files to the element pointed by selectors. 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(selectors) Deprecated

Scroll the element pointed by selectors into view, and move the mouse to its center. Deprecated. Use `scrollToElement(selectors)`

sn.pressShiftTabKey(selectors)

Press the Shift and Tab keys.

selectors

Points to the element which will be focused while the key press is happening.

sn.putPropertyInDom(selectors, property)

Put property in the DOM, at location selectors.

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

If selectors is not null, scrolls the element pointed by selectors into view. If selectors is null, scrolls to the bottom of the page.

sn.scrollToBottom()

Scroll to the bottom of the page.

sn.scrollToElement(selectors)

Scroll page to an element, represented by a given selectors.

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(selectors, value)

Select an option whose value is value in the select element pointed by selectors.

sn.selectByVisibleText(selectors, text)

Select an option whose visible text is text in the select element pointed by selectors.

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(selectors, rtvVariableName)

Stores the text contents of the element pointed by selectors 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(selectors, millis)

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

sn.waitForInvisibility(selectors, millis)

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

sn.waitForVisibility(selectors, millis)

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

sn.writeText(selectors, text, clearBeforeWrite)

Write the text into the element pointed by selectors.

selectors

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.