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

Included in:

Driver, Element

Defined in:

lib/appium_lib_core/common/base/search_context.rb

Constant Summary

FINDERS =

referenced: ::Selenium::WebDriver::SearchContext

::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
  view_matcher:         '-android viewmatcher', # Available in Espresso
  # iOS
  predicate:            '-ios predicate string',
  class_chain:          '-ios class chain',
  # Windows with windows prefix
  # @deprecated
  windows_uiautomation: '-windows uiautomation',
  # Tizen with Tizen prefix
  tizen_uiautomation:   '-tizen uiautomation'
)

Instance Method Summary

• #find_element(*args) ⇒ Element

  rubocop:disable Layout/LineLength.

• #find_elements(*args) ⇒ Array<Selenium::WebDriver::Element>

  Find all elements matching the given arguments.

Instance Method Details

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

rubocop:disable Layout/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 viewmatcher and datamatcher

Espresso has onView matcher and 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: '<name>', args: ['arg1', 'arg2', '...'], class: '<optional 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 viewmatcher and datamatcher in Ruby client

rubocop:enable Layout/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
# @deprecated
@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 132

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
    raise Selenium::WebDriver::Error::NoSuchElementError
  end
end

#find_elements(*args) ⇒ Array<Selenium::WebDriver::Element>

Find all elements matching the given arguments

Returns:

• (Array<Selenium::WebDriver::Element>)

See Also:

• #find_elements

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

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
    []
  end
end