Skip to main content

Element Actions

To interact with web elements, use driver.element() followed by the desired action. All element actions require a By locator to identify the target element.

For trust-gated natural-language element workflows such as driver.act("click Save"), see Natural Language Actions.

Typing​

Typing actions show the value being entered in the Allure step title. SHAFT caps long or multiline values in the title so reports stay readable, keeps the locator in step metadata, and adds the resolved element name only when the engine captures one. Secure typing remains masked.

type()​

Clears the text field and types the specified text.

TypeExample.java
By usernameField = By.id("username_textbox");
driver.element().type(usernameField, "john.doe");

typeAppend()​

Types text without clearing the field first — appends to existing content.

TypeAppendExample.java
By textBox = By.id("username_textbox");
driver.element().type(textBox, "SHAFT");
driver.element().typeAppend(textBox, " Engine"); // field now contains "SHAFT Engine"

typeSecure()​

Types text in a secure manner — the value is masked in reports for sensitive data like passwords.

TypeSecureExample.java
By passwordField = By.id("password_field");
driver.element().typeSecure(passwordField, "mySecretPassword");

typeFileLocationForUpload()​

Sets a file path for file upload input elements.

FileUploadExample.java
By fileInput = By.xpath("//form//input[@type='file']");
driver.element().typeFileLocationForUpload(fileInput, "src/test/resources/testDataFiles/testUpload.txt");

clear()​

Clears text from a text field or text area.

ClearExample.java
By textBox = By.id("username_textbox");
driver.element().clear(textBox);

Clicking​

click()​

Waits for the target element to be interactable, then clicks on it. Falls back to JavaScript click if the standard Selenium click fails. Click reports keep the resolved element name in the step title and keep the normalized locator, including Smart Locator labels, in step metadata.

ClickExample.java
By signInButton = By.id("sign_in_btn");
driver.element().click(signInButton);

clickAndHold()​

Waits for the element to be clickable, then clicks and holds it.

ClickAndHoldExample.java
driver.element().clickAndHold(elementLocator);

clickUsingJavascript()​

Clicks an element using JavaScript. Useful when the standard click fails due to element positioning or overlay issues.

ClickJsExample.java
driver.element().clickUsingJavascript(elementLocator);

doubleClick()​

Performs a double click on the target element.

DoubleClickExample.java
By doubleClickButton = By.className("double_click_btn");
driver.element().doubleClick(doubleClickButton);

Hovering​

hover()​

Hovers over the target element.

HoverExample.java
By menuItem = By.tagName("span");
driver.element().hover(menuItem);

hoverAndClick()​

Hovers over an element to reveal a dropdown or menu, then clicks on a visible option.

HoverAndClickExample.java
By hoverItem = By.linkText("Popular Toys");
By clickable = By.xpath("//a[contains(text(),'Video Games')]");
driver.element().hoverAndClick(hoverItem, clickable);

For multi-level hover menus, pass a list of locators to hover through before clicking:

MultiLevelHoverExample.java
List<By> hoverLocators = new ArrayList<>();
hoverLocators.add(By.linkText("Popular Toys"));
hoverLocators.add(By.xpath("//a[contains(text(),'Video Games')]"));

By clickable = By.linkText("Car");
driver.element().hoverAndClick(hoverLocators, clickable);

Scrolling​

scrollToElement()​

Scrolls the page to bring the target element into view.

ScrollExample.java
By footer = By.xpath("//a[@href='https://twitter.com/saucelabs']");
driver.element().scrollToElement(footer);

Screenshots​

captureScreenshot()​

Captures a screenshot of a specific element and attaches it to the report.

ElementScreenshotExample.java
By element = By.id("chart");
driver.element().captureScreenshot(element);

Drag and Drop​

Drag to Another Element​

DragToElementExample.java
By source = By.id("draggable");
By target = By.id("destination");
driver.element().dragAndDrop(source, target);

Drag to a Position​

DragToPositionExample.java
By source = By.id("draggable");
driver.element().dragAndDrop(source, 500, 500);

Drag by Offset​

DragByOffsetExample.java
By source = By.id("draggable");
driver.element().dragAndDropByOffset(source, 100, 50);

Element Information​

getTagName()​

Returns the HTML tag name of the target element.

GetTagNameExample.java
String tagName = driver.element().getTagName(elementLocator);

getAttribute()​

Returns the value of a specific attribute.

GetAttributeExample.java
By searchBox = By.cssSelector(".gLFyf.gsfi");
String nameAttr = driver.element().getAttribute(searchBox, "name");

getCSSProperty()​

Returns the value of a CSS property.

GetCssPropertyExample.java
String width = driver.element().getCSSProperty(elementLocator, "width");

getText()​

Returns the visible text content of the target element.

GetTextExample.java
String text = driver.element().getText(textElement);

getSize()​

Returns the size of the target element as a string.

GetSizeExample.java
String elementSize = driver.element().getSize(elementLocator);

getElementsCount()​

Returns the number of elements matching a locator.

GetElementsCountExample.java
int resultCount = driver.element().getElementsCount(By.cssSelector("h3.LC20lb"));

isElementDisplayed()​

Returns whether the element is currently displayed.

IsDisplayedExample.java
boolean isVisible = driver.element().isElementDisplayed(elementLocator);

isElementClickable()​

Returns whether the element is clickable (visible and enabled).

IsClickableExample.java
boolean isClickable = driver.element().isElementClickable(elementLocator);

select()​

Selects an option from a dropdown list by visible text. Select reports show the selected value in the step title and keep the dropdown locator in step metadata.

SelectExample.java
By dropdown = By.id("dropdown");
driver.element().select(dropdown, "Option 1");

getSelectedText()​

Returns the currently selected option text from a dropdown.

GetSelectedTextExample.java
By dropdown = By.id("dropdown");
String selected = driver.element().getSelectedText(dropdown);

IFrames​

switchToIframe()​

Switches driver focus to an iframe.

SwitchToIframeExample.java
By iframeLocator = By.id("ifr_id");
driver.element().switchToIframe(iframeLocator);

switchToDefaultContent()​

Switches driver focus back to the main page content.

SwitchToDefaultExample.java
driver.element().switchToDefaultContent();

getCurrentFrame()​

Returns the name or handle of the currently active iframe context. Useful for debugging iframe navigation state.

GetCurrentFrameExample.java
String currentFrame = driver.element().getCurrentFrame();

Clipboard Actions​

Performs clipboard operations on a text field. Supported actions: "copy", "paste", "cut", "select all", "unselect".

ClipboardExample.java
driver.element().clipboardActions(textFieldLocator, "select all");
driver.element().clipboardActions(textFieldLocator, "copy");

JavaScript Actions​

setValueUsingJavaScript()​

Sets the value of an element using JavaScript — useful when the standard type() method does not work.

SetValueJsExample.java
By inputField = By.id("username");
driver.element().setValueUsingJavaScript(inputField, "myUsername");

submitFormUsingJavaScript()​

Submits a form programmatically using JavaScript.

SubmitFormJsExample.java
By formElement = By.id("loginForm");
driver.element().submitFormUsingJavaScript(formElement);

Native Mobile Commands​

executeNativeMobileCommand()​

Executes a native Appium mobile command with custom parameters. Use this for advanced mobile interactions not covered by the standard element actions, such as mobile: scroll, mobile: swipe, or platform-specific gestures.

NativeMobileCommandExample.java
import java.util.Map;

// Scroll down on iOS
driver.element().executeNativeMobileCommand(
    "mobile: scroll",
    Map.of("direction", "down")
);

// Swipe on Android
driver.element().executeNativeMobileCommand(
    "mobile: swipeGesture",
    Map.of(
        "left", "100",
        "top", "500",
        "width", "200",
        "height", "200",
        "direction", "up",
        "percent", "0.75"
    )
);
note

This method is intended for mobile (Appium) test execution. The available commands and parameters depend on the Appium driver and the target platform (Android/iOS).

Wait Methods​

SHAFT provides several wait methods to handle synchronization:

WaitMethodExamples.java
// Wait until element text matches
driver.element().waitUntilElementTextToBe(locator, "Success");

// Wait until attribute contains value
driver.element().waitUntilAttributeContains(locator, "class", "complete");

// Wait until element is selected
driver.element().waitUntilElementToBeSelected(locator);

// Wait for specific number of elements
driver.element().waitUntilNumberOfElementsToBe(locator, 5);
driver.element().waitUntilNumberOfElementsToBeLessThan(locator, 10);
driver.element().waitUntilNumberOfElementsToBeMoreThan(locator, 0);

// Wait until all elements are present
driver.element().waitUntilPresenceOfAllElementsLocatedBy(locator);

Table Data Extraction​

Extracts table row data into a list of maps, where each map key is the column header.

TableDataExample.java
List<Map<String, String>> tableData = driver.element().getTableRowsData(tableLocator);
note

This works with standard HTML tables that use <thead> with <th> elements for column headers and <tbody> with <td> elements for row data.

Fluent Chaining​

All element actions support fluent chaining with .and():

FluentChainingExample.java
driver.element()
    .type(usernameField, "admin")
    .and().type(passwordField, "password")
    .and().click(loginButton);