Module: Appium::Common

Defined in:
lib/appium_lib/common/helper.rb,
lib/appium_lib/common/element/text.rb,
lib/appium_lib/common/element/button.rb,
lib/appium_lib/common/element/window.rb,
lib/appium_lib/common/patch.rb

Overview

end Add status to WebDriver

Instance Method Summary collapse

Instance Method Details

#back ⇒ void

This method returns an undefined value.

Navigate back.



75
76
77
 
# File 'lib/appium_lib/common/helper.rb', line 75

def back
  @driver.navigate.back
end

#button(text, number = 0) ⇒ Button

Find a button by text and optionally number.

Parameters:

  • text (String, Integer) —

    the text to exactly match. If int then the button at that index is returned.

  • number (Integer) (defaults to: 0) —

    the occurrence of the button matching text. Defaults to the first button.

Returns:

  • (Button) —

    the button found with text and matching number



8
9
10
11
12
13
14
 
# File 'lib/appium_lib/common/element/button.rb', line 8

def button text, number=0
  # return button at index.
  return ele_index :button, text if text.is_a? Numeric

  number >= 1 ? button_num( text, number ) :
                find_ele_by_text_include( :button, text )
end

#button_exact(text) ⇒ Button

Get the first button element that exactly matches text.

Parameters:

  • text (String) —

    the text to match exactly

Returns:

  • (Button) 


39
40
41
 
# File 'lib/appium_lib/common/element/button.rb', line 39

def button_exact text
  find_ele_by_text :button, text
end

#button_num(text, number = 1) ⇒ Button

Expected to be called via button method.

Get the button element exactly matching text and occurrence. number=2 means the 2nd occurrence.

find the second Sign In button

b = e_button ‘Sign In’, 2

Button order will change in iOS vs Android so if there’s no button found at number then return the first button.

Parameters:

  • text (String) —

    the text to match

  • number (Integer) (defaults to: 1) —

    the button occurance to return. 1 = first button

Returns:

  • (Button) —

    the button that matches text and number



72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/appium_lib/common/element/button.rb', line 72

def button_num text, number=1
  raise 'Number must be >= 1' if number <= 0
  number = number - 1 # zero indexed
  result = nil

  elements = buttons text
  elements.size > number ? result = elements[number]
                         : result = elements.first

  result
end

#buttons(text = nil) ⇒ Array<String>, Array<Buttons>

Get an array of button texts or button elements if text is provided.

Parameters:

  • text (String) (defaults to: nil) —

    the text to exactly match

Returns:

  • (Array<String>, Array<Buttons>) —

    either an array of button texts or an array of button elements if text is provided.



19
20
21
22
 
# File 'lib/appium_lib/common/element/button.rb', line 19

def buttons text=nil
  text == nil ? find_eles_attr( :button, :text ) :
                find_eles_by_text_include( :button, text )
end

#buttons_exact(text) ⇒ Array<Button>

Get all button elements that exactly match text.

Parameters:

  • text (String) —

    the text to match exactly

Returns:

  • (Array<Button>) 


46
47
48
 
# File 'lib/appium_lib/common/element/button.rb', line 46

def buttons_exact text
  find_eles_by_text :button, text
end

#e_buttons ⇒ Array<Button>

Get an array of button elements.

Returns:

  • (Array<Button>) 


52
53
54
 
# File 'lib/appium_lib/common/element/button.rb', line 52

def e_buttons
  find_eles :button
end

#e_s_texts ⇒ Array<Text>

Get an array of text elements.

Returns:

  • (Array<Text>) 


14
15
16
 
# File 'lib/appium_lib/common/element/text.rb', line 14

def e_s_texts
  find_eles :text
end

#ele_index(tag_name, index) ⇒ Element

Get the element of type tag_name at matching index.

Parameters:

  • tag_name (String) —

    the tag name to find

  • index (Integer) —

    the index

Returns:

  • (Element) —

    the found element of type tag_name



104
105
106
107
 
# File 'lib/appium_lib/common/helper.rb', line 104

def ele_index tag_name, index
  # XPath index starts at 1. ruby_lib index starts at 0
  find_element :xpath, "//#{tag_name}[#{index + 1}]"
end

#find_ele_by_attr_include(tag, attr, value) ⇒ Element

Get the first tag by attribute that exactly matches value.

Parameters:

  • tag (String) —

    the tag name to match

  • attr (String) —

    the attribute to compare

  • value (String) —

    the value of the attribute that the element must include

Returns:

  • (Element) —

    the element of type tag who’s attribute includes value



137
138
139
 
# File 'lib/appium_lib/common/helper.rb', line 137

def find_ele_by_attr_include tag, attr, value
  @driver.find_element :xpath, %Q(#{tag}[contains(@#{attr}, '#{value}')])
end

#find_ele_by_text(tag, text) ⇒ Element

Get the first tag that exactly matches tag and text.

Parameters:

  • tag (String) —

    the tag name to match

  • text (String) —

    the text to exactly match

Returns:

  • (Element) —

    the element of type tag exactly matching text



120
121
122
 
# File 'lib/appium_lib/common/helper.rb', line 120

def find_ele_by_text tag, text
  @driver.find_element :xpath, %Q(#{tag}[@text='#{text}'])
end

#find_ele_by_text_include(tag, text) ⇒ Element

Get the first tag that includes text. element.attribute(:text).include? text

Parameters:

  • tag (String) —

    the tag name to match

  • text (String) —

    the text the element must include

Returns:

  • (Element) —

    the element of type tag that includes text



155
156
157
 
# File 'lib/appium_lib/common/helper.rb', line 155

def find_ele_by_text_include tag, text
  find_ele_by_attr_include tag, :text, text
end

#find_eles(tag_name) ⇒ Array<Element>

Get all elements exactly matching tag name

Parameters:

  • tag_name (String) —

    the tag name to find

Returns:

  • (Array<Element>) —

    the found elements of type tag_name



112
113
114
 
# File 'lib/appium_lib/common/helper.rb', line 112

def find_eles tag_name
  @driver.find_elements :tag_name, tag_name
end

#find_eles_by_attr_include(tag, attr, value) ⇒ Array<Element>

Get tags by attribute that include value.

Parameters:

  • tag (String) —

    the tag name to match

  • attr (String) —

    the attribute to compare

  • value (String) —

    the value of the attribute that the element must include

Returns:

  • (Array<Element>) —

    the elements of type tag who’s attribute includes value



146
147
148
 
# File 'lib/appium_lib/common/helper.rb', line 146

def find_eles_by_attr_include tag, attr, value
  @driver.find_elements :xpath, %Q(#{tag}[contains(@#{attr}, '#{value}')])
end

#find_eles_by_text(tag, text) ⇒ Array<Element>

Get all tags that exactly match tag and text.

Parameters:

  • tag (String) —

    the tag name to match

  • text (String) —

    the text to exactly match

Returns:

  • (Array<Element>) —

    the elements of type tag exactly matching text



128
129
130
 
# File 'lib/appium_lib/common/helper.rb', line 128

def find_eles_by_text tag, text
  @driver.find_elements :xpath, %Q(#{tag}[@text='#{text}'])
end

#find_eles_by_text_include(tag, text) ⇒ Array<Element>

Get the tags that include text. element.attribute(:text).include? text

Parameters:

  • tag (String) —

    the tag name to match

  • text (String) —

    the text the element must include

Returns:

  • (Array<Element>) —

    the elements of type tag that includes text



164
165
166
 
# File 'lib/appium_lib/common/helper.rb', line 164

def find_eles_by_text_include tag, text
  find_eles_by_attr_include tag, :text, text
end

#find_name(name) ⇒ Element

Returns the first element that exactly matches name

Parameters:

  • name (String) —

    the name to exactly match

Returns:

  • (Element) 


200
201
202
 
# File 'lib/appium_lib/common/helper.rb', line 200

def find_name name
  find_element :name, name
end

#find_names(name) ⇒ Array<Element>

Returns all elements that exactly match name

Parameters:

  • name (String) —

    the name to exactly match

Returns:

  • (Array<Element>) 


208
209
210
 
# File 'lib/appium_lib/common/helper.rb', line 208

def find_names name
  find_elements :name, name
end

#first_button ⇒ Button

Get the first button element.

Returns:

  • (Button) 


26
27
28
 
# File 'lib/appium_lib/common/element/button.rb', line 26

def first_button
  first_ele :button
end

#first_ele(tag_name) ⇒ Element

Get the first tag that matches tag_name

Parameters:

  • tag_name (String) —

    the tag to match

Returns:

  • (Element) 


171
172
173
174
 
# File 'lib/appium_lib/common/helper.rb', line 171

def first_ele tag_name
  # XPath index starts at 1
  find_element :xpath, "//#{tag_name}[1]"
end

#first_s_text ⇒ Text

Get the first text element.

Returns:

  • (Text) 


20
21
22
 
# File 'lib/appium_lib/common/element/text.rb', line 20

def first_s_text
  first_ele :text
end

#get_source ⇒ JSON

Gets a JSON view of the current page

Returns:

  • (JSON) 


191
192
193
194
 
# File 'lib/appium_lib/common/helper.rb', line 191

def get_source
  # must set max nesting. default limit of 20 is too low for selendroid
  JSON.parse @driver.page_source, max_nesting: 9999
end

#id(id) ⇒ Element

Find by id. Useful for selendroid

Parameters:

  • id (String) —

    the id to search for

Returns:

  • (Element) 


69
70
71
 
# File 'lib/appium_lib/common/helper.rb', line 69

def id id
  find_element :id, id
end

#ignore(&block) ⇒ Object

Return block.call and ignore any exceptions.



45
46
47
 
# File 'lib/appium_lib/common/helper.rb', line 45

def ignore &block
  begin; block.call; rescue; end
end

#last_button ⇒ Button

Get the last button element.

Returns:

  • (Button) 


32
33
34
 
# File 'lib/appium_lib/common/element/button.rb', line 32

def last_button
  last_ele :button
end

#last_ele(tag_name) ⇒ Element

Get the last tag that matches tag_name

Parameters:

  • tag_name (String) —

    the tag to match

Returns:

  • (Element) 


179
180
181
 
# File 'lib/appium_lib/common/helper.rb', line 179

def last_ele tag_name
  xpath "//#{tag_name}[last()]"
end

#last_s_text ⇒ Text

Get the last text element

Returns:

  • (Text) 


26
27
28
 
# File 'lib/appium_lib/common/element/text.rb', line 26

def last_s_text
  last_ele :text
end

#px_to_window_rel(opts = {}) ⇒ Object

Converts pixel values to window relative values

“‘ruby px_to_window_rel x: 50, y: 150 “`



226
227
228
229
230
231
232
233
234
 
# File 'lib/appium_lib/common/helper.rb', line 226

def px_to_window_rel opts={}

  w = $driver.window_size
  x = opts.fetch :x, 0
  y = opts.fetch :y, 0

  OpenStruct.new( x: x.to_f / w.width.to_f,
                  y: y.to_f / w.height.to_f )
end

#s_text(text) ⇒ Text

Get the first element that includes text.

Parameters:

  • text (String, Integer) —

    the text to find. If int then the text at that index is returned.

Returns:

  • (Text) 


33
34
35
36
 
# File 'lib/appium_lib/common/element/text.rb', line 33

def s_text text
  return ele_index :text, text if text.is_a? Numeric
  find_ele_by_text_include :text, text
end

#s_text_exact(text) ⇒ Text

Get the first textfield that matches text.

Parameters:

  • text (String) —

    the text that the tag must match

Returns:

  • (Text) 


41
42
43
 
# File 'lib/appium_lib/common/element/text.rb', line 41

def s_text_exact text
  find_ele_by_text :text, text
end

#s_texts ⇒ Array<String>

Get an array of text texts.

Returns:

  • (Array<String>) 


8
9
10
 
# File 'lib/appium_lib/common/element/text.rb', line 8

def s_texts
  find_eles_attr :text, :text
end

#session_id ⇒ Object

For Sauce Labs reporting. Returns the current session id.



80
81
82
 
# File 'lib/appium_lib/common/helper.rb', line 80

def session_id
  @driver.session_id
end

#source ⇒ void

This method returns an undefined value.

Prints a JSON view of the current page



185
186
187
 
# File 'lib/appium_lib/common/helper.rb', line 185

def source
  ap get_source
end

#tag(tag_name) ⇒ Element

Returns the first element matching tag_name

Parameters:

  • tag_name (String) —

    the tag_name to search for

Returns:

  • (Element) 


216
217
218
 
# File 'lib/appium_lib/common/helper.rb', line 216

def tag tag_name
  find_element :tag_name, tag_name
end

#wait(max_wait = 30, interval = 0.5, &block) ⇒ Object

Check every 0.5 seconds to see if block.call doesn’t raise an exception. if .call raises an exception then it will be tried again. if .call doesn’t raise an exception then it will stop waiting.

Example: wait { name(‘back’).click }

Give up after 30 seconds.

Parameters:

  • max_wait (Integer) (defaults to: 30) —

    the maximum time in seconds to wait for. Note that max wait 0 means infinity.

  • interval (Float) (defaults to: 0.5) —

    the time in seconds to wait after calling the block

  • block (Block) —

    the block to call

Returns:

  • (Object) —

    the result of block.call



33
34
35
36
37
38
39
40
41
42
 
# File 'lib/appium_lib/common/helper.rb', line 33

def wait max_wait=30, interval=0.5, &block
  # Rescue Timeout::Error: execution expired
  result = nil
  timeout max_wait do
    until (result = begin; block.call || true; rescue; end)
      sleep interval
    end
  end
  result
end

#wait_true(max_wait = 30, interval = 0.5, &block) ⇒ Object

Check every 0.5 seconds to see if block.call returns true. nil is considered a failure. Give up after 30 seconds.

Parameters:

  • max_wait (Integer) (defaults to: 30) —

    the maximum time in seconds to wait for

  • interval (Float) (defaults to: 0.5) —

    the time in seconds to wait after calling the block

  • block (Block) —

    the block to call

Returns:

  • (Object) —

    the result of block.call



55
56
57
58
59
60
61
62
63
64
 
# File 'lib/appium_lib/common/helper.rb', line 55

def wait_true max_wait=30, interval=0.5, &block
  # Rescue Timeout::Error: execution expired
  result = nil
  timeout max_wait do
    until (result = begin; block.call; rescue; end)
      sleep interval
    end
  end
  result
end

#window_size ⇒ Object

Get the window’s size



5
6
7
8
 
# File 'lib/appium_lib/common/element/window.rb', line 5

def window_size
  return nil if @driver.nil?
  @driver.manage.window.size
end

#xpath(xpath_str) ⇒ Element

Returns the first element that matches the provided xpath.

Parameters:

  • xpath_str (String) —

    the XPath string

Returns:

  • (Element) 


88
89
90
 
# File 'lib/appium_lib/common/helper.rb', line 88

def xpath xpath_str
  find_element :xpath, xpath_str
end

#xpaths(xpath_str) ⇒ Array<Element>

Returns all elements that match the provided xpath.

Parameters:

  • xpath_str (String) —

    the XPath string

Returns:

  • (Array<Element>) 


96
97
98
 
# File 'lib/appium_lib/common/helper.rb', line 96

def xpaths xpath_str
  find_elements :xpath, xpath_str
end