Selenium keywords


Observations

  • Mandatory keyword arguments are shown in bold font.

  • All keywords listed in this page are found in the package org.getopentest.selenium, so you must prefix their names with this package name when calling them. For example, to call the Click action, use this syntax:

    - description: Click the submit button
      action: org.getopentest.selenium.Click
      args:
        locator: { id: submit }
  • If you have some basic familiarity with the Java language and would like to know more about how a certain keyword is implemented, please take a peek at the source code.

UI element locators

Since most Selenium keywords act on a particular UI element, they need to be given a way to identify that element. This is done by providing a locator argument. Locator arguments are simply objects that must contain the information necessary to identify a web UI element, using one of the methods supported by Selenium (id, css, name, class, tag, text or xpath). Some examples:

locator: { id: element1 }
locator: { name: name1 }
locator: { css: #container div.class1 }
locator: { class: class1 }
locator: { tag: button }
locator: { text: Submit the form }
locator: { xpath: "//element[@class='class1']" }
Note
In most cases, the values specified in locator arguments do not need to be enclosed in double quotes (courtesy of the YAML format). However, most xPath expressions must be enclosed in double quotes because they contain the square brackets characters "[" and "]", which in YAML are special characters used to represent an array value.

Common keywords

AssertElementDisabled

Verifies that a UI element is currently disabled.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is disabled
  action: org.getopentest.selenium.AssertElementDisabled
  args:
    locator: { id: submit }

AssertElementEnabled

Verifies that a UI element is currently enabled.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is enabled
  action: org.getopentest.selenium.AssertElementEnabled
  args:
    locator: { id: submit }

AssertElementHasClass

Verifies that a UI element’s class attribute contains the specified class name.

Arguments:

locator

The locator of the UI element.

class

The class name to look for.

Example:

- description: Verify that the submit button has class "primary"
  action: org.getopentest.selenium.AssertElementHasClass
  args:
    locator: { id: submit }
    class: primary

AssertElementNotPresent

Verifies that a UI element is NOT present in the DOM, regardless of its visibility. This assertion will fail even if the element is not currently visible, as long as it exists in the DOM.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is not present
  action: org.getopentest.selenium.AssertElementNotPresent
  args:
    locator: { id: submit }

AssertElementNotReadOnly

Verifies that a UI element doesn’t have the "readonly" attribute.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is not read-only
  action: org.getopentest.selenium.AssertElementNotReadOnly
  args:
    locator: { id: submit }

AssertElementNotSelected

Verifies that a UI element is not selected.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the "Agree" checkbox is not selected
  action: org.getopentest.selenium.AssertElementNotSelected
  args:
    locator: { id: agree }

AssertElementNotVisible

Verifies that a UI element is either invisible or not present in the DOM.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is not visible
  action: org.getopentest.selenium.AssertElementNotVisible
  args:
    locator: { id: submit }

AssertElementPresent

Verifies that a UI element is present in the DOM, regardless of its visibility. This assertion will succeed even for a hidden element, as long as it exists in the DOM.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is present in the DOM
  action: org.getopentest.selenium.AssertElementPresent
  args:
    locator: { id: submit }

AssertElementReadOnly

Verifies that a UI element has the "readonly" attribute specified (regardless of the actual value of the attribute).

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is read-only
  action: org.getopentest.selenium.AssertElementReadOnly
  args:
    locator: { id: submit }

AssertElementSelected

Verifies that a UI element is selected.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the "Agree" checkbox is selected
  action: org.getopentest.selenium.AssertElementSelected
  args:
    locator: { id: agree }

AssertElementText

Validates the text content of a UI element.

Arguments:

locator

The locator of the UI element.

text

The exact text that we expect to find in the UI element. Exactly one of the text or the textContains arguments must be provided.

textContains

A substring that we expect to be present anywhere in the UI element.

caseInsensitive

Specifies whether the text comparison operations will be carried out case-insensitive. Default: false.

Example:

- description: Verify that the "product" textbox contains "MacBook"
  action: org.getopentest.selenium.AssertElementText
  args:
    locator: { id: product }
    textContains: MacBook

AssertElementVisible

Verifies that a UI element is present in the DOM and visible. Visibility means that the element is not only displayed but also has a height and width greater than 0.

Arguments:

locator

The locator of the UI element.

Example:

- description: Verify that the submit button is visible
  action: org.getopentest.selenium.AssertElementVisible
  args:
    locator: { id: submit }

AssertListOption

Validates the currently selected option in a list or dropdown control (a select UI element).

Arguments:

locator

The locator of the select element.

optionValue

The value attribute of the list option to look for. Exactly one of the optionValue, optionText or optionNumber arguments must be provided.

optionText

The exact text displayed by the list option.

optionNumber

The number of the list option (numbering starts from 1).

Example:

- description: Verify option number 2 is selected in the products list
  action: org.getopentest.selenium.AssertListOption
  args:
    locator: { id: products }
    optionNumber: 2

AssertPageTitle

Validates the title of the current page.

Arguments:

title

The exact text that we expect in the page title. Exactly one of the title or titleContains arguments must be provided.

titleContains

A substring that we expect to find present anywhere in the page title.

Example:

- description: Validate page title
  action: org.getopentest.selenium.AssertPageTitle
  args:
    text: Place order

ClearContent

Clears the text content of input and textarea elements and has no effect on other elements. Please note that keyboard or mouse events will not fire when using this approach. If you want to ensure keyboard events are fired, consider using the SendKeys action with the backspace key. To ensure you get a change event, consider sending the the tab key using the same approach.

Arguments:

locator

The locator of the UI element.

Example:

- description: Clear the text content of the username textbox
  action: org.getopentest.selenium.ClearContent
  args:
    locator: { id: username }

Click

Clicks on an element. The prerequisites for an element to be clicked are that the element must be visible and have a height and width greater then 0.

Arguments:

locator

The locator of the UI element.

Example:

- description: Click the submit button
  action: org.getopentest.selenium.Click
  args:
    locator: { id: submit }

CloseBrowser

Discards the current browser instance and WebDriver instance. This is not normally something that needs to be done explicitly, as the test actor will automatically close the browser instance when a test session ends and create a new one when the first Selenium keyword is encountered in the next test.

Example:

- description: Close the current browser instance
  action: org.getopentest.selenium.CloseBrowser

CloseWindow

Closes the current browser window (or browser tab).

Example:

- description: Close the current browser window
  action: org.getopentest.selenium.CloseWindow

DeselectListOption

Deselects an option in a list or dropdown control (a select HTML element) that allows multiple selections.

Arguments:

locator

The locator of the UI element.

optionValue

The value attribute of the list option to deselect. Exactly one of the optionValue, optionText or optionNumber arguments must be provided.

optionText

The exact text displayed by the list option to deselect.

optionNumber

The number of the list option to deselect (numbering starts from 1).

Example:

- description: Deselect the second item in the products list
  action: org.getopentest.selenium.DeselectListOption
  args:
    locator: { id: products }
    optionNumber: 2

ExecuteScript

Execute JavaScript code in the context of the currently selected frame or window.

Arguments:

script

The JavaScript code to execute.

async

A boolean argument that can be used to execute the code asynchronously. The asynchronous JavaScript code must explicitly signal it finished execution by invoking the provided callback function. This callback is always injected into the executed function as the last argument. Default: false.

asyncArgs

The list of arguments to pass to the JavaScript function when executing code asynchronously. Default: an empty array.

timeoutSec

Sets the amount of time to wait for an asynchronous script to finish execution before throwing an error. If the timeout is negative, then the script will be allowed to run indefinitely. Default: 20.

Example:

- description: Display a greeting dialog box in the browser
  action: org.getopentest.selenium.ExecuteScript
  args:
    script: |
      var message = "Hello World!";
      alert(message);

GetElements

Collects and returns a list of UI elements.

Arguments:

locator

The locator that identifies the UI elements.

Output values:

elements

An array of UI element objects with an API similar to the Selenium WebElement API. The methods supported are: getAttribute(name), getLocation(), getSize(), getTagName(), getText(), isDisplayed(), isEnabled() and isSelected().

Example:

- description: Navigate to the GitHub homepage
  action: org.getopentest.selenium.NavigateTo
  args:
    url: https://github.com/

- description: Find all "p" elements on the page
  action: org.getopentest.selenium.GetElements
  args:
    locator: {css: p}
    $localData:
      paragraphs: $output.elements

- script: |
    var paragraphs = $localData.paragraphs;

    // Use the Array.filter JS API to find all paragraphs
    // that contain the word "GitHub"
    var filteredParagraphs =
      paragraphs.filter(function(p) {
        return (p.getText().indexOf("GitHub") > -1) ;
      });

    // Log the full HTML source of the elements
    $log(
      "Paragraphs containing the word 'GitHub': " +
      filteredParagraphs
        .map(function(p) {
          return p.getAttribute("outerHTML");
        })
        .join(", "));

HandleModal

Handles modal dialog boxes created by the browser (alert dialogs, authentication dialogs, etc.).

Arguments:

perform

Specifies the type of dialog to handle or the type of action to perform on the dialog. The valid values for this argument are:

  • accept (click the "OK" button)

  • dismiss (click the "Cancel" button)

  • getText (read the text displayed in the dialog box)

  • sendKeys (type text into the dialog box)

text

The text to input. Only necessary for the sendKeys action. Exactly one of the text or key arguments must be provided.

key

One of the values from the Selenium Keys enumeration ("ENTER", "CONTROL", "SHIFT", etc.) Only necessary for the sendKeys action.

Output values:

text

Provides the text that was read from the dialog box. Only produced by the getText action.

Example:

- description: Read the text displayed in the dialog box
  action: org.getopentest.selenium.HandleModal
  args:
    perform: getText
    $localData:
        dialogText: $output.text

- description: Log the text that we just read
  script: |
    $log("The dialog box said: " + $localData.dialogText);

Moves back one position in the browser’s history.

Example:

- description: Go back to the previous page
  action: org.getopentest.selenium.NavigateBack

Moves forward one position in the browser’s history.

Example:

- description: Go forward to the next page
  action: org.getopentest.selenium.NavigateForward

Loads the web page from the specified URL in the current browser window. This will follow redirects issued either by the server or as a meta-redirect from within the returned HTML.

Arguments:

url

The URL to navigate to.

Example:

- description: Load the GitHub homepage
  action: org.getopentest.selenium.NavigateTo
  args:
    url: https://github.com/

ReadCurrentUrl

Reads the URL the browser is currently looking at.

Output values:

anchor

The anchor (also known as the "reference") of the URL.

authority

The authority part of the URL.

defaultPort

The default port number of the protocol associated with the URL. If the URL scheme does not define a default port number, then -1 is returned.

file

The file name of the URL. The returned file portion will be the same as the URL path concatenated with the UR: query string, if any. If there is no query portion.

host

The host name of the URL, if applicable. The format of the host conforms to RFC 2732, i.e. for a literal IPv6 address, this method will return the IPv6 address enclosed in square brackets ('[' and ']').

path

The path part of the URL.

port

The port number of the URL.

protocol

The protocol name of the URL.

query

The query part of the URL.

userInfo

The user information part of the URL.

url

The full URL the browser is currently looking at.

Example:

- description: Read the current URL
  action: org.getopentest.selenium.ReadCurrentUrl
  args:
    $localData:
        currentUrl: $output.url

- description: Log the current URL
  script: |
    $log("The current URL is: " + $localData.currentUrl);

ReadElementAttribute

Reads the value of an attribute for the specified element. Will return the current value, even if this has been modified after the page has been loaded.

Arguments:

locator

The locator of the UI element.

attribute

The name of the attribute to read.

Output values:

text

The text that was read from the attribute’s value.

Example:

- description: Read the "data-category" attribute for product 2
  action: org.getopentest.selenium.ReadElementAttribute
  args:
    locator: {css:  #products > .product:nth-of-type(2)}
    attribute: data-category

ReadElementCount

Returns the number of elements that match a certain locator.

Arguments:

locator

The locator of the UI element.

Output values:

count

The number of elements that match the locator.

Example:

- description: Read the number of elements in the products list
  action: org.getopentest.selenium.ReadElementCount
  args:
    locator: {css: #products .product}
    $localData:
        productCount: $output.count

- description: Log the number of products in the list
  script: |
    $log("We found " + $localData.productCount + " products");

ReadElementText

Reads the visible (not hidden by CSS) inner text of this element, including sub-elements, without any leading or trailing whitespace.

Arguments:

locator

The locator of the UI element.

Output values:

text

The visible inner text of the element.

Example:

- description: Read the product description
  action: org.getopentest.selenium.ReadElementText
  args:
    locator: {css: "#product .description"}
    $localData:
        description: $output.text

- description: Log the product description
  script: |
    $log("The product description is " + $localData.description);

ReadPageSource

Gets the source of the last loaded page. If the page has been modified after loading (for example, by Javascript) there is no guarantee that the returned text is that of the modified page. You should consult the documentation of the particular WebDriver implementation you are using (e.g. chromedriver, geckodriver, etc.), to determine whether the returned text reflects the current state of the page or the text last sent by the web server. The page source returned is a representation of the underlying DOM: do not expect it to be formatted or escaped in the same way as the response sent from the web server.

Output values:

pageSource

The page source.

Example:

- description: Read the current page source
  action: org.getopentest.selenium.ReadPageSource
  args:
    $localData:
        pageSource: $output.pageSource

- description: Log the page source
  script: |
    $log("The page source is " + $localData.pageSource);

ReadPageTitle

Reads the title of the current page.

Output values:

title

The title of the page.

Example:

- description: Read page title
  action: org.getopentest.selenium.ReadPageTitle
  args:
    $localData:
        pageTitle: $output.title

- description: Log the page title
  script: |
    $log("The page title is " + $localData.pageTitle);

SelectListOption

Selects an option in a listbox or dropdown control (a select HTML element), by value, option text, or number.

Arguments:

locator

The locator of the select element to use.

optionValue

The value attribute of the list option to select. Exactly one of the optionValue, optionText or optionNumber arguments must be provided.

optionText

The exact text displayed by the list option.

optionNumber

The number of the list option (numbering starts from 1).

Example:

- description: Select product 1 in the list
  action: org.getopentest.selenium.SelectListOption
  args:
    locator: { id: products }
    optionValue: product1

SendKeys

Simulates typing into an element, which may set its value (depending on the type of UI element).

Arguments:

locator

The UI element to type in.

text

The text to type. Exactly one of the text or key arguments must be provided.

key

One of the values from the Selenium Keys enumeration ("ENTER", "CONTROL", "SHIFT", etc.)

clearContent

Instructs the action to clear the content of the element before typing in the new one. Default: false.

sendEnter

Instructs the action to send the ENTER key after typing the text. Useful for submitting a form after filling its last input element. Default: false.

Example:

- description: Type "opentest" in the Google search box
  action: org.getopentest.selenium.SendKeys
  args:
    locator: { name: q }
    text: opentest

SetBrowserAspect

Configures the position and size of the browser window.

Arguments:

positionX

The X coordinate of the top left corner of the browser window.

positionY

The Y coordinate of the top left corner of the browser window.

width

The width of the browser window.

height

The height of the browser window.

Example:

- description: Set browser position and size
  action: org.getopentest.selenium.SetBrowserAspect
  args:
    positionX: 0
    positionY: 0
    width: 1024
    height: 768

SwitchToDefaultContent

Selects either the first frame in a frameset element, or the main document when a page contains one or more iframe elements.

Example:

- description: Switch context to the main content of the page
  action: org.getopentest.selenium.SwitchToDefaultContent

SwitchToFrame

Switches context to a frame by its name, ID or locator.

Arguments:

frameName

The frame’s name. At least one of the frameName ,frameIndex or the locator arguments must be provided.

locator

The frame element’s locator.

frameIndex

The frame’s index (first frame in the page has index 0).

Example 1:

- description: Switch to the "products" frame (by name)
  action: org.getopentest.selenium.SwitchToFrame
  args:
    frameName: products

Example 2:

- description: Switch to the "products" frame (by CSS)
  action: org.getopentest.selenium.SwitchToFrame
  args:
    locator: { css: "iframe[name='products']" }

SwitchToLastWindow

Switch the focus of future commands for this driver to the last window that was opened in the current browser instance.

Example:

- description: Switch focus to the last opened window
  action: org.getopentest.selenium.SwitchToLastWindow

SwitchToWindow

Switches the focus of future commands for this driver to the window with the given number.

Arguments:

windowNumber

The number of the window to switch the focus to. Windows are numbered starting from 1, in the order they were opened.

Example:

- description: Switch focus to the first window
  action: org.getopentest.selenium.SwitchToWindow
  args:
    windowNumber: 1

TakeScreenshot

Captures a screenshot of the current browser window. The image is saved in the test actor working directory and is sent asynchronously to the OpenTest server so it can be presented in the web-based test execution report.

Example:

- description: Take a screenshot
  action: org.getopentest.selenium.TakeScreenshot

Advanced user gestures keywords

The test actions listed in this section leverage the Selenium user-facing API for emulating complex user gestures. You can call any sequence of actions you want to perform, but the actions won’t be executed until a call to ActionsPerform is encountered. For example, here’s how you would execute a CTRL + Click on a UI element:

- action: org.getopentest.selenium.ActionsKeyDown
  args:
    key: CONTROL

- action: org.getopentest.selenium.ActionsClick
  args:
    locator: { id: product1 }

- action: org.getopentest.selenium.ActionsKeyUp
  args:
    key: CONTROL

- action: org.getopentest.selenium.ActionsPerform

ActionsClick

Clicks at the current mouse location or in the middle of the specified element. Internally, it calls one of the Actions.click() or Actions.click(element) methods.

Arguments:

locator

The locator of the UI element. Default: null.

Example:

- description: Click the submit button
  action: org.getopentest.selenium.ActionsClick
  args:
    locator: { id: submit }

ActionsClickAndHold

Clicks (without releasing) at the current mouse location or in the middle of the specified element. Internally, it calls one of the Actions.clickAndHold() or Actions.clickAndHold(element) methods.

Arguments:

locator

The locator of the UI element. Default: null.

Example:

- description: Click and hold the submit button
  action: org.getopentest.selenium.ActionsClickAndHold
  args:
    locator: { id: submit }

ActionsContextClick

Performs a context-click (right-click) at the current mouse location or at middle of the specified element. Internally, it calls one of the Actions.contextClick() or Actions.contextClick(element) methods.

Arguments:

locator

The locator of the UI element. Default: null.

Example:

- description: Right-click the submit button
  action: org.getopentest.selenium.ActionsContextClick
  args:
    locator: { id: submit }

ActionsDoubleClick

Performs a double-click at the current mouse location or at middle of the specified element. Internally, it calls one of the Actions.doubleClick() or Actions.doubleClick(element) methods.

Arguments:

locator

The locator of the UI element. Default: null.

Example:

- description: Double-click the submit button
  action: org.getopentest.selenium.ActionsDoubleClick
  args:
    locator: { id: submit }

ActionsDragAndDrop

Performs click-and-hold at the location of the source element, moves to the location of the target element, then releases the mouse. Internally, it calls the Actions.dragAndDrop(source, target) method.

Arguments:

source

The locator of the source element.

target

The locator of the target element.

Example:

- description: Drag and drop product 1 to cart area
  action: org.getopentest.selenium.ActionsDragAndDrop
  args:
    source: { id: product1 }
    target: { id: cart }

ActionsDragAndDropBy

Performs click-and-hold at the location of the source element, moves by a given offset, then releases the mouse. Internally, it calls the Actions.dragAndDropBy(source, target) method.

Arguments:

locator

The locator of the UI element.

xOffset

The horizontal move offset. Default: 0.

yOffset

The vertical move offset. Default: 0.

Example:

- description: Drag and drop product 1 to the right 100 pixels
  action: org.getopentest.selenium.ActionsDragAndDropBy
  args:
    locator: { id: product1 }
    xOffset: 100

ActionsKeyDown

Simulates pressing a modifier key. Does not release the modifier key - subsequent interactions may assume it’s kept pressed. Note that the modifier key is never released implicitly - either ActionsKeyUp or ActionsSendKeys(with key=NULL) must be called to release the modifier.

Arguments:

locator

Indicates the UI element to focus on before doing the key press. Default: null.

key

The key to press. Must be one of the values from the Selenium Keys enumeration ("ENTER", "CONTROL", "SHIFT", etc.). Exactly one of the key or the char arguments must be provided.

char

The character corresponding to the key to be pressed.

Example:

- description: Press the control key
  action: org.getopentest.selenium.ActionsKeyDown
  args:
    key: CONTROL

ActionsKeyUp

Simulates releasing a modifier key. Releasing a non-depressed key will yield undefined behavior.

Arguments:

locator

Indicates the UI element to focus on before releasing the key. Default: null.

key

The key to release. Must be one of the values from the Selenium Keys enumeration ("ENTER", "CONTROL", "SHIFT", etc.). Exactly one of the key or the char arguments must be provided.

char

The character corresponding to the key to release.

Example:

- description: Release the control key
  action: org.getopentest.selenium.ActionsKeyUp
  args:
    key: CONTROL

ActionsMoveByOffset

Moves the mouse from its current position (or 0,0) by the given offset. If the coordinates provided are outside the viewport (the mouse will end up outside the browser window) then the viewport is scrolled to match.

Arguments:

xOffset

The horizontal move offset. Default: 0.

yOffset

The vertical move offset. Default: 0.

Example:

- description: Move the mouse to the right 100 pixels
  action: org.getopentest.selenium.ActionsMoveByOffset
  args:
    xOffset: 100

ActionsMoveTo

Moves the mouse to the middle of an element. The element is scrolled into view and its location is calculated using getBoundingClientRect.

Arguments:

locator

The locator of the UI element.

Example:

- description: Move the mouse to product 1 element
  action: org.getopentest.selenium.ActionsMoveTo
  args:
    locator: { id: product1 }

ActionsPause

Delays execution for the specified period of time.

Arguments:

durationMs

The duration of the delay, in milliseconds.

Example:

- description: Pause for 1 second
  action: org.getopentest.selenium.ActionsPause
  args:
    durationMs: 1000

ActionsPerform

Performs the chain of gestures that was specified so far using the set of keywords prefixed with "Actions". As soon as this action executes, a new chain of actions can be built in the same way.

Example:

- description: Performs gestures
  action: org.getopentest.selenium.ActionsPerform

ActionsRelease

Releases the depressed left mouse button, in the middle of the specified element. This is equivalent to: Actions.moveToElement(onElement).release() Invoking this action without invoking Actions.clickAndHold() first will result in undefined behavior.

Arguments:

locator

The locator of the UI element.

Example:

- description: Release the mouse over the product 1 element
  action: org.getopentest.selenium.ActionsRelease
  args:
    locator: { id: product1 }

ActionsSendKeys

Sends keys to the active element. This differs from calling WebElement.sendKeys() on the active element in two ways:

  • The modifier keys included in this call are not released.

  • There is no attempt to re-focus the element - so sendKeys(Keys.TAB) for switching elements should work.

Arguments:

text

The text to type. Exactly one of the text or the key arguments must be provided.

key

The key to type. Must be one of the values from the Selenium Keys enumeration ("ENTER", "CONTROL", "SHIFT", etc.).

Example:

- description: Type "John Doe"
  action: org.getopentest.selenium.ActionsSendKeys
  args:
    text: John Doe