webdriverio/build/commands/mobile/tap.d.ts

Next-gen browser and mobile automation test framework for Node.js

import type { TapOptions } from '../../types.js';
/**
 *
 * Performs a tap gesture on:
 * - or the given element. It will **automatically scroll** if it can't be found.
 * - or the screen on a mobile device by providing `x` and `y` coordinates
 *
 * Internally it uses:
 * - Element tap:
 *      - the `click` command for Web environments (Chrome/Safari browsers, or hybrid apps)
 *      - the Android [`mobile: clickGesture`](https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-mobile-gestures.md#mobile-clickgesture)
 * or iOS [`mobile: tap`](https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-tap) for Natives apps, including the `scrollIntoView`
 * command for automatic scrolling
 * - Screen tap:
 *      - the `action` command for Web environments (Chrome/Safari browsers, or hybrid apps)
 *      - the Android [`mobile: clickGesture`](https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-mobile-gestures.md#mobile-clickgesture)
 * or iOS [`mobile: tap`](https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-tap) for Natives apps
 *
 * This difference makes the `tap` command a more reliable alternative to the `click` command for mobile apps.
 *
 * For Native Apps, this command differs from the `click` command as it will <strong>automatically swipe</strong> to the element using the `scrollIntoView command`,
 * which is not supported for native apps with the `click` command. In hybrid apps or web environments, automatic scrolling is supported for both `click` and `tap` commands.
 *
 * :::info
 *
 * This command only works with the following up-to-date components:
 *  - Appium server (version 2.0.0 or higher)
 *  - `appium-uiautomator2-driver` (for Android)
 *  - `appium-xcuitest-driver` (for iOS)
 *
 * Make sure your local or cloud-based Appium environment is regularly updated to avoid compatibility issues.
 *
 * :::
 *
 *
 * :::caution For Screen taps
 *
 * If you want to tap on a specific coordinate on the screen and you use a screenshot to determine the coordinates, remember that the
 * the coordinates for iOS are based on the device's screen size, and not the screenshot size. The screenshot size is larger due to the device pixel ratio.
 * The average device pixel ratio until the iPhone 8 and the current iPads is 2, for iPhones from the iPhone X the ratio is 3. This means that the screenshot
 * size is 2 or 3 times larger than the device's screen size which means that ff you find the coordinates on the screenshot, divide them by the device pixel
 * ratio to get the correct screen coordinates. For example:
 *
 * ```js
 * const screenshotCoordinates = { x: 600, y: 900 };
 * const dpr = 3; // Example for iPhone 16
 * const screenCoordinates = {
 *     x: screenshotCoordinates.x / dpr,
 *     y: screenshotCoordinates.y / dpr
 * };
 * await browser.tap(screenCoordinates);
 * ```
 *
 * :::
 *
 * <example>
    :element.tap.example.js
    it('should be able to tap an on element', async () => {
        const elem = $('~myElement')
        // It will automatically scroll to the element if it's not already in the viewport
        await elem.tap()
    })
 * </example>
 *
 * <example>
    :element.tap.scroll.options.example.js
    it('should be able to swipe right 3 times in a custom scroll areas to an element and tap on the element', async () => {
        const elem = $('~myElement')
        // Swipe right 3 times in the custom scrollable element to find the element
        await elem.tap({
            direction: 'right',
            maxScrolls: 3,
            scrollableElement: $('#scrollable')
        })
    })
 * </example>
 *
 * <example>
    :screen.tap.example.js
    it('should be able to tap on screen coordinates', async () => {
        await browser.tap({ x: 200, y: 400 })
    })
 * </example>
 *
 * @param {TapOptions=} options                     Tap options (optional)
 * @rowInfo Element tap options
 * @param {number=}     options.x                   Number (optional, mandatory if y is set) <br /><strong>Only for SCREEN tap, not for ELEMENT tap</strong>
 * @param {number=}     options.y                   Number (optional, mandatory if x is set) <br /><strong>Only for SCREEN tap, not for ELEMENT tap</strong>
 * @rowInfo Screen tap options
 * @param {string=}     options.direction           Can be one of `down`, `up`, `left` or `right`, default is `down`. <br /><strong>Only for ELEMENT tap, not for SCREEN tap</strong><br /><strong>MOBILE-NATIVE-APP-ONLY</strong>
 * @param {number=}     options.maxScrolls          The max amount of scrolls until it will stop searching for the element, default is `10`. <br /><strong>Only for ELEMENT tap, not for SCREEN tap</strong><br /><strong>MOBILE-NATIVE-APP-ONLY</strong>
 * @param {Element=}    options.scrollableElement   Element that is used to scroll within. If no element is provided it will use the following selector for iOS `-ios predicate string:type == "XCUIElementTypeApplication"` and the following for Android `//android.widget.ScrollView'`. If more elements match the default selector, then by default it will pick the first matching element. <br /><strong>Only for ELEMENT tap, not for SCREEN tap</strong><br /><strong>MOBILE-NATIVE-APP-ONLY</strong>
 * @skipUsage
 */
export declare function tap(this: WebdriverIO.Browser | WebdriverIO.Element, options?: TapOptions): Promise<unknown>;
//# sourceMappingURL=tap.d.ts.map