---
name: Touch Perform
short_description: Perform a touch action sequence
   
description:
  |
    This functionality is only available from within a native context

    'Touch Perform' works similarly to the other singular touch interactions, except that this allows you to chain together more than one touch action as one
    command. This is useful because Appium commands are sent over the network and there's latency between commands. This latency can make certain touch 
    interactions impossible because some interactions need to be performed in one sequence. Vertical, for example, requires pressing down, moving to a different
    y coordinate, and then releasing. For it to work, there can't be a delay between the interactions.

example_usage:
  java:
    |
      TouchAction action = new TouchAction(driver);
      action.press(10, 10);
      action.moveTo(10, 100);
      action.release();
      action.perform();
  python:
    |
      from appium.webdriver.common.touch_action import TouchAction
      
      actions = TouchAction(driver)
      actions.tap_and_hold(20, 20)
      actions.move_to(10, 100)
      actions.release()
      actions.perform()
  javascript_wd:
    |
      let action = new wd.TouchAction();
      action.press({x: 10, y: 10});
      action.moveTo({x: 10, y: 100});
      action.release();
      action.perform();
      await driver.performTouchAction(action);

  javascript_wdio:
    |
      driver.touchPerform([
        { action: 'press', options: { x: 100, y: 250 }},
        { action: 'moveTo', options: { x: 300, y: 100 }},
        { action: 'release' }
      ]);
  ruby:
    |
      @driver.touch_action.down(element).move_to(10, 100).up(50, 50).perform
  php:
    |
      // TODO PHP sample
  csharp:
    |
      // TODO C# sample

client_docs:
  java: "http://appium.github.io/java-client/io/appium/java_client/TouchAction.html"
  python: "https://github.com/appium/python-client/blob/master/appium/webdriver/common/touch_action.py"
  javascript_wdio: "http://webdriver.io/api/mobile/performTouchAction.html"
  javascript_wd: "https://github.com/admc/wd/blob/master/lib/commands.js#L1546"
  ruby: "http://www.rubydoc.info/github/appium/ruby_lib/Appium/TouchAction"
  php: "https://github.com/appium/php-client/" # TODO PHP documentation link
  csharp: "https://github.com/appium/appium-dotnet-driver/" # TODO Dotnet documentation link

# Driver support by platform
driver_support:
  ios:
    xcuitest: true
    uiautomation: true
  android:
    uiautomator2: true
    uiautomator: true
  mac:
    mac: true # TODO Confirm this that mouse movements
  windows:
    windows: true # TODO Confirm this
client_support:
  java: true
  python: true
  ruby: true
  php: true
  csharp: true
  javascript_wd: true
  javascript_wdio: true
  

# Information about the HTTP endpoints
endpoint:
  url: /session/:session_id/touch/perform
  method: POST
  url_parameters:
    - name: session_id
      description: ID of the session to route the command to
  json_parameters:
    - name: action
      type: string
      description: The type of action to perform (moveTo|release|press|tap|wait)
    - name: options
      type: object
      description: The parameters of the action
    - name: opts.element
      type: string
      description: The ID of the element
    - name: opts.x
      type: number
      description: The X coordinate of the operation (relative to top left corner)
    - name: opts.y
      type: number
      description: The Y coordinate of the operation (relative to top left corner)
    - name: opts.count
      type: number
      description: Tap count

# Links to specifications. Should link to at least one specification
specifications:
  jsonwp: https://github.com/appium/appium-base-driver/blob/master/lib/mjsonwp/routes.js#L292