Class TouchActions

java.lang.Object
com.shaft.driver.internal.FluentWebDriverAction
com.shaft.gui.element.TouchActions
public class TouchActions extends FluentWebDriverAction
Provides touch and gesture actions for mobile test automation, including tap, swipe, pinch, and scroll operations on Android and iOS devices.

This class extends FluentWebDriverAction and supports method chaining for fluent test composition. It works with Appium drivers for native, hybrid, and mobile-web applications.

Usage example: 

driver.touch().swipeElementIntoView(targetLocator, TouchActions.SwipeDirection.DOWN)
      .and().element().assertThat(targetLocator).isVisible();
See Also:

  • Constructor Details

    • TouchActions

      public TouchActions()

    • TouchActions

      public TouchActions(org.openqa.selenium.WebDriver driver)

    • TouchActions

      public TouchActions(DriverFactoryHelper helper)

  • Method Details

    • and

      public TouchActions and()
      Description copied from class: FluentWebDriverAction
      Returns this instance to allow fluent (method-chaining) syntax between successive actions. Using .and() improves readability by making multi-step test sequences read like natural language.

      Example: 

      driver.element().type(searchBox, "query")
      .and().browser().captureScreenshot();
      Overrides:
      and in class FluentWebDriverAction
      Returns:
      this FluentWebDriverAction instance, enabling continued method chaining

    • assertThat

      public WebDriverElementValidationsBuilder assertThat(org.openqa.selenium.By elementLocator)

    • verifyThat

      public WebDriverElementValidationsBuilder verifyThat(org.openqa.selenium.By elementLocator)

    • nativeKeyboardKeyPress

      public TouchActions nativeKeyboardKeyPress(TouchActions.KeyboardKeys key)
      Sends a key-press via the device soft keyboard.
      Parameters:
      key - the key that should be pressed
      Returns:
      a self-reference to be used to chain actions

    • nativeKeyboardKeyPress

      public TouchActions nativeKeyboardKeyPress(String key)
      Sends a key-press via the device soft keyboard.
      Parameters:
      key - the key name that should be pressed
      Returns:
      a self-reference to be used to chain actions
      Throws:
      IllegalArgumentException - when the key name is blank or unsupported

    • hideNativeKeyboard

      public TouchActions hideNativeKeyboard()
      Hides the device native soft keyboard.
      Returns:
      a self-reference to be used to chain actions

    • tap

      public TouchActions tap(String elementReferenceScreenshot)
      Taps an element once on a touch-enabled screen
      Parameters:
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      Returns:
      a self-reference to be used to chain actions

    • type

      public TouchActions type(String elementReferenceScreenshot, CharSequence... text)
      Taps an element found by reference image, then types into the active field.
      Parameters:
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      text - one or more CharSequence values to type into the focused element
      Returns:
      a self-reference to be used to chain actions

    • tap

      public TouchActions tap(org.openqa.selenium.By elementLocator)
      Taps an element once on a touch-enabled screen
      Parameters:
      elementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      Returns:
      a self-reference to be used to chain actions

    • tapByCoordinates

      public TouchActions tapByCoordinates(int x, int y)
      Taps viewport coordinates once on a touch-enabled screen.
      Parameters:
      x - viewport x coordinate
      y - viewport y coordinate
      Returns:
      a self-reference to be used to chain actions

    • doubleTap

      public TouchActions doubleTap(org.openqa.selenium.By elementLocator)
      Double-Taps an element on a touch-enabled screen
      Parameters:
      elementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      Returns:
      a self-reference to be used to chain actions

    • longTap

      public TouchActions longTap(org.openqa.selenium.By elementLocator)
      Performs a long-tap on an element to trigger the context menu on a touch-enabled screen
      Parameters:
      elementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      Returns:
      a self-reference to be used to chain actions

    • sendAppToBackground

      public TouchActions sendAppToBackground(int secondsToSpendInTheBackground)
      Send the currently active app to the background, and return after a certain number of seconds.
      Parameters:
      secondsToSpendInTheBackground - number of seconds before returning to the app
      Returns:
      a self-reference to be used to chain actions

    • sendAppToBackground

      public TouchActions sendAppToBackground()
      Send the currently active app to the background and leave the app deactivated.
      Returns:
      a self-reference to be used to chain actions

    • activateAppFromBackground

      public TouchActions activateAppFromBackground(String appPackageName)
      Activates an app that has been previously deactivated or sent to the background.
      Parameters:
      appPackageName - the full name for the app package that you want to activate. for example [com.apple.Preferences] or [io.appium.android.apis]
      Returns:
      a self-reference to be used to chain actions

    • pushFile

      public TouchActions pushFile(String deviceFilePath, String localFilePath)
      Uploads a file to the device or simulator/emulator. This is particularly useful for BrowserStack and other cloud-based mobile testing platforms that require files to be uploaded to the device before they can be used in tests (e.g., for file upload scenarios, camera roll testing, etc.).

      For Android: Uploads the file to the device's external storage or specified path. For iOS: Uploads the file to the app's sandbox container.

      Note: The file path on the device and the actual behavior may vary depending on the platform and testing environment (local Appium vs BrowserStack vs other cloud providers).

      Parameters:
      deviceFilePath - the absolute path where the file should be stored on the device. For Android example: "/sdcard/Download/sample.pdf" or "@com.example.app:id/files/sample.pdf" For iOS example: "@com.example.app/Documents/sample.pdf"
      localFilePath - the absolute or relative path to the file on the local machine that should be uploaded
      Returns:
      a self-reference to be used to chain actions

    • pushFile

      public TouchActions pushFile(String deviceFilePath, File localFile)
      Uploads a file to the device or simulator/emulator using a File object. This is particularly useful for BrowserStack and other cloud-based mobile testing platforms that require files to be uploaded to the device before they can be used in tests (e.g., for file upload scenarios, camera roll testing, etc.).

      For Android: Uploads the file to the device's external storage or specified path. For iOS: Uploads the file to the app's sandbox container.

      Note: The file path on the device and the actual behavior may vary depending on the platform and testing environment (local Appium vs BrowserStack vs other cloud providers).

      Parameters:
      deviceFilePath - the absolute path where the file should be stored on the device. For Android example: "/sdcard/Download/sample.pdf" or "@com.example.app:id/files/sample.pdf" For iOS example: "@com.example.app/Documents/sample.pdf"
      localFile - the File object representing the file on the local machine that should be uploaded
      Returns:
      a self-reference to be used to chain actions

    • pullFile

      public TouchActions pullFile(String deviceFilePath, String localFilePath)
      Downloads a file from the device or simulator/emulator to the local machine. This is useful for retrieving files that were generated or modified during test execution on mobile devices.

      For Android: Downloads the file from the device's file system. For iOS: Downloads the file from the app's sandbox container.

      Note: The file path on the device and the actual behavior may vary depending on the platform and testing environment (local Appium vs BrowserStack vs other cloud providers).

      Parameters:
      deviceFilePath - the absolute path to the file on the device that should be downloaded. For Android example: "/sdcard/Download/sample.pdf" For iOS example: "@com.example.app/Documents/sample.pdf"
      localFilePath - the absolute or relative path where the downloaded file should be saved on the local machine
      Returns:
      a self-reference to be used to chain actions

    • swipeToElement

      public TouchActions swipeToElement(org.openqa.selenium.By sourceElementLocator, org.openqa.selenium.By destinationElementLocator)
      Swipes the sourceElement onto the destinationElement on a touch-enabled screen
      Parameters:
      sourceElementLocator - the locator of the webElement that needs to be swiped (By xpath, id, selector, name ...etc.)
      destinationElementLocator - the locator of the webElement that you'll drop the sourceElement on (By xpath, id, selector, name ...etc.)
      Returns:
      a self-reference to be used to chain actions

    • swipeByOffset

      public TouchActions swipeByOffset(org.openqa.selenium.By elementLocator, int xOffset, int yOffset)
      Swipes an element with the desired x and y offset. Swiping direction is determined by the positive/negative nature of the offset. Swiping destination is determined by the value of the offset.
      Parameters:
      elementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      xOffset - the horizontal offset by which the element should be swiped. positive value is "right" and negative value is "left"
      yOffset - the vertical offset by which the element should be swiped. positive value is "down" and negative value is "up"
      Returns:
      a self-reference to be used to chain actions

    • swipeByCoordinates

      public TouchActions swipeByCoordinates(int startX, int startY, int endX, int endY, int durationMillis)
      Swipes between viewport coordinates on a touch-enabled screen.
      Parameters:
      startX - starting viewport x coordinate
      startY - starting viewport y coordinate
      endX - ending viewport x coordinate
      endY - ending viewport y coordinate
      durationMillis - swipe duration in milliseconds
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(org.openqa.selenium.By targetElementLocator, TouchActions.SwipeDirection swipeDirection)
      Attempts to scroll the element into view in case of native mobile elements.
      Parameters:
      targetElementLocator - the locator of the webElement under test (By xpath, id, selector, name ...etc.)
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(org.openqa.selenium.By targetElementLocator, String swipeDirection)
      Attempts to scroll the element into view in case of native mobile elements.
      Parameters:
      targetElementLocator - the locator of the target element
      swipeDirection - swipe direction name: DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions
      Throws:
      IllegalArgumentException - when the swipe direction is blank or unsupported

    • swipeToEndOfView

      public TouchActions swipeToEndOfView(TouchActions.SwipeDirection swipeDirection)
      Swipes until the current view can no longer scroll in the requested direction.
      Parameters:
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • swipeToEndOfView

      public TouchActions swipeToEndOfView(org.openqa.selenium.By scrollableElementLocator, TouchActions.SwipeDirection swipeDirection)
      Swipes inside a scrollable element until it can no longer scroll in the requested direction.
      Parameters:
      scrollableElementLocator - the locator of the scrollable element, or null for the whole view
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • waitUntilElementIsVisible

      public TouchActions waitUntilElementIsVisible(String elementReferenceScreenshot)
      Waits until a specific element is now visible on the current screen
      Parameters:
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      Returns:
      a self-reference to be used to chain actions

    • waitUntilElementIsNotVisible

      public TouchActions waitUntilElementIsNotVisible(String elementReferenceScreenshot)
      Waits until a specific reference image is no longer visible on the current screen.
      Parameters:
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(String elementReferenceScreenshot, TouchActions.SwipeDirection swipeDirection)
      Attempts to scroll element into view using the new W3C compliant actions for android and ios and AI for image identification
      Parameters:
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(org.openqa.selenium.By scrollableElementLocator, String elementReferenceScreenshot, TouchActions.SwipeDirection swipeDirection)
      Attempts to scroll element into view using the new W3C compliant actions for android and ios and AI for image identification
      Parameters:
      scrollableElementLocator - the locator of the container/view/scrollable webElement that the scroll action will be performed inside
      elementReferenceScreenshot - relative path to the reference image from the local object repository
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(org.openqa.selenium.By scrollableElementLocator, org.openqa.selenium.By targetElementLocator, TouchActions.SwipeDirection swipeDirection)
      Attempts to scroll element into view using the new W3C compliant actions for android and ios
      Parameters:
      scrollableElementLocator - the locator of the container/view/scrollable webElement that the scroll action will be performed inside
      targetElementLocator - the locator of the webElement that you want to scroll to under test (By xpath, id, selector, name ...etc.)
      swipeDirection - SwipeDirection.DOWN, UP, RIGHT, or LEFT
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(String targetText)
      Attempts to scroll element into view using androidUIAutomator
      Parameters:
      targetText - element text to be used to swipe it into view
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(String targetText, TouchActions.SwipeMovement movement)
      Attempts to scroll element into view using androidUIAutomator
      Parameters:
      targetText - element text to be used to swipe it into view
      movement - SwipeMovement.VERTICAL or HORIZONTAL
      Returns:
      a self-reference to be used to chain actions

    • swipeElementIntoView

      public TouchActions swipeElementIntoView(String targetText, String movement)
      Attempts to scroll Android text into view using androidUIAutomator.
      Parameters:
      targetText - target text to be used to swipe it into view
      movement - swipe movement name: VERTICAL or HORIZONTAL
      Returns:
      a self-reference to be used to chain actions
      Throws:
      IllegalArgumentException - when the movement is blank or unsupported

    • rotate

      public TouchActions rotate(org.openqa.selenium.ScreenOrientation orientation)
      Rotate between portrait and landscape modes
      Parameters:
      orientation - ScreenOrientation.LANDSCAPE or PORTRAIT
      Returns:
      a self-reference to be used to chain actions

    • rotate

      public TouchActions rotate(String orientation)
      Rotate between portrait and landscape modes.
      Parameters:
      orientation - orientation name: PORTRAIT or LANDSCAPE
      Returns:
      a self-reference to be used to chain actions
      Throws:
      IllegalArgumentException - when the orientation is blank or unsupported

    • waitForVisible

      public TouchActions waitForVisible(org.openqa.selenium.By elementLocator)
      Waits for a Flutter widget to become visible, using SupportsWaitingForFlutterElements.waitForVisible(WaitParameter) against the Flutter integration driver's own widget tree -- unlike native visibility waits, this works against a bare FlutterView with no native scrollable/overlay. Requires both a Flutter integration driver session and an AppiumBy.FlutterBy locator; anything else fails the action.
      Parameters:
      elementLocator - an AppiumBy.FlutterBy locator identifying the target Flutter widget
      Returns:
      a self-reference to be used to chain actions

    • waitForVisible

      public TouchActions waitForVisible(org.openqa.selenium.By elementLocator, Duration timeout)
      Waits for a Flutter widget to become visible within the given timeout, using SupportsWaitingForFlutterElements.waitForVisible(WaitParameter).
      Parameters:
      elementLocator - an AppiumBy.FlutterBy locator identifying the target Flutter widget
      timeout - the maximum duration to wait, or null to use the Flutter driver default
      Returns:
      a self-reference to be used to chain actions

    • waitForAbsent

      public TouchActions waitForAbsent(org.openqa.selenium.By elementLocator)
      Waits for a Flutter widget to become absent, using SupportsWaitingForFlutterElements.waitForInVisible(WaitParameter) against the Flutter integration driver's own widget tree. Requires both a Flutter integration driver session and an AppiumBy.FlutterBy locator; anything else fails the action.
      Parameters:
      elementLocator - an AppiumBy.FlutterBy locator identifying the target Flutter widget
      Returns:
      a self-reference to be used to chain actions

    • waitForAbsent

      public TouchActions waitForAbsent(org.openqa.selenium.By elementLocator, Duration timeout)
      Waits for a Flutter widget to become absent within the given timeout, using SupportsWaitingForFlutterElements.waitForInVisible(WaitParameter).
      Parameters:
      elementLocator - an AppiumBy.FlutterBy locator identifying the target Flutter widget
      timeout - the maximum duration to wait, or null to use the Flutter driver default
      Returns:
      a self-reference to be used to chain actions

    • performDoubleClick

      public TouchActions performDoubleClick(org.openqa.selenium.By elementLocator)
      Performs a Flutter-native double-click on the target widget, using SupportsGestureOnFlutterElements.performDoubleClick(DoubleClickParameter). Unlike doubleTap(By), this drives Flutter's own synthetic gesture command instead of native touch events, so it works against a bare FlutterView. Requires a Flutter integration driver session; anything else fails the action.
      Parameters:
      elementLocator - the locator of the target Flutter widget
      Returns:
      a self-reference to be used to chain actions

    • performLongPress

      public TouchActions performLongPress(org.openqa.selenium.By elementLocator)
      Performs a Flutter-native long-press on the target widget, using SupportsGestureOnFlutterElements.performLongPress(LongPressParameter). Unlike longTap(By), this drives Flutter's own synthetic gesture command instead of native touch events, so it works against a bare FlutterView. Requires a Flutter integration driver session; anything else fails the action.
      Parameters:
      elementLocator - the locator of the target Flutter widget
      Returns:
      a self-reference to be used to chain actions

    • performDragAndDrop

      public TouchActions performDragAndDrop(org.openqa.selenium.By sourceElementLocator, org.openqa.selenium.By targetElementLocator)
      Performs a Flutter-native drag-and-drop between two widgets, using SupportsGestureOnFlutterElements.performDragAndDrop(DragAndDropParameter). Unlike swipeToElement(By, By), this drives Flutter's own synthetic gesture command instead of native touch events, so it works against a bare FlutterView. Requires a Flutter integration driver session; anything else fails the action.
      Parameters:
      sourceElementLocator - the locator of the widget to drag
      targetElementLocator - the locator of the widget to drop onto
      Returns:
      a self-reference to be used to chain actions

    • injectMockImage

      public String injectMockImage(File image)
      Injects a mock camera image into the Flutter application, using SupportsFlutterCameraMocking.injectMockImage(File). Useful for QR/scanner flow testing. Requires a Flutter integration driver session; anything else fails the action and returns null.

      Intentionally breaks the fluent chain (like AlertActions.getAlertText()): the returned image id is required by activateInjectedImage(String).

      Parameters:
      image - the image file to inject (must be in PNG format)
      Returns:
      a unique id for the injected image, or null if the action failed

    • activateInjectedImage

      public TouchActions activateInjectedImage(String imageId)
      Activates a previously injected mock camera image, using SupportsFlutterCameraMocking.activateInjectedImage(String). Requires a Flutter integration driver session; anything else fails the action.
      Parameters:
      imageId - the id returned by injectMockImage(File)
      Returns:
      a self-reference to be used to chain actions

    • saveSessionCapabilities

      public TouchActions saveSessionCapabilities(String filePath)
      Saves the active Appium session capabilities to a JSON file, so a later test run can reuse the same device/app configuration without re-resolving it.

      Example: 

      driver.touch().saveSessionCapabilities("target/mobile-session-cache/device.json");
      Parameters:
      filePath - target JSON file path
      Returns:
      a self-reference to be used to chain actions

    • loadSessionCapabilities

      public static org.openqa.selenium.MutableCapabilities loadSessionCapabilities(String filePath)
      Loads previously saved Appium session capabilities from a JSON file.

      This is a static method because capabilities must be known before a driver session exists. Example: 

      MutableCapabilities capabilities = TouchActions.loadSessionCapabilities("target/mobile-session-cache/device.json");
SHAFT.GUI.WebDriver driver = new SHAFT.GUI.WebDriver(DriverFactory.DriverType.APPIUM_MOBILE_NATIVE, capabilities);
      Parameters:
      filePath - source JSON file path
      Returns:
      capabilities restored from the file

    • saveAppState

      public TouchActions saveAppState(String filePath)
      Saves a snapshot of the current mobile app state (active app, context, orientation, window size) to a JSON file.

      Example: 

      driver.touch().saveAppState("target/mobile-session-cache/app-state.json");
      Parameters:
      filePath - target JSON file path
      Returns:
      a self-reference to be used to chain actions

    • loadAppState

      public TouchActions loadAppState(String filePath)
      Restores what is restorable of a previously saved mobile app-state snapshot on the current live session: re-activates the app, switches context, and rotates the device when supported. Unsupported restore steps are skipped silently.

      Example: 

      driver.touch().loadAppState("target/mobile-session-cache/app-state.json");
      Parameters:
      filePath - source JSON file path
      Returns:
      a self-reference to be used to chain actions

    • pinchToZoom

      public TouchActions pinchToZoom(TouchActions.ZoomDirection zoomDirection)
      Attempts to zoom the current screen IN/ OUT in case of zoom enabled screen.
      Parameters:
      zoomDirection - ZoomDirection.IN or OUT
      Returns:
      a self-reference to be used to chain actions