Class: Appium::TouchAction

Inherits:
Object
  • Object
show all
Defined in:
lib/appium_lib/device/touch_actions.rb

Overview

Perform a series of gestures, one after another. Gestures are chained together and only performed when `perform()` is called.

Each method returns the object itself, so calls can be chained.

“`ruby action = TouchAction.new.press(x: 45, y: 100).wait(5).release action.perform action = TouchAction.new.swipe(.…) action.perform “`

Or each methods can call without `TouchAction.new` as the following. In this case, `perform` is called automatically. “`ruby # called `swipe(…).perform` in this method. swipe(start_x: 75, start_y: 500, offset_x: 75, offset_y: 20, duration: 500) “`

Constant Summary

ACTIONS =
[:move_to, :long_press, :double_tap, :two_finger_tap, :press, :release, :tap, :wait, :perform].freeze
COMPLEX_ACTIONS =
[:swipe].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeTouchAction



39
40
41
# File 'lib/appium_lib/device/touch_actions.rb', line 39

def initialize
  @actions = []
end

Instance Attribute Details

#actionsObject (readonly)

Returns the value of attribute actions



37
38
39
# File 'lib/appium_lib/device/touch_actions.rb', line 37

def actions
  @actions
end

Instance Method Details

#cancelObject

Does nothing, currently.



186
187
188
189
190
# File 'lib/appium_lib/device/touch_actions.rb', line 186

def cancel
  @actions << { action: cancel }
  $driver.touch_actions @actions
  self
end

#double_tap(opts) ⇒ Object

Double tap an element on the screen

Options Hash (opts):

  • :element (WebDriver::Element) — default: Optional

    Element to restrict scope too.

  • :x (integer)

    x co-ordinate to tap

  • :y (integer)

    y co-ordinate to tap



112
113
114
115
116
# File 'lib/appium_lib/device/touch_actions.rb', line 112

def double_tap(opts)
  args = opts.select { |k, _v| [:element, :x, :y].include? k }
  args = args_with_ele_ref(args)
  chain_method(:doubleTap, args) # doubleTap is what the appium server expects
end

#long_press(opts) ⇒ Object

Press down for a specific duration. Alternatively, you can use `press(…).wait(…).release()` instead of `long_press` if duration doesn't work well. github.com/appium/ruby_lib/issues/231#issuecomment-269895512 e.g. Appium::TouchAction.new.press(x: 280, y: 530).wait(2000).release.perform



64
65
66
67
68
# File 'lib/appium_lib/device/touch_actions.rb', line 64

def long_press(opts)
  args = opts.select { |k, _v| [:element, :x, :y, :duration].include? k }
  args = args_with_ele_ref(args)
  chain_method(:longPress, args) # longPress is what the appium server expects
end

#move_to(opts) ⇒ Object

Move to the given co-ordinates.

`move_to`'s `x` and `y` have two case. One is working as coordinate, the other is working as offset.

Options Hash (opts):

  • :x (integer)

    x co-ordinate to move to if element isn't set. Works as an offset if x is set with Element.

  • :y (integer)

    y co-ordinate to move to if element isn't set. Works as an offset if y is set with Element.

  • Element (WebDriver::Element)

    to scope this move within.



50
51
52
53
# File 'lib/appium_lib/device/touch_actions.rb', line 50

def move_to(opts)
  opts = args_with_ele_ref(opts)
  chain_method(:moveTo, opts)
end

#performObject

Ask the driver to perform all actions in this action chain.



179
180
181
182
183
# File 'lib/appium_lib/device/touch_actions.rb', line 179

def perform
  $driver.touch_actions @actions
  @actions.clear
  self
end

#press(opts) ⇒ Object

Press a finger onto the screen. Finger will stay down until you call `release`.

Options Hash (opts):

  • :element (WebDriver::Element) — default: Optional

    Element to press within.

  • :x (integer)

    x co-ordinate to press on

  • :y (integer)

    y co-ordinate to press on



76
77
78
79
80
# File 'lib/appium_lib/device/touch_actions.rb', line 76

def press(opts)
  args = opts.select { |k, _v| [:element, :x, :y].include? k }
  args = args_with_ele_ref(args)
  chain_method(:press, args)
end

#release(opts = nil) ⇒ Object

Remove a finger from the screen.

Options Hash (opts):

  • :element (WebDriver::Element) — default: Optional

    Element to release from.

  • :x (integer)

    x co-ordinate to release from

  • :y (integer)

    y co-ordinate to release from



87
88
89
90
# File 'lib/appium_lib/device/touch_actions.rb', line 87

def release(opts = nil)
  args = args_with_ele_ref(opts) if opts
  chain_method(:release, args)
end

#swipe(opts, ele = nil) ⇒ Object

Convenience method to peform a swipe.

Note that iOS 7 simulators have broken swipe.

For iOS: Use `offset_x` and `offset_y` to define the end point.

For Android: Use `end_x` and `end_y` to define the end point.

If you'd like more details, please read tests and its log samples in `ios_tests/lib/ios/specs/device/touch_actions.rb` and `ios_tests/lib/ios/specs/device/touch_actions.rb`

Options Hash (opts):

  • :start_x (int)

    Where to start swiping, on the x axis. Default 0.

  • :start_y (int)

    Where to start swiping, on the y axis. Default 0.

  • :offset_x (int)

    For iOS. Offset, on the x axis. Default 0.

  • :offset_y (int)

    For iOS. Offset, on the y axis. Default 0.

  • :end_x (int)

    For Android. Where to end swiping, on the x axis. Default 0.

  • :end_y (int)

    For Android. Where to end swiping, on the y axis. Default 0.

  • :duration (int)

    How long the actual swipe takes to complete in milliseconds. Default 200.



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
# File 'lib/appium_lib/device/touch_actions.rb', line 154

def swipe(opts, ele = nil)
  start_x  = opts.fetch :start_x, 0
  start_y  = opts.fetch :start_y, 0
  offset_x = opts.fetch :offset_x, nil
  offset_y = opts.fetch :offset_y, nil
  end_x    = opts.fetch :end_x, nil
  end_y    = opts.fetch :end_y, nil
  duration = opts.fetch :duration, 200

  coordinates = swipe_coordinates(end_x: end_x, end_y: end_y, offset_x: offset_x, offset_y: offset_y)

  if ele # pinch/zoom for XCUITest
    press x: start_x, y: start_y, element: ele
    move_to x: coordinates[:offset_x], y: coordinates[:offset_y], element: ele
  else
    press x: start_x, y: start_y
    wait(duration) if duration
    move_to x: coordinates[:offset_x], y: coordinates[:offset_y]
  end
  release

  self
end

#swipe_coordinates(end_x: nil, end_y: nil, offset_x: nil, offset_y: nil) ⇒ Object



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
# File 'lib/appium_lib/device/touch_actions.rb', line 192

def swipe_coordinates(end_x: nil, end_y: nil, offset_x: nil, offset_y: nil)
  if $driver.device_is_android?
    puts 'end_x and end_y are used for Android. Not offset_x and offset_y.' if end_x.nil? || end_y.nil?
    end_x ||= 0
    end_y ||= 0
    return { offset_x: end_x, offset_y: end_y }
  elsif offset_x.nil? || offset_y.nil?
    puts 'offset_x and offset_y are used for iOS. Not end_x and end_y point.'
  end

  offset_x ||= 0
  offset_y ||= 0

  { offset_x: offset_x, offset_y: offset_y }
end

#tap(opts) ⇒ Object

Touch a point on the screen. Alternatively, you can use `press(…).release.perform` instead of `tap(…).perform`.

Options Hash (opts):

  • :element (WebDriver::Element) — default: Optional

    Element to restrict scope too.

  • :x (integer)

    x co-ordinate to tap

  • :y (integer)

    y co-ordinate to tap

  • :fingers (integer)

    how many fingers to tap with (Default 1)



99
100
101
102
103
104
# File 'lib/appium_lib/device/touch_actions.rb', line 99

def tap(opts)
  opts[:count] = opts.delete(:fingers) if opts[:fingers]
  opts[:count] ||= 1
  args = args_with_ele_ref opts
  chain_method(:tap, args)
end

#two_finger_tap(opts) ⇒ Object

Two finger tap an element on the screen

Options Hash (opts):

  • :element (WebDriver::Element) — default: Optional

    Element to restrict scope too.

  • :x (integer)

    x co-ordinate to tap

  • :y (integer)

    y co-ordinate to tap



123
124
125
126
127
# File 'lib/appium_lib/device/touch_actions.rb', line 123

def two_finger_tap(opts)
  args = opts.select { |k, _v| [:element, :x, :y].include? k }
  args = args_with_ele_ref(args)
  chain_method(:twoFingerTap, args) # twoFingerTap is what the appium server expects
end

#wait(milliseconds) ⇒ Object

Pause for a number of milliseconds before the next action



131
132
133
134
# File 'lib/appium_lib/device/touch_actions.rb', line 131

def wait(milliseconds)
  args = { ms: milliseconds }
  chain_method(:wait, args)
end