Module: Appium::Core::Base::SearchContext

Included in:

Driver, Selenium::WebDriver::Element

Defined in:

lib/appium_lib_core/common/base/search_context.rb

Constant Summary

FINDERS =

rubocop:disable Layout/AlignHash

::Selenium::WebDriver::SearchContext::FINDERS.merge(
  accessibility_id:     'accessibility id',
  image:                '-image',
  custom:               '-custom',
  # Android
  uiautomator:          '-android uiautomator', # Unavailable in Espresso
  viewtag:              '-android viewtag',     # Available in Espresso
  data_matcher:         '-android datamatcher', # Available in Espresso
  # iOS
  uiautomation:         '-ios uiautomation',
  predicate:            '-ios predicate string',
  class_chain:          '-ios class chain',
  # Windows with windows prefix
  windows_uiautomation: '-windows uiautomation',
  # Tizen with Tizen prefix
  tizen_uiautomation:   '-tizen uiautomation'
)

Instance Method Summary

• #find_element(*args) ⇒ Element

  rubocop:disable Metrics/LineLength.

• #find_elements(*args) ⇒ Object

  Find all elements matching the given arguments.

Instance Method Details

#find_element(how, what) ⇒ Element #find_element(opts) ⇒ Element

rubocop:disable Metrics/LineLength

Find the first element matching the given arguments

• Android can find with uiautomator like a UISelector.
• iOS can find with a UIAutomation command.
• iOS, only for XCUITest(WebDriverAgent), can find with a class chain

Find with image

Return an element if current view has a partial image. The logic depends on template matching by OpenCV. image-comparison

You can handle settings for the comparision following here

Espresso datamatcher

Espresso has an _onData_ matcher for more reference that allows you to target adapters instead of Views. This method find methods based on reflections

This is a selector strategy that allows users to pass a selector of the form:

{ name: '', args: ['arg1', 'arg2', '...'], class: '' }

• name: The name of a method to invoke. The method must return a Hamcrest Matcher
• args: The args provided to the method
• class: The class name that the method is part of (defaults to org.hamcrest.Matchers). Can be fully qualified, or simple, and simple defaults to androidx.test.espresso.matcher package (e.g.: class=CursorMatchers fully qualified is class=androidx.test.espresso.matcher.CursorMatchers

See example how to send datamatcher in Ruby client

rubocop:enable Metrics/LineLength

Examples:

Find element with each keys

# with accessibility id. All platforms.
@driver.find_elements :accessibility_id, 'Animation'
@driver.find_elements :accessibility_id, 'Animation'

# with base64 encoded template image. All platforms.
@driver.find_elements :image, Base64.strict_encode64(File.read(file_path))

# For Android
## With uiautomator
@driver.find_elements :uiautomator, 'new UiSelector().clickable(true)'
## With viewtag, but only for Espresso
## 'setTag'/'getTag' in https://developer.android.com/reference/android/view/View
@driver.find_elements :viewtag, 'new UiSelector().clickable(true)'
# With data_matcher. The argument should be JSON format.
@driver.find_elements :data_matcher, { name: 'hasEntry', args: %w(title Animation) }.to_json

# For iOS
## With :predicate
@driver.find_elements :predicate, "isWDVisible == 1"
@driver.find_elements :predicate, 'wdName == "Buttons"'
@driver.find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'

## With Class Chain
### select the third child button of the first child window element
@driver.find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
### select all the children windows
@driver.find_elements :class_chain, 'XCUIElementTypeWindow'
### select the second last child of the second child window
@driver.find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
### matching predicate. <code>'</code> is the mark.
@driver.find_elements :class_chain, 'XCUIElementTypeWindow['visible = 1]['name = "bla"']'
### containing predicate. '$' is the mark.
### Require appium-xcuitest-driver 2.54.0+. PR: https://github.com/facebook/WebDriverAgent/pull/707/files
@driver.find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
e = find_element :class_chain, "**/XCUIElementTypeWindow[$name == 'Buttons'$]"
e.tag_name #=> "XCUIElementTypeWindow"
e = find_element :class_chain, "**/XCUIElementTypeStaticText[$name == 'Buttons'$]"
e.tag_name #=> "XCUIElementTypeStaticText"

# For Windows
@driver.find_elements :windows_uiautomation, '....'

# For Tizen
@driver.find_elements :tizen_uiautomation, '....'

Overloads:

• #find_element(how, what) ⇒ Element

  Parameters:

  • how (Symbol, String) —

    The method to find the element by

  • what (String) —

    The locator to use

• #find_element(opts) ⇒ Element

  Parameters:

  • opts (Hash) —

    Find options

  Options Hash (opts):

  • :how (Symbol) —

    Key named after the method to find the element by, containing the locator

Returns:

• (Element)

Raises:

• (Error::NoSuchElementError) —

  if the element doesn't exist

# File 'lib/appium_lib_core/common/base/search_context.rb', line 131

def find_element(*args)
  how, what = extract_args(args)
  by = _set_by_from_finders(how)
  begin
    bridge.find_element_by by, what.to_s, ref
  rescue Selenium::WebDriver::Error::TimeOutError # will deprecate
    raise Selenium::WebDriver::Error::NoSuchElementError
  rescue Selenium::WebDriver::Error::TimeoutError
    raise Selenium::WebDriver::Error::NoSuchElementError
  end
end

#find_elements(*args) ⇒ Object

Find all elements matching the given arguments

See Also:

• #find_elements

# File 'lib/appium_lib_core/common/base/search_context.rb', line 148

def find_elements(*args)
  how, what = extract_args(args)
  by = _set_by_from_finders(how)
  begin
    bridge.find_elements_by by, what.to_s, ref
  rescue Selenium::WebDriver::Error::TimeOutError # will deprecate
    []
  rescue Selenium::WebDriver::Error::TimeoutError
    []
  end
end