Class: Appium::Core::TouchAction

Inherits:
Object
  • Object
show all
Defined in:
lib/appium_lib_core/common/touch_action/touch_actions.rb

Overview

Perform a series of gestures, one after another. Gestures are chained together and only performed when perform() is called. Default is conducted by global driver.

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

Consider to use W3C spec touch action like the followings. seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/W3CActionBuilder.html github.com/appium/ruby_lib_core/blob/master/test/functional/android/webdriver/w3c_actions_test.rb github.com/appium/ruby_lib_core/blob/master/test/functional/ios/webdriver/w3c_actions_test.rb

Examples:


@driver = Appium::Core.for(opts).start_driver
action = TouchAction.new(@driver).press(x: 45, y: 100).wait(600).release
action.perform
action = TouchAction.new(@driver).swipe(....)
action.perform

Constant Summary collapse

ACTIONS = 
%i(move_to long_press double_tap two_finger_tap press release tap wait perform).freeze
COMPLEX_ACTIONS = 
%i(swipe).freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(driver) ⇒ TouchAction

Returns a new instance of TouchAction.



41
42
43
44
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 41

def initialize(driver)
  @actions = []
  @driver = driver
end

Instance Attribute Details

#actions ⇒ Object (readonly)

Returns the value of attribute actions.



39
40
41
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 39

def actions
  @actions
end

#driver ⇒ Object (readonly)

Returns the value of attribute driver.



39
40
41
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 39

def driver
  @driver
end

Instance Method Details

#cancel ⇒ Object

Does nothing, currently.



183
184
185
186
187
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 183

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

#double_tap(opts) ⇒ Object

Double tap an element on the screen

Parameters:

  • opts (Hash) —

    Options

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



125
126
127
128
129
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 125

def double_tap(opts)
  args = opts.select { |k, _v| %i(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

Parameters:

  • opts (Hash) —

    Options

Options Hash (opts):

  • element (WebDriver::Element) —

    the element to press.

  • x (integer) —

    X co-ordinate to press on.

  • y (integer) —

    Y co-ordinate to press on.

  • duration (integer) —

    Number of milliseconds to press.



69
70
71
72
73
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 69

def long_press(opts)
  args = opts.select { |k, _v| %i(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.

Parameters:

  • opts (Hash) —

    Options

Options Hash (opts):

  • :x (integer) —

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

  • :y (integer) —

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

  • Element (WebDriver::Element) —

    to scope this move within.



54
55
56
57
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 54

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

#perform ⇒ Object

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



176
177
178
179
180
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 176

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.

Parameters:

  • opts (Hash) —

    Options

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

  • pressure (Float) — default: iOS Only —

    press as force touch. See the description of force property on Apple’s UITouch class (developer.apple.com/documentation/uikit/uitouch?language=objc) for more details on possible value ranges.



85
86
87
88
89
90
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 85

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

#release(opts = nil) ⇒ Object

Remove a finger from the screen.

Parameters:

  • opts (Hash) (defaults to: nil) —

    Options

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



98
99
100
101
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 98

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

#swipe(opts) ⇒ Object

Convenience method to perform a swipe.

Parameters:

  • opts (Hash) —

    Options

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.

  • :end_x (int) —

    Move to the end, on the x axis. Default 0.

  • :end_y (int) —

    Move to the end, on the y axis. Default 0.

  • :duration (int) —

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



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 158

def swipe(opts)
  start_x = opts.fetch :start_x, 0
  start_y = opts.fetch :start_y, 0
  end_x   = opts.fetch :end_x, 0
  end_y   = opts.fetch :end_y, 0

  duration = opts.fetch :duration, 200

  press x: start_x, y: start_y
  wait(duration) if duration
  move_to x: end_x, y: end_y

  release

  self
end

#tap(opts) ⇒ Object

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

Parameters:

  • opts (Hash) —

    Options

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)



111
112
113
114
115
116
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 111

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

Parameters:

  • opts (Hash) —

    Options

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



137
138
139
140
141
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 137

def two_finger_tap(opts)
  args = opts.select { |k, _v| %i(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

Parameters:

  • milliseconds (integer) —

    Number of milliseconds to pause for



145
146
147
148
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 145

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