Skip to content

Commit 408b00e

Browse files
KazuCocoaKazuCocoa
authored
chore: add module and class to make them readable in docs (#588)
1 parent 589bfa0 commit 408b00e

File tree

3 files changed

+108
-100
lines changed

3 files changed

+108
-100
lines changed

‎lib/appium_lib_core/common/base/driver.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ class Driver < ::Selenium::WebDriver::Driver
3939

4040
include ::Appium::Core::Waitable
4141

42-
::Selenium::WebDriver::SearchContext.extra_finders = APPIUM_EXTRA_FINDERS
42+
::Selenium::WebDriver::SearchContext.extra_finders = ::Appium::Core::Base::SearchContext::APPIUM_EXTRA_FINDERS
4343

4444
# Private API.
4545
# Do not use this for general use. Used by flutter driver to get bridge for creating a new element

‎lib/appium_lib_core/common/base/search_context.rb

+106-98
Original file line numberDiff line numberDiff line change
@@ -12,102 +12,110 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15-
# rubocop:disable Layout/LineLength
16-
#
17-
# Find the first element matching the given arguments
18-
#
19-
# - Android can find with uiautomator like a {http://developer.android.com/tools/help/uiautomator/UiSelector.html UISelector}.
20-
# - iOS can find with a {https://developer.apple.com/library/ios/documentation/ToolsLanguages/Reference/UIAWindowClassReference/UIAWindow/UIAWindow.html#//apple_ref/doc/uid/TP40009930 UIAutomation command}.
21-
# - iOS, only for XCUITest(WebDriverAgent), can find with a {https://github.com/facebook/WebDriverAgent/wiki/Queries class chain}
22-
#
23-
# == Find with image
24-
# Return an element if current view has a partial image. The logic depends on template matching by OpenCV.
25-
# {https://github.com/appium/appium/blob/1.x/docs/en/writing-running-appium/image-comparison.md image-comparison}
26-
#
27-
# You can handle settings for the comparision following {https://github.com/appium/appium-base-driver/blob/master/lib/basedriver/device-settings.js#L6 here}
28-
#
29-
# == Espresso viewmatcher and datamatcher
30-
# Espresso has {https://developer.android.com/training/testing/espresso/basics _onView_ matcher}
31-
# and {https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf _onData_ matcher} for more reference
32-
# that allows you to target adapters instead of Views. This method find methods based on reflections
33-
#
34-
# This is a selector strategy that allows users to pass a selector of the form:
35-
#
36-
# <code>{ name: '<name>', args: ['arg1', 'arg2', '...'], class: '<optional class>' }</code>
37-
#
38-
# - _name_: The name of a method to invoke. The method must return
39-
# a Hamcrest {http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matcher.html Matcher}
40-
# - _args_: The args provided to the method
41-
# - _class_: The class name that the method is part of (defaults to <code>org.hamcrest.Matchers</code>).
42-
# Can be fully qualified, or simple, and simple defaults to <code>androidx.test.espresso.matcher</code> package
43-
# (e.g.: <code>class=CursorMatchers</code> fully qualified is <code>class=androidx.test.espresso.matcher.CursorMatchers</code>
44-
#
45-
# See example how to send viewmatcher and datamatcher in Ruby client
46-
#
47-
#
48-
# @overload find_element(how, what)
49-
# @param [Symbol, String] how The method to find the element by
50-
# @param [String] what The locator to use
51-
#
52-
# @overload find_element(opts)
53-
# @param [Hash] opts Find options
54-
# @option opts [Symbol] :how Key named after the method to find the element by, containing the locator
55-
# @return [Element]
56-
# @raise [Error::NoSuchElementError] if the element doesn't exist
57-
#
58-
# @example Find element with each keys
59-
#
60-
# # with accessibility id. All platforms.
61-
# @driver.find_elements :accessibility_id, 'Animation'
62-
# @driver.find_elements :accessibility_id, 'Animation'
63-
#
64-
# # with base64 encoded template image. All platforms.
65-
# @driver.find_elements :image, Base64.strict_encode64(File.read(file_path))
66-
#
67-
# # For Android
68-
# ## With uiautomator
69-
# @driver.find_elements :uiautomator, 'new UiSelector().clickable(true)'
70-
# ## With viewtag, but only for Espresso
71-
# ## 'setTag'/'getTag' in https://developer.android.com/reference/android/view/View
72-
# @driver.find_elements :viewtag, 'new UiSelector().clickable(true)'
73-
# # With data_matcher. The argument should be JSON format.
74-
# @driver.find_elements :data_matcher, { name: 'hasEntry', args: %w(title Animation) }.to_json
75-
#
76-
# # For iOS
77-
# ## With :predicate
78-
# @driver.find_elements :predicate, "isWDVisible == 1"
79-
# @driver.find_elements :predicate, 'wdName == "Buttons"'
80-
# @driver.find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'
81-
#
82-
# ## With Class Chain
83-
# ### select the third child button of the first child window element
84-
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
85-
# ### select all the children windows
86-
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow'
87-
# ### select the second last child of the second child window
88-
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
89-
# ### matching predicate. <code>'</code> is the mark.
90-
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow['visible = 1]['name = "bla"']'
91-
# ### containing predicate. '$' is the mark.
92-
# ### Require appium-xcuitest-driver 2.54.0+. PR: https://github.com/facebook/WebDriverAgent/pull/707/files
93-
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
94-
# e = find_element :class_chain, "**/XCUIElementTypeWindow[$name == 'Buttons'$]"
95-
# e.tag_name #=> "XCUIElementTypeWindow"
96-
# e = find_element :class_chain, "**/XCUIElementTypeStaticText[$name == 'Buttons'$]"
97-
# e.tag_name #=> "XCUIElementTypeStaticText"
98-
#
99-
# rubocop:enable Layout/LineLength
15+
module Appium
16+
module Core
17+
class Base
18+
module SearchContext
19+
# rubocop:disable Layout/LineLength
20+
#
21+
# Find the first element matching the given arguments
22+
#
23+
# - Android can find with uiautomator like a {http://developer.android.com/tools/help/uiautomator/UiSelector.html UISelector}.
24+
# - iOS can find with a {https://developer.apple.com/library/ios/documentation/ToolsLanguages/Reference/UIAWindowClassReference/UIAWindow/UIAWindow.html#//apple_ref/doc/uid/TP40009930 UIAutomation command}.
25+
# - iOS, only for XCUITest(WebDriverAgent), can find with a {https://github.com/facebook/WebDriverAgent/wiki/Queries class chain}
26+
#
27+
# == Find with image
28+
# Return an element if current view has a partial image. The logic depends on template matching by OpenCV.
29+
# {https://github.com/appium/appium/blob/1.x/docs/en/writing-running-appium/image-comparison.md image-comparison}
30+
#
31+
# You can handle settings for the comparision following {https://github.com/appium/appium-base-driver/blob/master/lib/basedriver/device-settings.js#L6 here}
32+
#
33+
# == Espresso viewmatcher and datamatcher
34+
# Espresso has {https://developer.android.com/training/testing/espresso/basics _onView_ matcher}
35+
# and {https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf _onData_ matcher} for more reference
36+
# that allows you to target adapters instead of Views. This method find methods based on reflections
37+
#
38+
# This is a selector strategy that allows users to pass a selector of the form:
39+
#
40+
# <code>{ name: '<name>', args: ['arg1', 'arg2', '...'], class: '<optional class>' }</code>
41+
#
42+
# - _name_: The name of a method to invoke. The method must return
43+
# a Hamcrest {http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matcher.html Matcher}
44+
# - _args_: The args provided to the method
45+
# - _class_: The class name that the method is part of (defaults to <code>org.hamcrest.Matchers</code>).
46+
# Can be fully qualified, or simple, and simple defaults to <code>androidx.test.espresso.matcher</code> package
47+
# (e.g.: <code>class=CursorMatchers</code> fully qualified is <code>class=androidx.test.espresso.matcher.CursorMatchers</code>
48+
#
49+
# See example how to send viewmatcher and datamatcher in Ruby client
50+
#
51+
#
52+
# @overload find_element(how, what)
53+
# @param [Symbol, String] how The method to find the element by
54+
# @param [String] what The locator to use
55+
#
56+
# @overload find_element(opts)
57+
# @param [Hash] opts Find options
58+
# @option opts [Symbol] :how Key named after the method to find the element by, containing the locator
59+
# @return [Element]
60+
# @raise [Error::NoSuchElementError] if the element doesn't exist
61+
#
62+
# @example Find element with each keys
63+
#
64+
# # with accessibility id. All platforms.
65+
# @driver.find_elements :accessibility_id, 'Animation'
66+
# @driver.find_elements :accessibility_id, 'Animation'
67+
#
68+
# # with base64 encoded template image. All platforms.
69+
# @driver.find_elements :image, Base64.strict_encode64(File.read(file_path))
70+
#
71+
# # For Android
72+
# ## With uiautomator
73+
# @driver.find_elements :uiautomator, 'new UiSelector().clickable(true)'
74+
# ## With viewtag, but only for Espresso
75+
# ## 'setTag'/'getTag' in https://developer.android.com/reference/android/view/View
76+
# @driver.find_elements :viewtag, 'new UiSelector().clickable(true)'
77+
# # With data_matcher. The argument should be JSON format.
78+
# @driver.find_elements :data_matcher, { name: 'hasEntry', args: %w(title Animation) }.to_json
79+
#
80+
# # For iOS
81+
# ## With :predicate
82+
# @driver.find_elements :predicate, "isWDVisible == 1"
83+
# @driver.find_elements :predicate, 'wdName == "Buttons"'
84+
# @driver.find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'
85+
#
86+
# ## With Class Chain
87+
# ### select the third child button of the first child window element
88+
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
89+
# ### select all the children windows
90+
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow'
91+
# ### select the second last child of the second child window
92+
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
93+
# ### matching predicate. <code>'</code> is the mark.
94+
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow['visible = 1]['name = "bla"']'
95+
# ### containing predicate. '$' is the mark.
96+
# ### Require appium-xcuitest-driver 2.54.0+. PR: https://github.com/facebook/WebDriverAgent/pull/707/files
97+
# @driver.find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
98+
# e = find_element :class_chain, "**/XCUIElementTypeWindow[$name == 'Buttons'$]"
99+
# e.tag_name #=> "XCUIElementTypeWindow"
100+
# e = find_element :class_chain, "**/XCUIElementTypeStaticText[$name == 'Buttons'$]"
101+
# e.tag_name #=> "XCUIElementTypeStaticText"
102+
#
103+
# rubocop:enable Layout/LineLength
100104

101-
APPIUM_EXTRA_FINDERS = {
102-
accessibility_id: 'accessibility id',
103-
image: '-image',
104-
custom: '-custom',
105-
# Android
106-
uiautomator: '-android uiautomator', # Unavailable in Espresso
107-
viewtag: '-android viewtag', # Available in Espresso
108-
data_matcher: '-android datamatcher', # Available in Espresso
109-
view_matcher: '-android viewmatcher', # Available in Espresso
110-
# iOS
111-
predicate: '-ios predicate string',
112-
class_chain: '-ios class chain'
113-
}.freeze
105+
APPIUM_EXTRA_FINDERS = {
106+
accessibility_id: 'accessibility id',
107+
image: '-image',
108+
custom: '-custom',
109+
# Android
110+
uiautomator: '-android uiautomator', # Unavailable in Espresso
111+
viewtag: '-android viewtag', # Available in Espresso
112+
data_matcher: '-android datamatcher', # Available in Espresso
113+
view_matcher: '-android viewmatcher', # Available in Espresso
114+
# iOS
115+
predicate: '-ios predicate string',
116+
class_chain: '-ios class chain'
117+
}.freeze
118+
end
119+
end
120+
end
121+
end

‎lib/appium_lib_core/element.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ module Core
1919
class Element < ::Selenium::WebDriver::Element
2020
include ::Appium::Core::Base::TakesScreenshot
2121

22-
::Selenium::WebDriver::SearchContext.extra_finders = APPIUM_EXTRA_FINDERS
22+
::Selenium::WebDriver::SearchContext.extra_finders = ::Appium::Core::Base::SearchContext::APPIUM_EXTRA_FINDERS
2323

2424
# Retuns the element id.
2525
#

0 commit comments

Comments
 (0)