xref: /platform_testing/libraries/app-helpers/spectatio/spectatio-util/src/android/platform/spectatio/utils/SpectatioUiUtil.java

/*
 * Copyright (C) 2022 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.platform.spectatio.utils;

import android.app.Instrumentation;
import android.graphics.Point;
import android.graphics.Rect;
import android.os.RemoteException;
import android.os.SystemClock;
import android.platform.spectatio.constants.JsonConfigConstants;
import android.platform.spectatio.exceptions.MissingUiElementException;
import android.util.Log;
import android.view.KeyEvent;

import androidx.test.uiautomator.By;
import androidx.test.uiautomator.BySelector;
import androidx.test.uiautomator.Direction;
import androidx.test.uiautomator.UiDevice;
import androidx.test.uiautomator.UiObject2;
import androidx.test.uiautomator.Until;

import com.google.common.base.Strings;
import com.google.escapevelocity.Template;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;

public class SpectatioUiUtil {
    private static final String LOG_TAG = SpectatioUiUtil.class.getSimpleName();

    private static SpectatioUiUtil sSpectatioUiUtil = null;

    private static final int SHORT_UI_RESPONSE_WAIT_MS = 1000;
    private static final int LONG_UI_RESPONSE_WAIT_MS = 5000;
    private static final int TEN_SECONDS_WAIT = 10000;
    private static final int EXTRA_LONG_UI_RESPONSE_WAIT_MS = 15000;
    private static final int LONG_PRESS_DURATION_MS = 5000;
    private static final int MAX_SCROLL_COUNT = 100;
    private static final int MAX_SWIPE_STEPS = 10;
    private static final float SCROLL_PERCENT = 1.0f;
    private static final float SWIPE_PERCENT = 1.0f;

    private int mWaitTimeAfterScroll = 5; // seconds
    private int mScrollMargin = 4;

    private UiDevice mDevice;

    public enum SwipeDirection {
        TOP_TO_BOTTOM,
        BOTTOM_TO_TOP,
        LEFT_TO_RIGHT,
        RIGHT_TO_LEFT
    }

    /**
     * Defines the swipe fraction, allowing for a swipe to be performed from a 5-pad distance, a
     * quarter, half, three-quarters of the screen, or the full screen.
     *
     * <p>DEFAULT: Swipe from one side of the screen to another side, with a 5-pad distance from the
     * edge.
     *
     * <p>QUARTER: Swipe from one side, a quarter of the distance of the entire screen away from the
     * edge, to the other side.
     *
     * <p>HALF: Swipe from the center of the screen to the other side.
     *
     * <p>THREEQUARTER: Swipe from one side, three-quarters of the distance of the entire screen
     * away from the edge, to the other side.
     *
     * <p>FULL: Swipe from one edge of the screen to the other edge.
     */
    public enum SwipeFraction {
        DEFAULT,
        QUARTER,
        HALF,
        THREEQUARTER,
        FULL,
    }

    /**
     * Defines the swipe speed based on the number of steps.
     *
     * <p><a
     * href="https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#swipe(int,int,int,int,int)">UiDevie#Swipe</a>
     * performs a swipe from one coordinate to another using the number of steps to determine
     * smoothness and speed. Each step execution is throttled to 5ms per step. So for a 100 steps,
     * the swipe will take about 1/2 second to complete.
     */
    public enum SwipeSpeed {
        NORMAL(200), // equals to 1000ms in duration.
        SLOW(1000), // equals to 5000ms in duration.
        FAST(50), // equals to 250ms in duration.
        FLING(20); // equals to 100ms in duration.

        final int mNumSteps;

        SwipeSpeed(int numOfSteps) {
            this.mNumSteps = numOfSteps;
        }
    }

    private SpectatioUiUtil(UiDevice mDevice) {
        this.mDevice = mDevice;
    }

    public static SpectatioUiUtil getInstance(UiDevice mDevice) {
        if (sSpectatioUiUtil == null) {
            sSpectatioUiUtil = new SpectatioUiUtil(mDevice);
        }
        return sSpectatioUiUtil;
    }

    /**
     * Initialize a UiDevice for the given instrumentation, then initialize Spectatio for that
     * device. If Spectatio has already been initialized, return the previously initialized
     * instance.
     */
    public static SpectatioUiUtil getInstance(Instrumentation instrumentation) {
        return getInstance(UiDevice.getInstance(instrumentation));
    }

    /** Sets the scroll margin and wait time after the scroll */
    public void addScrollValues(Integer scrollMargin, Integer waitTime) {
        this.mScrollMargin = scrollMargin;
        this.mWaitTimeAfterScroll = waitTime;
    }

    public boolean pressBack() {
        return mDevice.pressBack();
    }

    public boolean pressHome() {
        return mDevice.pressHome();
    }

    public boolean pressKeyCode(int keyCode) {
        return mDevice.pressKeyCode(keyCode);
    }

    public boolean pressPower() {
        return pressKeyCode(KeyEvent.KEYCODE_POWER);
    }

    public boolean longPress(UiObject2 uiObject) {
        if (!isValidUiObject(uiObject)) {
            Log.e(
                    LOG_TAG,
                    "Cannot Long Press UI Object; Provide a valid UI Object, currently it is"
                            + " NULL.");
            return false;
        }
        if (!uiObject.isLongClickable()) {
            Log.e(
                    LOG_TAG,
                    "Cannot Long Press UI Object; Provide a valid UI Object, "
                            + "current UI Object is not long clickable.");
            return false;
        }
        uiObject.longClick();
        wait1Second();
        return true;
    }

    public boolean longPressKey(int keyCode) {
        try {
            // Use English Locale because ADB Shell command does not depend on Device UI
            mDevice.executeShellCommand(
                    String.format(Locale.ENGLISH, "input keyevent --longpress %d", keyCode));
            wait1Second();
            return true;
        } catch (IOException e) {
            // Ignore
            Log.e(
                    LOG_TAG,
                    String.format(
                            "Failed to long press key code: %d, Error: %s",
                            keyCode, e.getMessage()));
        }
        return false;
    }

    public boolean longPressPower() {
        return longPressKey(KeyEvent.KEYCODE_POWER);
    }

    public boolean longPressScreenCenter() {
        Rect bounds = getScreenBounds();
        int xCenter = bounds.centerX();
        int yCenter = bounds.centerY();
        try {
            // Click method in UiDevice only takes x and y co-ordintes to tap,
            // so it can be clicked but cannot be pressed for long time
            // Use ADB command to Swipe instead (because UiDevice swipe method don't take duration)
            // i.e. simulate long press by swiping from
            // center of screen to center of screen (i.e. same points) for long duration
            // Use English Locale because ADB Shell command does not depend on Device UI
            mDevice.executeShellCommand(
                    String.format(
                            Locale.ENGLISH,
                            "input swipe %d %d %d %d %d",
                            xCenter,
                            yCenter,
                            xCenter,
                            yCenter,
                            LONG_PRESS_DURATION_MS));
            wait1Second();
            return true;
        } catch (IOException e) {
            // Ignore
            Log.e(
                    LOG_TAG,
                    String.format(
                            "Failed to long press on screen center. Error: %s", e.getMessage()));
        }
        return false;
    }

    public void wakeUp() {
        try {
            mDevice.wakeUp();
        } catch (RemoteException ex) {
            throw new IllegalStateException("Failed to wake up device.", ex);
        }
    }

    public void clickAndWait(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Click");
        uiObject.click();
        wait1Second();
    }

    public void clickAndWait(UiObject2 uiObject, int waitTime) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Click");
        uiObject.click();
        waitNSeconds(waitTime);
    }

    /**
     * Click and wait until new window opens, wait for the specified time. Usecases * Clicking a
     * object that opens a new window * Navigating between screens * Clicking an object that can
     * open a popup
     */
    public void clickAndWaitUntilNewWindowAppears(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Click");
        uiObject.clickAndWait(Until.newWindow(), EXTRA_LONG_UI_RESPONSE_WAIT_MS);
    }

    /**
     * Click at a specific location in the UI, and wait one second
     *
     * @param location Where to click
     */
    public void clickAndWait(Point location) {
        mDevice.click(location.x, location.y);
        wait1Second();
    }

    public void waitForIdle() {
        mDevice.waitForIdle();
    }

    public void wait1Second() {
        waitNSeconds(SHORT_UI_RESPONSE_WAIT_MS);
    }

    public void wait5Seconds() {
        waitNSeconds(LONG_UI_RESPONSE_WAIT_MS);
    }

    /** Waits for 15 seconds */
    public void wait15Seconds() {
        waitNSeconds(EXTRA_LONG_UI_RESPONSE_WAIT_MS);
    }

    public void waitNSeconds(int waitTime) {
        SystemClock.sleep(waitTime);
    }

    /**
     * Executes a shell command on device, and return the standard output in string.
     *
     * @param command the command to run
     * @return the standard output of the command, or empty string if failed without throwing an
     *     IOException
     */
    public String executeShellCommand(String command) {
        validateText(command, /* type= */ "Command");
        String populatedCommand = populateShellCommand(command);
        Log.d(
                LOG_TAG,
                String.format(
                        "Initial command: %s. Populated command: %s",
                        command, populatedCommand));
        try {
            return mDevice.executeShellCommand(populatedCommand);
        } catch (IOException e) {
            // ignore
            Log.e(
                    LOG_TAG,
                    String.format(
                            "The shell command failed to run: %s, Error: %s",
                            populatedCommand, e.getMessage()));
            return "";
        }
    }

    private String populateShellCommand(String command) {
        String populatedCommand = command;

        // Map of supported substitutions
        Map<String, String> vars = new HashMap<>();
        try {
            vars.put("user_id", mDevice.executeShellCommand("am get-current-user"));
        } catch (IOException e) {
            Log.e(LOG_TAG, "Could not execute `am get-current-user` to retrieve user id");
        }

        try (InputStreamReader reader =
                new InputStreamReader(
                        new ByteArrayInputStream(command.getBytes(StandardCharsets.UTF_8)))) {
            Template template = Template.parseFrom(reader);
            populatedCommand = template.evaluate(vars);
            Log.d(
                    LOG_TAG,
                    String.format(
                            "Initial command: %s. Populated command: %s",
                            command, populatedCommand));
        } catch (IOException e) {
            Log.e(
                    LOG_TAG,
                    String.format(
                            "Error populating the shell command template %s, Error: %s",
                            command, e.getMessage()));
        }
        return populatedCommand;
    }

    /** Find and return the UI Object that matches the given selector */
    public UiObject2 findUiObject(BySelector selector) {
        validateSelector(selector, /* action= */ "Find UI Object");
        UiObject2 uiObject = mDevice.wait(Until.findObject(selector), LONG_UI_RESPONSE_WAIT_MS);
        return uiObject;
    }

    /** Find and return the UI Objects that matches the given selector */
    public List<UiObject2> findUiObjects(BySelector selector) {
        validateSelector(selector, /* action= */ "Find UI Object");
        List<UiObject2> uiObjects =
                mDevice.wait(Until.findObjects(selector), LONG_UI_RESPONSE_WAIT_MS);
        return uiObjects;
    }

    /**
     * Find the UI Object that matches the given text string.
     *
     * @param text Text to search on device UI. It should exactly match the text visible on UI.
     */
    public UiObject2 findUiObject(String text) {
        validateText(text, /* type= */ "Text");
        return findUiObject(By.text(text));
    }

    /**
     * Find the UI Object in given element.
     *
     * @param uiObject Find the ui object(selector) in this element.
     * @param selector Find this ui object in the given element.
     */
    public UiObject2 findUiObjectInGivenElement(UiObject2 uiObject, BySelector selector) {
        validateUiObjectAndThrowIllegalArgumentException(
                uiObject, /* action= */ "Find UI object in given element");
        validateSelector(selector, /* action= */ "Find UI object in given element");
        return uiObject.findObject(selector);
    }

    /**
     * Waits for a UI element to appear within a specified timeout.
     * Relpacement of findUiObject().
     * Reference: https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#wait
     *
     * @param selector The BySelector used to locate the element.
     * @param timeout  The maximum time to wait in milliseconds.
     * @return The UiObject2 representing the found element, or null if it's not found within the timeout.
     */
    public UiObject2 waitForUiObject(BySelector selector, int timeout) {
        Log.i(LOG_TAG, "Waiting for UI element: " + selector);
        validateSelector(selector, /* action= */ "Find UI Object");

        UiObject2 uiObject = mDevice.wait(Until.findObject(selector), timeout);
        if (uiObject == null) {
            Log.w(LOG_TAG, "UI element not found within timeout: " + selector);
        }

        return uiObject;
    }

    /**
     * Waits for a UI element to appear using the default timeout.
     *
     * @param selector The BySelector used to locate the element.
     * @return The UiObject2 representing the found element, or null if it's not found within the default timeout.
     */
    public UiObject2 waitForUiObject(BySelector selector) {
        return waitForUiObject(selector, TEN_SECONDS_WAIT);
    }

    /**
     * Checks if given text is available on the Device UI. The text should be exactly same as seen
     * on the screen.
     *
     * <p>Given text will be searched on current screen. This method will not scroll on the screen
     * to check for given text.
     *
     * @param text Text to search on device UI
     * @return Returns True if the text is found, else return False.
     */
    public boolean hasUiElement(String text) {
        validateText(text, /* type= */ "Text");
        return hasUiElement(By.text(text));
    }

    /**
     * Scroll using forward and backward buttons on device screen and check if the given text is
     * present.
     *
     * <p>Method throws {@link MissingUiElementException} if the given button selectors are not
     * available on the Device UI.
     *
     * @param forward {@link BySelector} for the button to use for scrolling forward/down.
     * @param backward {@link BySelector} for the button to use for scrolling backward/up.
     * @param text Text to search on device UI
     * @return Returns True if the text is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(
            BySelector forward, BySelector backward, String text) throws MissingUiElementException {
        return scrollAndFindUiObject(forward, backward, text) != null;
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and check if the given
     * text is present on Device UI.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollAndCheckIfUiElementExist(BySelector scrollableSelector, String text, boolean
     * isVertical)} by passing isVertical = false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} used for scrolling on device UI
     * @param text Text to search on device UI
     * @return Returns True if the text is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(BySelector scrollableSelector, String text)
            throws MissingUiElementException {
        return scrollAndCheckIfUiElementExist(scrollableSelector, text, /* isVertical= */ true);
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and check if the given
     * text is present on Device UI.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} used for scrolling on device UI
     * @param text Text to search on device UI
     * @param isVertical For vertical scrolling, use isVertical = true and For Horizontal scrolling,
     *     use isVertical = false.
     * @return Returns True if the text is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(
            BySelector scrollableSelector, String text, boolean isVertical)
            throws MissingUiElementException {
        return scrollAndFindUiObject(scrollableSelector, text, isVertical) != null;
    }

    /**
     * Checks if given target is available on the Device UI.
     *
     * <p>Given target will be searched on current screen. This method will not scroll on the screen
     * to check for given target.
     *
     * @param target {@link BySelector} to search on device UI
     * @return Returns True if the target is found, else return False.
     */
    public boolean hasUiElement(BySelector target) {
        validateSelector(target, /* action= */ "Check For UI Object");
        return mDevice.hasObject(target);
    }

    /**
     * Scroll using forward and backward buttons on device screen and check if the given target is
     * present.
     *
     * <p>Method throws {@link MissingUiElementException} if the given button selectors are not
     * available on the Device UI.
     *
     * @param forward {@link BySelector} for the button to use for scrolling forward/down.
     * @param backward {@link BySelector} for the button to use for scrolling backward/up.
     * @param target {@link BySelector} to search on device UI
     * @return Returns True if the target is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(
            BySelector forward, BySelector backward, BySelector target)
            throws MissingUiElementException {
        return scrollAndFindUiObject(forward, backward, target) != null;
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and check if the target
     * UI Element is present.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollAndCheckIfUiElementExist(BySelector scrollableSelector, BySelector target, boolean
     * isVertical)} by passing isVertical = false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} used for scrolling on device UI
     * @param target {@link BySelector} to search on device UI
     * @return Returns True if the target is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(BySelector scrollableSelector, BySelector target)
            throws MissingUiElementException {
        return scrollAndCheckIfUiElementExist(scrollableSelector, target, /* isVertical= */ true);
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and check if the target
     * UI Element is present.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} used for scrolling on device UI
     * @param target {@link BySelector} to search on device UI
     * @param isVertical For vertical scrolling, use isVertical = true and For Horizontal scrolling,
     *     use isVertical = false.
     * @return Returns True if the target is found, else return False.
     */
    public boolean scrollAndCheckIfUiElementExist(
            BySelector scrollableSelector, BySelector target, boolean isVertical)
            throws MissingUiElementException {
        return scrollAndFindUiObject(scrollableSelector, target, isVertical) != null;
    }

    public boolean hasPackageInForeground(String packageName) {
        validateText(packageName, /* type= */ "Package");
        return mDevice.hasObject(By.pkg(packageName).depth(0));
    }

    /** Click at the specified location on the device */
    public void click(int x, int y) throws IOException {
        mDevice.click(x, y);
    }

    public void swipeUp() {
        // Swipe Up From bottom of screen to the top in one step
        swipe(SwipeDirection.BOTTOM_TO_TOP, /*numOfSteps*/ MAX_SWIPE_STEPS);
    }

    public void swipeDown() {
        // Swipe Down From top of screen to the bottom in one step
        swipe(SwipeDirection.TOP_TO_BOTTOM, /*numOfSteps*/ MAX_SWIPE_STEPS);
    }

    public void swipeRight() {
        // Swipe Right From left of screen to the right in one step
        swipe(SwipeDirection.LEFT_TO_RIGHT, /*numOfSteps*/ MAX_SWIPE_STEPS);
    }

    public void swipeLeft() {
        // Swipe Left From right of screen to the left in one step
        swipe(SwipeDirection.RIGHT_TO_LEFT, /*numOfSteps*/ MAX_SWIPE_STEPS);
    }

    public void swipe(SwipeDirection swipeDirection, int numOfSteps) {
        swipe(swipeDirection, numOfSteps, SwipeFraction.DEFAULT);
    }

    /**
     * Perform a swipe gesture
     *
     * @param swipeDirection The direction to perform the swipe in
     * @param numOfSteps How many steps the swipe will take
     * @param swipeFraction The fraction of the screen to swipe across
     */
    public void swipe(SwipeDirection swipeDirection, int numOfSteps, SwipeFraction swipeFraction) {
        Rect bounds = getScreenBounds();

        List<Point> swipePoints = getPointsToSwipe(bounds, swipeDirection, swipeFraction);

        Point startPoint = swipePoints.get(0);
        Point finishPoint = swipePoints.get(1);

        // Swipe from start pont to finish point in given number of steps
        mDevice.swipe(startPoint.x, startPoint.y, finishPoint.x, finishPoint.y, numOfSteps);
    }

    /**
     * Perform a swipe gesture
     *
     * @param swipeDirection The direction to perform the swipe in
     * @param swipeSpeed How fast to swipe
     */
    public void swipe(SwipeDirection swipeDirection, SwipeSpeed swipeSpeed) throws IOException {
        swipe(swipeDirection, swipeSpeed.mNumSteps);
    }

    /**
     * Perform a swipe gesture
     *
     * @param swipeDirection The direction to perform the swipe in
     * @param swipeSpeed How fast to swipe
     * @param swipeFraction The fraction of the screen to swipe across
     */
    public void swipe(
            SwipeDirection swipeDirection, SwipeSpeed swipeSpeed, SwipeFraction swipeFraction)
            throws IOException {
        swipe(swipeDirection, swipeSpeed.mNumSteps, swipeFraction);
    }

    private List<Point> getPointsToSwipe(
            Rect bounds, SwipeDirection swipeDirection, SwipeFraction swipeFraction) {
        int xStart;
        int yStart;
        int xFinish;
        int yFinish;

        int padXStart = 5;
        int padXFinish = 5;
        int padYStart = 5;
        int padYFinish = 5;

        switch (swipeFraction) {
            case FULL:
                padXStart = 0;
                padXFinish = 0;
                padYStart = 0;
                padYFinish = 0;
                break;
            case QUARTER:
                padXStart = bounds.right / 4;
                padYStart = bounds.bottom / 4;
                break;
            case HALF:
                padXStart = bounds.centerX();
                padYStart = bounds.centerY();
                break;
            case THREEQUARTER:
                padXStart = bounds.right / 4 * 3;
                padYStart = bounds.bottom / 4 * 3;
                break;
            case DEFAULT:
                break; // handled above the switch.
        }

        switch (swipeDirection) {
                // Scroll left = swipe from left to right.
            case LEFT_TO_RIGHT:
                xStart = bounds.left + padXStart;
                xFinish = bounds.right - padXFinish;
                yStart = bounds.centerY();
                yFinish = bounds.centerY();
                break;
                // Scroll right = swipe from right to left.
            case RIGHT_TO_LEFT:
                xStart = bounds.right - padXStart;
                xFinish = bounds.left + padXFinish;
                yStart = bounds.centerY();
                yFinish = bounds.centerY();
                break;
                // Scroll up = swipe from top to bottom.
            case TOP_TO_BOTTOM:
                xStart = bounds.centerX();
                xFinish = bounds.centerX();
                yStart = bounds.top + padYStart;
                yFinish = bounds.bottom - padYFinish;
                break;
                // Scroll down = swipe to bottom to top.
            case BOTTOM_TO_TOP:
            default:
                xStart = bounds.centerX();
                xFinish = bounds.centerX();
                yStart = bounds.bottom - padYStart;
                yFinish = bounds.top + padYFinish;
                break;
        }

        List<Point> swipePoints = new ArrayList<>();
        // Start Point
        swipePoints.add(new Point(xStart, yStart));
        // Finish Point
        swipePoints.add(new Point(xFinish, yFinish));

        return swipePoints;
    }

    /** Returns a Rect representing the bounds of the screen */
    public Rect getScreenBounds() {
        return new Rect(
            /* left= */ 0,
            /* top= */ 0,
            /* right= */ mDevice.getDisplayWidth(),
            /* bottom= */ mDevice.getDisplayHeight());
    }

    public void swipeRight(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Swipe Right");
        uiObject.swipe(Direction.RIGHT, SWIPE_PERCENT);
    }

    public void swipeLeft(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Swipe Left");
        uiObject.swipe(Direction.LEFT, SWIPE_PERCENT);
    }

    public void swipeUp(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Swipe Up");
        uiObject.swipe(Direction.UP, SWIPE_PERCENT);
    }

    public void swipeDown(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Swipe Down");
        uiObject.swipe(Direction.DOWN, SWIPE_PERCENT);
    }

    public void setTextForUiElement(UiObject2 uiObject, String text) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Set Text");
        validateText(text, /* type= */ "Text");
        uiObject.setText(text);
    }

    public String getTextForUiElement(UiObject2 uiObject) {
        validateUiObjectAndThrowIllegalArgumentException(uiObject, /* action= */ "Get Text");
        return uiObject.getText();
    }

    /**
     * Scroll on the device screen using forward or backward buttons.
     *
     * <p>Pass Forward/Down Button Selector to scroll forward. Pass Backward/Up Button Selector to
     * scroll backward. Method throws {@link MissingUiElementException} if the given button is not
     * available on the Device UI.
     *
     * @param scrollButtonSelector {@link BySelector} for the button to use for scrolling.
     * @return Method returns true for successful scroll else returns false
     */
    public boolean scrollUsingButton(BySelector scrollButtonSelector)
            throws MissingUiElementException {
        validateSelector(scrollButtonSelector, /* action= */ "Scroll Using Button");
        UiObject2 scrollButton = findUiObject(scrollButtonSelector);
        validateUiObjectAndThrowMissingUiElementException(
                scrollButton, scrollButtonSelector, /* action= */ "Scroll Using Button");

        String previousView = getViewHierarchy();
        if (!scrollButton.isEnabled()) {
            // Already towards the end, cannot scroll
            return false;
        }

        clickAndWait(scrollButton);

        String currentView = getViewHierarchy();

        // If current view is same as previous view, scroll did not work, so return false
        return !currentView.equals(previousView);
    }

    /**
     * Scroll using forward and backward buttons on device screen and find the text.
     *
     * <p>Method throws {@link MissingUiElementException} if the given button selectors are not
     * available on the Device UI.
     *
     * @param forward {@link BySelector} for the button to use for scrolling forward/down.
     * @param backward {@link BySelector} for the button to use for scrolling backward/up.
     * @param text Text to search on device UI. It should be exactly same as visible on device UI.
     * @return {@link UiObject2} for given text will be returned. It returns NULL if given text is
     *     not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(BySelector forward, BySelector backward, String text)
            throws MissingUiElementException {
        validateText(text, /* type= */ "Text");
        return scrollAndFindUiObject(forward, backward, By.text(text));
    }

    /**
     * Scroll using forward and backward buttons on device screen and find the target UI Element.
     *
     * <p>Method throws {@link MissingUiElementException} if the given button selectors are not
     * available on the Device UI.
     *
     * @param forward {@link BySelector} for the button to use for scrolling forward/down.
     * @param backward {@link BySelector} for the button to use for scrolling backward/up.
     * @param target {@link BySelector} for UI Element to search on device UI.
     * @return {@link UiObject2} for target UI Element will be returned. It returns NULL if given
     *     target is not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(
            BySelector forward, BySelector backward, BySelector target)
            throws MissingUiElementException {
        validateSelector(forward, /* action= */ "Scroll Forward");
        validateSelector(backward, /* action= */ "Scroll Backward");
        validateSelector(target, /* action= */ "Find UI Object");
        // Find the object on current page
        UiObject2 uiObject = findUiObject(target);
        if (isValidUiObject(uiObject)) {
            return uiObject;
        }
        scrollToBeginning(backward);
        return scrollForwardAndFindUiObject(forward, target);
    }

    private UiObject2 scrollForwardAndFindUiObject(BySelector forward, BySelector target)
            throws MissingUiElementException {
        UiObject2 uiObject = findUiObject(target);
        if (isValidUiObject(uiObject)) {
            return uiObject;
        }
        int scrollCount = 0;
        boolean canScroll = true;
        while (!isValidUiObject(uiObject) && canScroll && scrollCount < MAX_SCROLL_COUNT) {
            canScroll = scrollUsingButton(forward);
            scrollCount++;
            uiObject = findUiObject(target);
        }
        return uiObject;
    }

    public void scrollToBeginning(BySelector backward) throws MissingUiElementException {
        int scrollCount = 0;
        boolean canScroll = true;
        while (canScroll && scrollCount < MAX_SCROLL_COUNT) {
            canScroll = scrollUsingButton(backward);
            scrollCount++;
        }
    }

    /**
     * Swipe in a direction until a target UI Object is found
     *
     * @param swipeDirection Direction to swipe
     * @param numOfSteps Ticks per swipe
     * @param swipeFraction How far to swipe
     * @param target The UI Object to find
     * @return The found object, or null if there isn't one
     */
    public UiObject2 swipeAndFindUiObject(
            SwipeDirection swipeDirection,
            int numOfSteps,
            SwipeFraction swipeFraction,
            BySelector target) {
        validateSelector(target, "Find UI Object");
        UiObject2 uiObject = findUiObject(target);
        if (isValidUiObject(uiObject)) {
            return uiObject;
        }

        String previousView = null;
        String currentView = getViewHierarchy();
        while (!currentView.equals(previousView)) {
            swipe(swipeDirection, numOfSteps, swipeFraction);
            uiObject = findUiObject(target);
            if (isValidUiObject(uiObject)) {
                return uiObject;
            }
            previousView = currentView;
            currentView = getViewHierarchy();
        }
        return null;
    }

    /** Returns the view hierarchy as XML, as output by `adb shell uiautomator dump`. */
    public String getViewHierarchy() {
        try {
            ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
            mDevice.dumpWindowHierarchy(outputStream);
            outputStream.close();
            return outputStream.toString();
        } catch (IOException ex) {
            throw new IllegalStateException("Unable to get view hierarchy.", ex);
        }
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and find the text.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollAndFindUiObject(BySelector scrollableSelector, String text, boolean isVertical)} by
     * passing isVertical = false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @param text Text to search on device UI. It should be exactly same as visible on device UI.
     * @return {@link UiObject2} for given text will be returned. It returns NULL if given text is
     *     not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(BySelector scrollableSelector, String text)
            throws MissingUiElementException {
        validateText(text, /* type= */ "Text");
        return scrollAndFindUiObject(scrollableSelector, By.text(text));
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and find the text.
     *
     * <p>For vertical scrolling, use isVertical = true For Horizontal scrolling, use isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @param text Text to search on device UI. It should be exactly same as visible on device UI.
     * @return {@link UiObject2} for given text will be returned. It returns NULL if given text is
     *     not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(
            BySelector scrollableSelector, String text, boolean isVertical)
            throws MissingUiElementException {
        validateText(text, /* type= */ "Text");
        return scrollAndFindUiObject(scrollableSelector, By.text(text), isVertical);
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and find the target UI
     * Element.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollAndFindUiObject(BySelector scrollableSelector, BySelector target, boolean isVertical)}
     * by passing isVertical = false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @param target {@link BySelector} for UI Element to search on device UI.
     * @return {@link UiObject2} for target UI Element will be returned. It returns NULL if given
     *     target is not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(BySelector scrollableSelector, BySelector target)
            throws MissingUiElementException {
        return scrollAndFindUiObject(scrollableSelector, target, /* isVertical= */ true);
    }

    /**
     * Scroll by performing forward and backward gestures on device screen and find the target UI
     * Element.
     *
     * <p>For vertical scrolling, use isVertical = true For Horizontal scrolling, use isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if the given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @param target {@link BySelector} for UI Element to search on device UI.
     * @param isVertical For vertical scrolling, use isVertical = true and For Horizontal scrolling,
     *     use isVertical = false.
     * @return {@link UiObject2} for target UI Element will be returned. It returns NULL if given
     *     target is not found on the Device UI.
     */
    public UiObject2 scrollAndFindUiObject(
            BySelector scrollableSelector, BySelector target, boolean isVertical)
            throws MissingUiElementException {
        validateSelector(scrollableSelector, /* action= */ "Scroll");
        validateSelector(target, /* action= */ "Find UI Object");
        // Find UI element on current page
        UiObject2 uiObject = findUiObject(target);
        if (isValidUiObject(uiObject)) {
            return uiObject;
        }
        scrollToBeginning(scrollableSelector, isVertical);
        return scrollForwardAndFindUiObject(scrollableSelector, target, isVertical);
    }

    private UiObject2 scrollForwardAndFindUiObject(
            BySelector scrollableSelector, BySelector target, boolean isVertical)
            throws MissingUiElementException {
        UiObject2 uiObject = findUiObject(target);
        if (isValidUiObject(uiObject)) {
            return uiObject;
        }
        int scrollCount = 0;
        boolean canScroll = true;
        while (!isValidUiObject(uiObject) && canScroll && scrollCount < MAX_SCROLL_COUNT) {
            canScroll = scrollForward(scrollableSelector, isVertical);
            scrollCount++;
            uiObject = findUiObject(target);
        }
        return uiObject;
    }

    public void scrollToBeginning(BySelector scrollableSelector, boolean isVertical)
            throws MissingUiElementException {
        int scrollCount = 0;
        boolean canScroll = true;
        while (canScroll && scrollCount < MAX_SCROLL_COUNT) {
            canScroll = scrollBackward(scrollableSelector, isVertical);
            scrollCount++;
        }
    }

    private Direction getDirection(boolean isVertical, boolean scrollForward) {
        // Default Scroll = Vertical and Forward
        // Go DOWN to scroll forward vertically
        Direction direction = Direction.DOWN;
        if (isVertical && !scrollForward) {
            // Scroll = Vertical and Backward
            // Go UP to scroll backward vertically
            direction = Direction.UP;
        }
        if (!isVertical && scrollForward) {
            // Scroll = Horizontal and Forward
            // Go RIGHT to scroll forward horizontally
            direction = Direction.RIGHT;
        }
        if (!isVertical && !scrollForward) {
            // Scroll = Horizontal and Backward
            // Go LEFT to scroll backward horizontally
            direction = Direction.LEFT;
        }
        return direction;
    }

    private UiObject2 validateAndGetScrollableObject(BySelector scrollableSelector)
            throws MissingUiElementException {
        List<UiObject2> scrollableObjects = findUiObjects(scrollableSelector);
        for (UiObject2 scrollableObject : scrollableObjects) {
            validateUiObjectAndThrowMissingUiElementException(
                    scrollableObject, scrollableSelector, /* action= */ "Scroll");
            if (!scrollableObject.isScrollable()) {
                scrollableObject = scrollableObject.findObject(By.scrollable(true));
            }
            if (scrollableObject != null && scrollableObject.isScrollable()) {
                // if there are multiple, return the first UiObject that is scrollable
                return scrollableObject;
            }
        }
        throw new IllegalStateException(
                String.format(
                        "Cannot scroll; Could not find UI Object for selector %s that is scrollable"
                                + " or have scrollable children.",
                        scrollableSelector));
    }

    /**
     * Scroll forward one page by performing forward gestures on device screen.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollForward(BySelector scrollableSelector, boolean isVertical)} by passing isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @return Returns true for successful forward scroll, else false.
     */
    public boolean scrollForward(BySelector scrollableSelector) throws MissingUiElementException {
        return scrollForward(scrollableSelector, /* isVertical= */ true);
    }

    /**
     * Scroll forward one page by performing forward gestures on device screen.
     *
     * <p>For vertical scrolling, use isVertical = true For Horizontal scrolling, use isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @return Returns true for successful forward scroll, else false.
     */
    public boolean scrollForward(BySelector scrollableSelector, boolean isVertical)
            throws MissingUiElementException {
        return scroll(scrollableSelector, getDirection(isVertical, /* scrollForward= */ true));
    }

    /**
     * Scroll backward one page by performing backward gestures on device screen.
     *
     * <p>Scrolling will be performed vertically by default. For horizontal scrolling use {@code
     * scrollBackward(BySelector scrollableSelector, boolean isVertical)} by passing isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @return Returns true for successful backard scroll, else false.
     */
    public boolean scrollBackward(BySelector scrollableSelector) throws MissingUiElementException {
        return scrollBackward(scrollableSelector, /* isVertical= */ true);
    }

    /**
     * Scroll backward one page by performing backward gestures on device screen.
     *
     * <p>For vertical scrolling, use isVertical = true For Horizontal scrolling, use isVertical =
     * false.
     *
     * <p>Method throws {@link MissingUiElementException} if given scrollable selector is not
     * available on the Device UI.
     *
     * @param scrollableSelector {@link BySelector} for the scrollable UI Element on device UI.
     * @return Returns true for successful backward scroll, else false.
     */
    public boolean scrollBackward(BySelector scrollableSelector, boolean isVertical)
            throws MissingUiElementException {
        return scroll(scrollableSelector, getDirection(isVertical, /* scrollForward= */ false));
    }

    private boolean scroll(BySelector scrollableSelector, Direction direction)
            throws MissingUiElementException {

        UiObject2 scrollableObject = validateAndGetScrollableObject(scrollableSelector);

        Rect bounds = scrollableObject.getVisibleBounds();
        int horizontalMargin = (int) (Math.abs(bounds.width()) / mScrollMargin);
        int verticalMargin = (int) (Math.abs(bounds.height()) / mScrollMargin);

        scrollableObject.setGestureMargins(
                horizontalMargin, // left
                verticalMargin, // top
                horizontalMargin, // right
                verticalMargin); // bottom

        String previousView = getViewHierarchy();

        scrollableObject.scroll(direction, SCROLL_PERCENT);
        waitNSeconds(mWaitTimeAfterScroll);

        String currentView = getViewHierarchy();

        // If current view is same as previous view, scroll did not work, so return false
        return !currentView.equals(previousView);
    }

    private void validateText(String text, String type) {
        if (Strings.isNullOrEmpty(text)) {
            throw new IllegalArgumentException(
                    String.format(
                            "Provide a valid %s, current %s value is either NULL or empty.",
                            type, type));
        }
    }

    private void validateSelector(BySelector selector, String action) {
        if (selector == null) {
            throw new IllegalArgumentException(
                    String.format(
                            "Cannot %s; Provide a valid selector to %s, currently it is NULL.",
                            action, action));
        }
    }

    /**
     * A simple null-check on a single uiObject2 instance
     *
     * @param uiObject - The object to be checked.
     * @param action - The UI action being performed when the object was generated or searched-for.
     */
    public void validateUiObject(UiObject2 uiObject, String action) {
        if (uiObject == null) {
            throw new MissingUiElementException(
                    String.format("Unable to find UI Element for %s.", action));
        }
    }

    /**
     * A simple null-check on a list of UIObjects
     *
     * @param uiObjects - The list to check
     * @param action - A string description of the UI action being taken when this list was
     *     generated.
     */
    public void validateUiObjects(List<UiObject2> uiObjects, String action) {
        if (uiObjects == null) {
            throw new MissingUiElementException(
                    String.format("Unable to find UI Element for %s.", action));
        }
    }

    public boolean isValidUiObject(UiObject2 uiObject) {
        return uiObject != null;
    }

    private Set<String> mSupportedProperties =
            Set.of(
                    JsonConfigConstants.CLICKABLE,
                    JsonConfigConstants.SCROLLABLE,
                    JsonConfigConstants.TEXT,
                    JsonConfigConstants.TEXT_CONTAINS,
                    JsonConfigConstants.DESCRIPTION,
                    JsonConfigConstants.DESCRIPTION_CONTAINS,
                    JsonConfigConstants.CLASS,
                    JsonConfigConstants.DISPLAY_ID,
                    JsonConfigConstants.RESOURCE_ID);

    /**
     * Check a UI Object for a given property value.
     *
     * @param uiObject object to check
     * @param property which property to check
     * @param expected expected value of property
     */
    public boolean validateUiObjectProperty(UiObject2 uiObject, String property, String expected) {
        if (!mSupportedProperties.contains(property)) {
            throw new RuntimeException(
                    String.format(
                            "VALIDATE_VALUE property name %s in Spectatio JSON Config is invalid. "
                                    + "Supported properties: [ RESOURCE_ID, TEXT, TEXT_CONTAINS, "
                                    + "DESCRIPTION, DESCRIPTION_CONTAINS, CLASS, CLICKABLE, "
                                    + "SCROLLABLE, DISPLAY_ID ]",
                            property));
        }
        switch (property) {
            case JsonConfigConstants.CLICKABLE:
                return Boolean.toString(uiObject.isClickable()).equalsIgnoreCase(expected);
            case JsonConfigConstants.SCROLLABLE:
                return Boolean.toString(uiObject.isScrollable()).equalsIgnoreCase(expected);
            case JsonConfigConstants.TEXT:
                return uiObject.getText().equalsIgnoreCase(expected);
            case JsonConfigConstants.TEXT_CONTAINS:
                return uiObject.getText().contains(expected);
            case JsonConfigConstants.DESCRIPTION:
                return uiObject.getContentDescription().equalsIgnoreCase(expected);
            case JsonConfigConstants.DESCRIPTION_CONTAINS:
                return uiObject.getContentDescription().contains(expected);
            case JsonConfigConstants.CLASS:
                return uiObject.getClassName().equalsIgnoreCase(expected);
            case JsonConfigConstants.DISPLAY_ID:
                return Integer.toString(uiObject.getDisplayId()).equals(expected);
            case JsonConfigConstants.RESOURCE_ID:
                return uiObject.getResourceName().equals(expected);
            default:
                return false;
        }
    }

    private void validateUiObjectAndThrowIllegalArgumentException(
            UiObject2 uiObject, String action) {
        if (!isValidUiObject(uiObject)) {
            throw new IllegalArgumentException(
                    String.format(
                            "Cannot %s; Provide a valid UI Object to %s, currently it is NULL.",
                            action, action));
        }
    }

    private void validateUiObjectAndThrowMissingUiElementException(
            UiObject2 uiObject, BySelector selector, String action)
            throws MissingUiElementException {
        if (!isValidUiObject(uiObject)) {
            throw new MissingUiElementException(
                    String.format(
                            "Cannot %s; Unable to find UI Object for %s selector.",
                            action, selector));
        }
    }
}