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.



27
28
29
30
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 27

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

Instance Attribute Details

#actions ⇒ Object (readonly)

Returns the value of attribute actions.



25
26
27
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 25

def actions
  @actions
end

#driver ⇒ Object (readonly)

Returns the value of attribute driver.



25
26
27
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 25

def driver
  @driver
end

Instance Method Details

#cancel ⇒ Object

Does nothing, currently.



169
170
171
172
173
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 169

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



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

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.



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

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.



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

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.



162
163
164
165
166
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 162

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.



71
72
73
74
75
76
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 71

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



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

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.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 144

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)



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

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



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

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



131
132
133
134
 
# File 'lib/appium_lib_core/common/touch_action/touch_actions.rb', line 131

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