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.



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

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



99
100
101
102
 
# File 'lib/appium_lib/common/helper.rb', line 99

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



132
133
134
 
# File 'lib/appium_lib/common/helper.rb', line 132

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



115
116
117
 
# File 'lib/appium_lib/common/helper.rb', line 115

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



150
151
152
 
# File 'lib/appium_lib/common/helper.rb', line 150

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



107
108
109
 
# File 'lib/appium_lib/common/helper.rb', line 107

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



141
142
143
 
# File 'lib/appium_lib/common/helper.rb', line 141

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



123
124
125
 
# File 'lib/appium_lib/common/helper.rb', line 123

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



159
160
161
 
# File 'lib/appium_lib/common/helper.rb', line 159

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) 


195
196
197
 
# File 'lib/appium_lib/common/helper.rb', line 195

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>) 


203
204
205
 
# File 'lib/appium_lib/common/helper.rb', line 203

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) 


166
167
168
169
 
# File 'lib/appium_lib/common/helper.rb', line 166

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) 


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

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) 


64
65
66
 
# File 'lib/appium_lib/common/helper.rb', line 64

def id id
  find_element :id, id
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) 


174
175
176
 
# File 'lib/appium_lib/common/helper.rb', line 174

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

#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.



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

def session_id
  @driver.session_id
end

#source ⇒ void

This method returns an undefined value.

Prints a JSON view of the current page



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

def source
  ap get_source
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



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/appium_lib/common/helper.rb', line 50

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) 


83
84
85
 
# File 'lib/appium_lib/common/helper.rb', line 83

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>) 


91
92
93
 
# File 'lib/appium_lib/common/helper.rb', line 91

def xpaths xpath_str
  find_elements :xpath, xpath_str
end