Skip to main content

Touch Actions

SHAFT provides touch action methods for mobile app automation. Access them through driver.touch().

For trust-gated natural-language touch workflows such as driver.act("tap Continue"), see Natural Language Actions.

Tap Actions​

tap()​

Taps an element once on a touch-enabled screen.

TapExample.java
By loginButton = By.id("login_btn");
driver.touch().tap(loginButton);

Reference-image taps use shaft-visual to find the image in the current viewport, then execute a Selenium/Appium pointer action at the matched center:

ImageTapExample.java
driver.touch().tap("src/test/resources/dynamicObjectRepository/login-button.png");

type()​

Taps a field found by reference image, then types into the focused field.

ImageTypeExample.java
driver.touch().type("src/test/resources/dynamicObjectRepository/search-field.png", "SHAFT Engine");

doubleTap()​

Double-taps an element on a touch-enabled screen.

DoubleTapExample.java
By imageElement = By.id("photo");
driver.touch().doubleTap(imageElement);

longTap()​

Performs a long press on an element to trigger the context menu.

LongTapExample.java
By listItem = By.id("item_1");
driver.touch().longTap(listItem);

Swipe Actions​

swipeToElement()​

Swipes from a source element to a destination element.

SwipeToElementExample.java
By sourceElement = By.id("card_1");
By destinationElement = By.id("drop_zone");
driver.touch().swipeToElement(sourceElement, destinationElement);

swipeByOffset()​

Swipes an element by a specified horizontal and vertical offset. Positive x-offset swipes right, negative swipes left. Positive y-offset swipes down, negative swipes up.

SwipeByOffsetExample.java
By element = By.id("slider");
driver.touch().swipeByOffset(element, 200, 0); // swipe right by 200px

swipeElementIntoView()​

Scrolls until the target element is visible. Useful for finding elements in long scrollable lists.

SwipeIntoViewExample.java
By targetElement = By.id("item_at_bottom");
driver.touch().swipeElementIntoView(targetElement, TouchActions.SwipeDirection.DOWN);

You can also specify a scrollable container:

SwipeIntoViewContainerExample.java
By scrollableContainer = By.id("list_view");
By targetElement = By.id("item_50");
driver.touch().swipeElementIntoView(scrollableContainer, targetElement, TouchActions.SwipeDirection.DOWN);

Image-path overloads scroll until the reference image is visible in the viewport. Selenium sessions use headless-safe page or element scrolling; Appium native sessions use Appium scroll gestures.

ImageSwipeIntoViewExample.java
driver.touch().swipeElementIntoView(
        "src/test/resources/dynamicObjectRepository/pay-now.png",
        TouchActions.SwipeDirection.DOWN);

swipeToEndOfView()​

Swipes until the current Appium view can no longer scroll in the requested direction.

SwipeToEndExample.java
driver.touch().swipeToEndOfView(TouchActions.SwipeDirection.DOWN);

You can also limit the gesture to a scrollable container:

SwipeContainerToEndExample.java
By scrollableContainer = By.id("list_view");
driver.touch().swipeToEndOfView(scrollableContainer, TouchActions.SwipeDirection.UP);

Keyboard Actions​

nativeKeyboardKeyPress()​

Sends a key press via the device soft keyboard.

KeyPressExample.java
driver.touch().nativeKeyboardKeyPress(TouchActions.KeyboardKeys.ENTER);

hideNativeKeyboard()​

Hides the device native soft keyboard.

HideKeyboardExample.java
driver.touch().hideNativeKeyboard();

Zoom Actions​

pinchToZoom()​

Zooms the current screen in or out.

PinchToZoomExample.java
driver.touch().pinchToZoom(TouchActions.ZoomDirection.IN);
driver.touch().pinchToZoom(TouchActions.ZoomDirection.OUT);

App Management​

sendAppToBackground()​

Sends the currently active app to the background.

BackgroundAppExample.java
// Send to background and return after 5 seconds
driver.touch().sendAppToBackground(5);

// Send to background and leave deactivated
driver.touch().sendAppToBackground();

activateAppFromBackground()​

Activates an app that has been previously deactivated or sent to the background.

ActivateAppExample.java
driver.touch().activateAppFromBackground("com.example.myapp");

Visual Element Detection​

Image-path touch actions support cropped reference screenshots captured at a different DPI or display scale than the current app screenshot when shaft-visual is on the runtime classpath.

waitUntilElementIsVisible()​

Waits until a specific element is visible on the screen using image-based detection.

WaitForVisualElement.java
driver.touch().waitUntilElementIsVisible("path/to/reference-screenshot.png");

waitUntilElementIsNotVisible()​

Waits until a reference image is no longer visible on the screen.

WaitForVisualElementToDisappear.java
driver.touch().waitUntilElementIsNotVisible("path/to/reference-screenshot.png");

Complete Example​

MobileTouchActionsDemo.java
import com.shaft.driver.SHAFT;
import org.openqa.selenium.By;
import org.testng.annotations.*;

public class MobileTouchActionsDemo {
    private SHAFT.GUI.WebDriver driver;

    @BeforeMethod
    public void setup() {
        SHAFT.Properties.platform.set().targetPlatform("ANDROID");
        SHAFT.Properties.mobile.set().automationName("UiAutomator2");
        driver = new SHAFT.GUI.WebDriver();
    }

    @Test
    public void testTouchActions() {
        By usernameField = By.accessibilityId("username");
        By passwordField = By.accessibilityId("password");
        By loginButton = By.accessibilityId("login");

        driver.touch().tap(usernameField);
        driver.element().type(usernameField, "admin");
        driver.touch().tap(passwordField);
        driver.element().type(passwordField, "password");
        driver.touch().tap(loginButton);
    }

    @AfterMethod
    public void teardown() {
        driver.quit();
    }
}

Coordinates, files, app state and Flutter helpers​

MethodWhat it does
tapByCoordinates(int x, int y)Taps viewport coordinates once.
swipeByCoordinates(int startX, int startY, int endX, int endY, int durationMillis)Swipes between two viewport coordinates over the given duration.
pushFile(String deviceFilePath, String localFilePath) / pushFile(String deviceFilePath, File localFile)Uploads a local file to the device, emulator or simulator.
pullFile(String deviceFilePath, String localFilePath)Downloads a file from the device to the local machine.
saveAppState(String filePath)Saves a JSON snapshot of the current app state (active app, context, orientation, window size).
loadAppState(String filePath)Restores what can be restored from a saved app-state snapshot on the live session.
saveSessionCapabilities(String filePath)Saves the active Appium session capabilities to JSON so a later run can reuse the same device setup.
loadSessionCapabilities(String filePath)Loads previously saved Appium session capabilities from JSON.
performDoubleClick(By), performLongPress(By), performDragAndDrop(By source, By target)Flutter-native gestures on widgets, using the Flutter driver.
waitForVisible(By) / waitForVisible(By, Duration)Waits for a Flutter widget to become visible.
waitForAbsent(By) / waitForAbsent(By, Duration)Waits for a Flutter widget to disappear.
injectMockImage(File image) / activateInjectedImage(String imageId)Injects a mock camera image into a Flutter app and activates it.
driver.touch().tapByCoordinates(200, 640)
      .pushFile("/sdcard/Download/data.json", "src/test/resources/data.json")
      .saveAppState("target/app-state.json");