Class ElementActionsHelper

java.lang.Object
com.shaft.gui.element.internal.ElementActionsHelper
public class ElementActionsHelper extends Object
Helper utilities for low-level element discovery, interaction, and reporting.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    ElementActionsHelper.TextDetectionStrategy
    Strategies used to extract textual content from a web element.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    OBFUSCATED_STRING
    Masking character used when obfuscating sensitive values in logs and reports.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ElementActionsHelper(boolean isSilent)
    Creates a new element actions helper.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    changeWebElementVisibilityUsingJavascript(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean desiredIsVisibleState)
    Changes a web element visibility state by setting inline style via JavaScript.
    String
    createReportMessage(String actionName, String testData, String elementName, Boolean passFailStatus)
    Builds a user-facing report message for element actions.
    void
    executeNativeMobileCommandUsingJavascript(org.openqa.selenium.WebDriver driver, String command, Map<String,String> parameters)
    Executes a native mobile JavaScript command through the driver.
    void
    failAction(org.openqa.selenium.WebDriver driver, String actionName, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> screenshots, Throwable... rootCauseException)
    Reports a failed element action using explicit action metadata and optional root cause.
    void
    failAction(org.openqa.selenium.WebDriver driver, String testData, org.openqa.selenium.By elementLocator, Throwable... rootCauseException)
    Reports a failed element action with test data and optional root cause.
    void
    failAction(org.openqa.selenium.WebDriver driver, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> attachments, Throwable... rootCauseException)
    Reports a failed element action with explicit attachments and optional root cause.
    void
    failAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, Throwable... rootCauseException)
    Reports a failed element action using inferred action name and optional root cause.
    String
    getElementName(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Resolves a human-readable element name for reporting purposes.
    int
    getElementsCount(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Returns the number of elements that match a certain elementLocator
    List<Object>
    getMatchingElementsInformation(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean checkForVisibility)
    Collects element-match metadata for the supplied locator.
    List<Object>
    identifyUniqueElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Identifies a unique matching element while enforcing visibility checks.
    List<Object>
    identifyUniqueElementIgnoringVisibility(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Identifies a unique matching element without visibility checks.
    boolean
    isFoundInStacktrace(Class<?> classObject, Throwable throwable)
    Checks whether a target class appears in the provided throwable stack trace.
    void
    passAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionName, String testData, List<List<Object>> screenshots, String elementName)
    Reports a successful element action with optional attachments.
    void
    passAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String testData, List<Object> screenshot, String elementName)
    Reports a successful element action with a single screenshot attachment.
    boolean
    performClipboardActions(org.openqa.selenium.WebDriver driver, ClipboardAction action)
    Performs a keyboard-based clipboard action on the active element.
    String
    reportActionResult(org.openqa.selenium.WebDriver driver, String actionName, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> screenshots, String elementName, Boolean passFailStatus, Throwable... rootCauseException)
    Finalizes action reporting by logging formatted message and attachments.
    static org.openqa.selenium.WebElement
    safeFindElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By locator)
    Safely calls driver.findElement(locator), handling the infinite recursion between Selenium 4.41.0's ElementLocation and Appium java-client 10.0.0's AppiumBy.findElements(SearchContext).
    static List<org.openqa.selenium.WebElement>
    safeFindElements(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By locator)
    Safely calls driver.findElements(locator), handling the infinite recursion between Selenium 4.41.0's ElementLocation and Appium java-client 10.0.0's AppiumBy.findElements(SearchContext).
    List<Object>
    scrollToFindElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Scrolls through the page until the target element is found or timeout is reached.
    void
    submitFormUsingJavascript(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
    Submits a form element using JavaScript in non-mobile executions.
    List<Object>
    takeScreenshot(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionName, String testData, boolean passFailStatus)
    Captures an action screenshot for reporting, with pass/fail aware behavior.
    List<Object>
    waitForElementPresence(org.openqa.selenium.WebDriver driver, String elementReferenceScreenshot)
    Waits for an on-screen image reference to appear within the current viewport.
    List<Object>
    waitForElementPresence(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean checkForVisibility)
    Waits for an element to be present (and optionally visible), then returns collected metadata.
    boolean
    waitForElementTextToBeNot(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String textShouldNotBe)
    Waits until the element text differs from the specified value.
    boolean
    waitForElementToBeClickable(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionToExecute)
    Waits until an element is clickable and optionally performs a follow-up action.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • OBFUSCATED_STRING

      public static final String OBFUSCATED_STRING
      Masking character used when obfuscating sensitive values in logs and reports.
      See Also:

  • Constructor Details

    • ElementActionsHelper

      public ElementActionsHelper(boolean isSilent)
      Creates a new element actions helper.
      Parameters:
      isSilent - true to suppress non-critical report logs; false otherwise

  • Method Details

    • safeFindElements

      public static List<org.openqa.selenium.WebElement> safeFindElements(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By locator)
      Safely calls driver.findElements(locator), handling the infinite recursion between Selenium 4.41.0's ElementLocation and Appium java-client 10.0.0's AppiumBy.findElements(SearchContext).

      The normal driver.findElements() path is attempted first. If a StackOverflowError occurs (caused by Appium 3.x returning InvalidArgumentException for non-W3C locator strategies, triggering ElementLocation ↔ AppiumBy infinite recursion), the method falls back to sending the find command directly via AppiumDriver.execute().

      Parameters:
      driver - the WebDriver instance
      locator - the element locator
      Returns:
      the list of found elements, or an empty list if none found or an error occurs

    • safeFindElement

      public static org.openqa.selenium.WebElement safeFindElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By locator)
      Safely calls driver.findElement(locator), handling the infinite recursion between Selenium 4.41.0's ElementLocation and Appium java-client 10.0.0's AppiumBy.findElements(SearchContext).
      Parameters:
      driver - the WebDriver instance
      locator - the element locator
      Returns:
      the found element
      Throws:
      org.openqa.selenium.NoSuchElementException - if the element cannot be found
      See Also:

    • waitForElementPresence

      public List<Object> waitForElementPresence(org.openqa.selenium.WebDriver driver, String elementReferenceScreenshot)
      Waits for an on-screen image reference to appear within the current viewport.
      Parameters:
      driver - the active WebDriver instance
      elementReferenceScreenshot - path to the reference image file
      Returns:
      list containing current screenshot, reference screenshot bytes, and matched coordinates

    • waitForElementPresence

      public List<Object> waitForElementPresence(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean checkForVisibility)
      Waits for an element to be present (and optionally visible), then returns collected metadata.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      checkForVisibility - whether visibility must be validated
      Returns:
      element information payload used by downstream action methods

    • scrollToFindElement

      public List<Object> scrollToFindElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Scrolls through the page until the target element is found or timeout is reached.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      Returns:
      element information including match count and first matched element

    • waitForElementToBeClickable

      public boolean waitForElementToBeClickable(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionToExecute)
      Waits until an element is clickable and optionally performs a follow-up action.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      actionToExecute - optional action name to execute after clickability is confirmed
      Returns:
      true when the element is clickable; otherwise false

    • waitForElementTextToBeNot

      public boolean waitForElementTextToBeNot(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String textShouldNotBe)
      Waits until the element text differs from the specified value.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      textShouldNotBe - text value that must no longer be present
      Returns:
      true when the condition is met; otherwise false

    • executeNativeMobileCommandUsingJavascript

      public void executeNativeMobileCommandUsingJavascript(org.openqa.selenium.WebDriver driver, String command, Map<String,String> parameters)
      Executes a native mobile JavaScript command through the driver.
      Parameters:
      driver - the active WebDriver instance
      command - mobile command expression (for example, mobile: scroll)
      parameters - command parameters map

    • submitFormUsingJavascript

      public void submitFormUsingJavascript(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Submits a form element using JavaScript in non-mobile executions.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the form element to submit

    • changeWebElementVisibilityUsingJavascript

      public void changeWebElementVisibilityUsingJavascript(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean desiredIsVisibleState)
      Changes a web element visibility state by setting inline style via JavaScript.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      desiredIsVisibleState - true to show element; false to hide it

    • takeScreenshot

      public List<Object> takeScreenshot(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionName, String testData, boolean passFailStatus)
      Captures an action screenshot for reporting, with pass/fail aware behavior.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element, or null for full page
      actionName - current action name
      testData - current action test data
      passFailStatus - current action status
      Returns:
      screenshot attachment payload

    • getElementName

      public String getElementName(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Resolves a human-readable element name for reporting purposes.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      Returns:
      accessible name when available; otherwise formatted locator text

    • performClipboardActions

      public boolean performClipboardActions(org.openqa.selenium.WebDriver driver, ClipboardAction action)
      Performs a keyboard-based clipboard action on the active element.
      Parameters:
      driver - the active WebDriver instance
      action - clipboard action to execute
      Returns:
      true when action succeeds; otherwise false

    • isFoundInStacktrace

      public boolean isFoundInStacktrace(Class<?> classObject, Throwable throwable)
      Checks whether a target class appears in the provided throwable stack trace.
      Parameters:
      classObject - class to search for
      throwable - throwable containing stack trace frames
      Returns:
      true when class is found in the stack trace; otherwise false

    • identifyUniqueElement

      public List<Object> identifyUniqueElement(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Identifies a unique matching element while enforcing visibility checks.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      Returns:
      element information payload for the matched element

    • identifyUniqueElementIgnoringVisibility

      public List<Object> identifyUniqueElementIgnoringVisibility(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Identifies a unique matching element without visibility checks.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      Returns:
      element information payload for the matched element

    • getMatchingElementsInformation

      public List<Object> getMatchingElementsInformation(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, boolean checkForVisibility)
      Collects element-match metadata for the supplied locator.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      checkForVisibility - whether visibility must be validated
      Returns:
      list containing count and resolved element details

    • getElementsCount

      public int getElementsCount(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator)
      Returns the number of elements that match a certain elementLocator
      Parameters:
      driver - the current instance of Selenium WebDriver
      elementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      Returns:
      integer value that represents the number of elements that match the desired elementLocator

    • passAction

      public void passAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String testData, List<Object> screenshot, String elementName)
      Reports a successful element action with a single screenshot attachment.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      testData - test data associated with the action
      screenshot - screenshot attachment payload
      elementName - resolved element name for reporting

    • passAction

      public void passAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, String actionName, String testData, List<List<Object>> screenshots, String elementName)
      Reports a successful element action with optional attachments.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      actionName - action name to report
      testData - test data associated with the action
      screenshots - screenshot attachments payload
      elementName - resolved element name for reporting

    • failAction

      public void failAction(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, Throwable... rootCauseException)
      Reports a failed element action using inferred action name and optional root cause.
      Parameters:
      driver - the active WebDriver instance
      elementLocator - locator of the target element
      rootCauseException - optional root cause exceptions

    • failAction

      public void failAction(org.openqa.selenium.WebDriver driver, String testData, org.openqa.selenium.By elementLocator, Throwable... rootCauseException)
      Reports a failed element action with test data and optional root cause.
      Parameters:
      driver - the active WebDriver instance
      testData - test data associated with the action
      elementLocator - locator of the target element
      rootCauseException - optional root cause exceptions

    • failAction

      public void failAction(org.openqa.selenium.WebDriver driver, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> attachments, Throwable... rootCauseException)
      Reports a failed element action with explicit attachments and optional root cause.
      Parameters:
      driver - the active WebDriver instance
      testData - test data associated with the action
      elementLocator - locator of the target element
      attachments - pre-collected attachments
      rootCauseException - optional root cause exceptions

    • failAction

      public void failAction(org.openqa.selenium.WebDriver driver, String actionName, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> screenshots, Throwable... rootCauseException)
      Reports a failed element action using explicit action metadata and optional root cause.
      Parameters:
      driver - the active WebDriver instance
      actionName - action name to report
      testData - test data associated with the action
      elementLocator - locator of the target element
      screenshots - optional screenshot attachments
      rootCauseException - optional root cause exceptions

    • createReportMessage

      public String createReportMessage(String actionName, String testData, String elementName, Boolean passFailStatus)
      Builds a user-facing report message for element actions.
      Parameters:
      actionName - action name
      testData - action test data
      elementName - resolved element name
      passFailStatus - action status flag
      Returns:
      formatted report message

    • reportActionResult

      public String reportActionResult(org.openqa.selenium.WebDriver driver, String actionName, String testData, org.openqa.selenium.By elementLocator, List<List<Object>> screenshots, String elementName, Boolean passFailStatus, Throwable... rootCauseException)
      Finalizes action reporting by logging formatted message and attachments.
      Parameters:
      driver - the active WebDriver instance
      actionName - action name, or null to infer from stack trace
      testData - action test data
      elementLocator - locator of the target element
      screenshots - pre-collected screenshots
      elementName - resolved element name
      passFailStatus - action status flag
      rootCauseException - optional root cause exceptions
      Returns:
      final report message