testa_appium_driver 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '091ff22c4f74ee0e70238adf6d044b93d7b989954c8080b8d7e289d917fe6986'
-  data.tar.gz: ce33cac99f7631febd8c362e0b74160e29180a4271ab0218c6932757736601e8
+  metadata.gz: ae8c1d10792a04508f11afa6d0b58380d60ba4f079eba2caed9707a5ae036e95
+  data.tar.gz: 47b0ca0facbc1cccaddc5a5efd4c2bcadd53f4ac4e8a66f6b4c2f89334cca8ee
 SHA512:
-  metadata.gz: b5981dc66c90872097718763169e90e717edeafaae3f551785be38e01dc0594d81f771269873042ed998ad5733267db6d0ac74749e00287fd275895a7dab84f5
-  data.tar.gz: 62cb8fa7ed7405a8c0a36fbefab4c304520316286428e61ae3380b918ac65e189aa71cb7ab67552a2798b099f75771ecde55f32b1587ee082f33f9a30a3c6bf8
+  metadata.gz: 62cf8d80a49626ffc88709afde4f408c535e53a25352058a36476c3b9791792b0f5cf17d45e3ac52c228b10909c4e67093c94d5dd6347147e3dce398b7cc18f4
+  data.tar.gz: 265b1b055eec368481790df7c50c78b9f803dbd64286d50b60e37fbe1b8bba6a004f9dadf0c07a6fa688f3ce19c0ba190b914aff97296c19214cbfa10b9be0c0

data/.idea/deployment.xml

@@ -5,7 +5,7 @@
       <paths name="supertesta.com">
         <serverdata>
           <mappings>
-            <mapping local="$PROJECT_DIR$" web="/" />
+            <mapping deploy="/testa_docker/path_data/testa_appium_driver" local="$PROJECT_DIR$" web="/" />
           </mappings>
         </serverdata>
       </paths>

data/lib/testa_appium_driver/android/class_selectors.rb

@@ -20,12 +20,14 @@ module TestaAppiumDriver
       end
     end
 
+    # first element that match given selectors
     # @param selectors [Hash]
     # @return [TestaAppiumDriver::Locator] first element
     def element(selectors = {})
       add_selector(selectors)
     end
 
+    # all elements that match given selectors
     # @param params [Hash]
     # @return [TestaAppiumDriver::Locator] all elements that match given selectors
     def elements(params = {})
@@ -34,6 +36,7 @@ module TestaAppiumDriver
     end
 
 
+    # first element that has scrollable: true
     # @param selectors [Hash]
     # @return [TestaAppiumDriver::Locator] first scrollable element
     def scrollable(selectors = {})
@@ -41,6 +44,7 @@ module TestaAppiumDriver
       add_selector(selectors)
     end
 
+    # all elements that have scrollable: true
     # @param params [Hash]
     # @return [TestaAppiumDriver::Locator] first scrollable element
     def scrollables(params = {})
@@ -50,12 +54,14 @@ module TestaAppiumDriver
     end
 
 
+    # first android.widget.ImageView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def image_view(params = {})
       params[:class] = "android.widget.ImageView"
       add_selector(params)
     end
 
+    # all android.widget.ImageView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def image_views(params = {})
       params[:class] = "android.widget.ImageView"
@@ -63,12 +69,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.FrameLayout element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def frame_layout(params = {})
       params[:class] = "android.widget.FrameLayout"
       add_selector(params)
     end
 
+    # all android.widget.FrameLayout elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def frame_layouts(params = {})
       params[:class] = "android.widget.FrameLayout"
@@ -76,12 +84,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.LinearLayout element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def linear_layout(params = {})
       params[:class] = "android.widget.LinearLayout"
       add_selector(params)
     end
 
+    # all android.widget.LinearLayout elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def linear_layouts(params = {})
       params[:class] = "android.widget.LinearLayout"
@@ -89,12 +99,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.view.View element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def view(params = {})
       params[:class] = "android.view.View"
       add_selector(params)
     end
 
+    # all android.view.View elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def views(params = {})
       params[:class] = "android.view.View"
@@ -102,12 +114,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.EditText element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def edit_text(params = {})
       params[:class] = "android.widget.EditText"
       add_selector(params)
     end
 
+    # all android.widget.EditText elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def edit_texts(params = {})
       params[:class] = "android.widget.EditText"
@@ -115,12 +129,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.ViewGroup element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def view_group(params = {})
       params[:class] = "android.widget.ViewGroup"
       add_selector(params)
     end
 
+    # all android.widget.ViewGroup elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def view_groups(params = {})
       params[:class] = "android.widget.ViewGroup"
@@ -128,12 +144,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.RelativeLayout element that match given selecotrs
     # @return [TestaAppiumDriver::Locator]
     def relative_layout(params = {})
       params[:class] = "android.widget.RelativeLayout"
       add_selector(params)
     end
 
+    # all android.widget.RelativeLayout elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def relative_layouts(params = {})
       params[:class] = "android.widget.RelativeLayout"
@@ -141,12 +159,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first androidx.recyclerview.widget.RecyclerView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def recycler_view(params = {})
       params[:class] = "androidx.recyclerview.widget.RecyclerView"
       add_selector(params)
     end
 
+    # all androidx.recyclerview.widget.RecyclerView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def recycler_views(params = {})
       params[:class] = "androidx.recyclerview.widget.RecyclerView"
@@ -154,12 +174,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.Button element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def button(params = {})
       params[:class] = "android.widget.Button"
       add_selector(params)
     end
 
+    # all android.widget.Button elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def buttons(params = {})
       params[:class] = "android.widget.Button"
@@ -167,12 +189,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.ImageButton element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def image_button(params = {})
       params[:class] = "android.widget.ImageButton"
       add_selector(params)
     end
 
+    # all android.widget.ImageButton elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def image_buttons(params = {})
       params[:class] = "android.widget.ImageButton"
@@ -180,12 +204,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.HorizontalScrollView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def horizontal_scroll_view(params = {})
       params[:class] = "android.widget.HorizontalScrollView"
       add_selector(params)
     end
 
+    # all android.widget.HorizontalScrollView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def horizontal_scroll_views(params = {})
       params[:class] = "android.widget.HorizontalScrollView"
@@ -193,12 +219,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.ScrollView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def scroll_view(params = {})
       params[:class] = "android.widget.ScrollView"
       add_selector(params)
     end
 
+    # all android.widget.ScrollView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def scroll_views(params = {})
       params[:class] = "android.widget.ScrollView"
@@ -206,12 +234,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first viewpager.widget.ViewPager element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def view_pager(params = {})
       params[:class] = "androidx.viewpager.widget.ViewPager"
       add_selector(params)
     end
 
+    # all viewpager.widget.ViewPager elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def view_pagers(params = {})
       params[:class] = "androidx.viewpager.widget.ViewPager"
@@ -219,12 +249,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.CheckBox element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def check_box(params = {})
       params[:class] = "android.widget.CheckBox"
       add_selector(params)
     end
 
+    # all android.widget.CheckBox elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def check_boxes(params = {})
       params[:class] = "android.widget.CheckBox"
@@ -232,12 +264,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.ListView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def list_view(params = {})
       params[:class] = "android.widget.ListView"
       add_selector(params)
     end
 
+    # all android.widget.ListView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def list_views(params = {})
       params[:class] = "android.widget.ListView"
@@ -245,12 +279,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.ProgressBar element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def progress_bar(params = {})
       params[:class] = "android.widget.ProgressBar"
       add_selector(params)
     end
 
+    # all android.widget.ProgressBar elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def progress_bars(params = {})
       params[:class] = "android.widget.ProgressBar"
@@ -258,12 +294,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.RadioButton element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def radio_button(params = {})
       params[:class] = "android.widget.RadioButton"
       add_selector(params)
     end
 
+    # all android.widget.RadioButton elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def radio_buttons(params = {})
       params[:class] = "android.widget.RadioButton"
@@ -271,12 +309,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.RadioGroup element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def radio_group(params = {})
       params[:class] = "android.widget.RadioGroup"
       add_selector(params)
     end
 
+    # all android.widget.RadioGroup elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def radio_groups(params = {})
       params[:class] = "android.widget.RadioGroup"
@@ -284,12 +324,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.SearchView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def search_view(params = {})
       params[:class] = "android.widget.SearchView"
       add_selector(params)
     end
 
+    # all android.widget.SearchView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def search_views(params = {})
       params[:class] = "android.widget.SearchView"
@@ -297,12 +339,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.Spinner element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def spinner(params = {})
       params[:class] = "android.widget.Spinner"
       add_selector(params)
     end
 
+    # all android.widget.Spinner elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def spinners(params = {})
       params[:class] = "android.widget.Spinner"
@@ -310,12 +354,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.Toast element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def toast(params = {})
       params[:class] = "android.widget.Toast"
       add_selector(params)
     end
 
+    # all android.widget.Toast elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def toasts(params = {})
       params[:class] = "android.widget.Toast"
@@ -323,12 +369,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.Toolbar element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def toolbar(params = {})
       params[:class] = "android.widget.Toolbar"
       add_selector(params)
     end
 
+    # all android.widget.Toolbar elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def toolbars(params = {})
       params[:class] = "android.widget.Toolbar"
@@ -336,12 +384,14 @@ module TestaAppiumDriver
       add_selector(params)
     end
 
+    # first android.widget.TextView element that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def text_view(params = {})
       params[:class] = "android.widget.TextView"
       add_selector(params)
     end
 
+    # all android.widget.TextView elements that match given selectors
     # @return [TestaAppiumDriver::Locator]
     def text_views(params = {})
       params[:class] = "android.widget.TextView"

data/lib/testa_appium_driver/android/driver.rb

@@ -8,11 +8,11 @@ module TestaAppiumDriver
     include ClassSelectors
 
 
+    # executes shell command
     # @param [String] command Shell command name to execute for example echo or rm
     # @param [Array<String>] args Array of command arguments, example: ['-f', '/sdcard/my_file.txt']
     # @param [Integer] timeout Command timeout in milliseconds. If the command blocks for longer than this timeout then an exception is going to be thrown. The default timeout is 20000 ms
     # @param [Boolean] includeStderr 	Whether to include stderr stream into the returned result.
-    #noinspection RubyParameterNamingConvention
     def shell(command, args: nil, timeout: nil, includeStderr: true)
       params = {
           command: command,
@@ -24,6 +24,7 @@ module TestaAppiumDriver
     end
 
 
+    private
     def handle_testa_opts
       if @testa_opts[:default_find_strategy].nil?
         @default_find_strategy = DEFAULT_ANDROID_FIND_STRATEGY

data/lib/testa_appium_driver/android/locator.rb

@@ -75,7 +75,7 @@ module TestaAppiumDriver
     end
 
 
-    # @return [Locator] existing locator element
+    # @return [Locator] new child locator element
     def add_child_selector(params)
       params, selectors = extract_selectors_from_params(params)
       single = params[:single]

data/lib/testa_appium_driver/common/locator/scroll_actions.rb

@@ -2,6 +2,7 @@ module TestaAppiumDriver
   #noinspection RubyTooManyMethodsInspection
   class Locator
 
+    # performs a long tap on the retrieved element
     # @param [Float] duration in seconds
     def long_tap(duration = LONG_TAP_DURATION)
       action_builder = @driver.action
@@ -15,173 +16,238 @@ module TestaAppiumDriver
       @driver.perform_actions [f1]
     end
 
-    # @return [Array] array of [Selenium::WebDriver::Element]
-    def each(deadzone: nil, skip_scroll_to_start: false, &block)
+
+    # scrolls to the start of the scrollable containers and scrolls to the end,
+    # everytime a locator element is found the given block is executed
+    # @return [Array<Selenium::WebDriver::Element>]
+    def each(top: nil, bottom: nil, right: nil, left: nil, direction: nil, &block)
+      deadzone = _process_deadzone(top, bottom, right, left)
       raise "Each can only be performed on multiple elements locator" if @single
       deadzone = @scrollable_locator.scroll_deadzone if deadzone.nil? && !@scrollable_locator.nil?
       sa = ScrollActions.new(@scrollable_locator,
                              locator: self,
                              deadzone: deadzone,
                              default_scroll_strategy: @default_scroll_strategy)
-      sa.each(skip_scroll_to_start, &block)
+      if direction.nil?
+        sa.each(&block)
+      else
+        sa.send("each_#{direction}", &block)
+      end
+    end
+
+    # scrolls down from the current page view (without prior scrolling to the top) and
+    # everytime a locator element is found the given block is executed
+    # @return [Array<Selenium::WebDriver::Element>]
+    def each_down(top: nil, bottom: nil, right: nil, left: nil, &block)
+      each(top: top, bottom: bottom, right: right, left: left, direction: :down, &block)
+    end
+
+    # scrolls up from the current page view (without prior scrolling to the bottom) and
+    # everytime a locator element is found the given block is executed
+    # @return [Array<Selenium::WebDriver::Element>]
+    def each_up(top: nil, bottom: nil, right: nil, left: nil, &block)
+      each(top: top, bottom: bottom, right: right, left: left, direction: :up, &block)
+    end
+
+    # scrolls right from the current page view (without prior scrolling to the left) and
+    # everytime a locator element is found the given block is executed
+    # @return [Array<Selenium::WebDriver::Element>]
+    def each_right(top: nil, bottom: nil, right: nil, left: nil, &block)
+      each(top: top, bottom: bottom, right: right, left: left, direction: :right, &block)
+    end
+
+    # scrolls left from the current page view (without prior scrolling to the right) and
+    # everytime a locator element is found the given block is executed
+    # @return [Array<Selenium::WebDriver::Element>]
+    def each_left(top: nil, bottom: nil, right: nil, left: nil, &block)
+      each(top: top, bottom: bottom, right: right, left: left, direction: :left, &block)
     end
 
 
     # Aligns element (by default) on top of the scrollable container, if the element does not exists it will scroll to find it
+    # The element is aligned if the the distance from the top/bottom/right/left of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align(with = :top, deadzone: nil, raise: false)
+    def align(with = :top, top: nil, bottom: nil, right: nil, left: nil, scroll_to_find: false)
       deadzone = @scrollable_locator.scroll_deadzone if deadzone.nil? && !@scrollable_locator.nil?
       sa = ScrollActions.new(@scrollable_locator,
                              locator: self,
                              deadzone: deadzone,
-                             default_scroll_strategy: @default_scroll_strategy,
-                             raise: raise)
-      sa.align(with)
+                             default_scroll_strategy: @default_scroll_strategy)
+      sa.align(with, scroll_to_find)
       self
     end
 
     # Aligns element on top of the scrollable container, if the element does not exists it will scroll to find it
+    # The element is aligned if the the distance from the top of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_top(deadzone: nil)
-      align(:top, deadzone: deadzone)
+    def align_top(top: nil, bottom: nil, right: nil, left: nil)
+      align(:top, top: top, bottom: bottom, right: right, left: left)
     end
 
     # Aligns element on bottom of the scrollable container, if the element does not exists it will scroll to find it
+    # The element is aligned if the the distance from the bottom of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_bottom(deadzone: nil)
-      align(:bottom, deadzone: deadzone)
+    def align_bottom(top: nil, bottom: nil, right: nil, left: nil)
+      align(:bottom, top: top, bottom: bottom, right: right, left: left)
     end
 
     # Aligns element on left of the scrollable container, if the element does not exists it will scroll to find it
+    # The element is aligned if the the distance from the left of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_left(deadzone: nil)
-      align(:left, deadzone: deadzone)
+    def align_left(top: nil, bottom: nil, right: nil, left: nil)
+      align(:left, top: top, bottom: bottom, right: right, left: left)
     end
 
     # Aligns element on right of the scrollable container, if the element does not exists it will scroll to find it
+    # The element is aligned if the the distance from the right of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_right(deadzone: nil)
-      align(:right, deadzone: deadzone)
+    def align_right(top: nil, bottom: nil, right: nil, left: nil)
+      align(:right, top: top, bottom: bottom, right: right, left: left)
     end
 
     # Aligns element (by default) on top of the scrollable container, if the element does not exists it raise an exception
+    # The element is aligned if the the distance from the top/bottom/right/left of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align!(with = :top, deadzone: nil)
-      align(with, deadzone: deadzone, raise: true)
+    def align!(with = :top, top: nil, bottom: nil, right: nil, left: nil)
+      align(with, top: top, bottom: bottom, right: right, left: left, scroll_to_find: true)
     end
 
     # Aligns element on top of the scrollable container, if the element does not exists it raise an exception
+    # The element is aligned if the the distance from the top of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_top!(deadzone: nil)
-      align(:top, deadzone: deadzone, raise: true)
+    def align_top!(top: nil, bottom: nil, right: nil, left: nil)
+      align(:top, top: top, bottom: bottom, right: right, left: left, scroll_to_find: true)
     end
 
     # Aligns element on bottom of the scrollable container, if the element does not exists it raise an exception
+    # The element is aligned if the the distance from the bottom of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_bottom!(deadzone: nil)
-      align(:bottom, deadzone: deadzone, raise: true)
+    def align_bottom!(top: nil, bottom: nil, right: nil, left: nil)
+      align(:bottom, top: top, bottom: bottom, right: right, left: left, scroll_to_find: true)
     end
 
     # Aligns element on left of the scrollable container, if the element does not exists it raise an exception
+    # The element is aligned if the the distance from the left of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_left!(deadzone: nil)
-      align(:left, deadzone: deadzone, raise: true)
+    def align_left!(top: nil, bottom: nil, right: nil, left: nil)
+      align(:left, top: top, bottom: bottom, right: right, left: left, scroll_to_find: true)
     end
 
     # Aligns element on right of the scrollable container, if the element does not exists it raise an exception
+    # The element is aligned if the the distance from the right of the scrollable container is less than [TestaAppiumDriver::SCROLL_ALIGNMENT_THRESHOLD]
+    # If the distance is greater than the threshold, it will attempt to realign it up to 2 more times.
+    # The retry mechanism allows alignment even for dynamic layouts when elements are hidden/show when scrolling to certain direction
     # @return [TestaAppiumDriver::Locator]
-    def align_right!(deadzone: nil)
-      align(:right, deadzone: deadzone, raise: true)
+    def align_right!(top: nil, bottom: nil, right: nil, left: nil)
+      align(:right, top: top, bottom: bottom, right: right, left: left, scroll_to_find: true)
     end
 
 
     # First scrolls to the beginning of the scrollable container and then scrolls down until element is found or end is reached
     # @return [TestaAppiumDriver::Locator]
-    def scroll_to(deadzone: nil, max_scrolls: nil, direction: nil)
+    def scroll_to(top: nil, bottom: nil, right: nil, left: nil, max_scrolls: nil, direction: nil)
       if direction
-        _scroll_dir_to(deadzone, max_scrolls, direction)
+        _scroll_dir_to(_process_deadzone(top, bottom, right, left), max_scrolls, direction)
       else
-        _scroll_to(deadzone, max_scrolls)
+        _scroll_to(_process_deadzone(top, bottom, right, left), max_scrolls)
       end
     end
 
 
     # Scrolls down until element is found or end is reached
     # @return [TestaAppiumDriver::Locator]
-    def scroll_down_to(deadzone: nil, max_scrolls: nil)
-      _scroll_dir_to(deadzone, max_scrolls, :down)
+    def scroll_down_to(top: nil, bottom: nil, right: nil, left: nil, max_scrolls: nil)
+      _scroll_dir_to(_process_deadzone(top, bottom, right, left), max_scrolls, :down)
     end
 
     # Scrolls up until element is found or end is reached
     # @return [TestaAppiumDriver::Locator]
-    def scroll_up_to(deadzone: nil, max_scrolls: nil)
-      _scroll_dir_to(deadzone, max_scrolls, :up)
+    def scroll_up_to(top: nil, bottom: nil, right: nil, left: nil, max_scrolls: nil)
+      _scroll_dir_to(_process_deadzone(top, bottom, right, left), max_scrolls, :up)
     end
 
     # Scrolls right until element is found or end is reached
     # @return [TestaAppiumDriver::Locator]
-    def scroll_right_to(deadzone: nil, max_scrolls: nil)
-      _scroll_dir_to(deadzone, max_scrolls, :right)
+    def scroll_right_to(top: nil, bottom: nil, right: nil, left: nil, max_scrolls: nil)
+      _scroll_dir_to(_process_deadzone(top, bottom, right, left), max_scrolls, :right)
     end
 
 
     # Scrolls left until element is found or end is reached
     # @return [TestaAppiumDriver::Locator]
-    def scroll_left_to(deadzone: nil, max_scrolls: nil)
-      _scroll_dir_to(deadzone, max_scrolls, :left)
+    def scroll_left_to(top: nil, bottom: nil, right: nil, left: nil, max_scrolls: nil)
+      _scroll_dir_to(_process_deadzone(top, bottom, right, left), max_scrolls, :left)
     end
 
     # Scrolls to the start of the scrollable container (top on vertical container, left on horizontal)
     # @return [TestaAppiumDriver::Locator]
-    def scroll_to_start(deadzone: nil)
-      _scroll_to_start_or_end(:start, deadzone)
+    def scroll_to_start(top: nil, bottom: nil, right: nil, left: nil)
+      _scroll_to_start_or_end(:start, _process_deadzone(top, bottom, right, left))
     end
 
     # Scrolls to the end of the scrollable container (bottom on vertical container, right on horizontal)
     # @return [TestaAppiumDriver::Locator]
-    def scroll_to_end(deadzone: nil)
-      _scroll_to_start_or_end(:end, deadzone)
+    def scroll_to_end(top: nil, bottom: nil, right: nil, left: nil)
+      _scroll_to_start_or_end(:end, _process_deadzone(top, bottom, right, left))
     end
 
 
     # @return [TestaAppiumDriver::Locator]
-    def page_down(deadzone: nil)
-      _page(:down, deadzone)
+    def page_down(top: nil, bottom: nil, right: nil, left: nil)
+      _page(:down, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def page_up(deadzone: nil)
-      _page(:up, deadzone)
+    def page_up(top: nil, bottom: nil, right: nil, left: nil)
+      _page(:up, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def page_left(deadzone: nil)
-      _page(:left, deadzone)
+    def page_left(top: nil, bottom: nil, right: nil, left: nil)
+      _page(:left, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def page_right(deadzone: nil)
-      _page(:right, deadzone)
+    def page_right(top: nil, bottom: nil, right: nil, left: nil)
+      _page(:right, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def fling_down(deadzone: nil)
-      _fling(:down, deadzone)
+    def fling_down(top: nil, bottom: nil, right: nil, left: nil)
+      _fling(:down, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def fling_up(deadzone: nil)
-      _fling(:up, deadzone)
+    def fling_up(top: nil, bottom: nil, right: nil, left: nil)
+      _fling(:up, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def fling_left(deadzone: nil)
-      _fling(:left, deadzone)
+    def fling_left(top: nil, bottom: nil, right: nil, left: nil)
+      _fling(:left, _process_deadzone(top, bottom, right, left))
     end
 
     # @return [TestaAppiumDriver::Locator]
-    def fling_right(deadzone: nil)
-      _fling(:right, deadzone)
+    def fling_right(top: nil, bottom: nil, right: nil, left: nil)
+      _fling(:right, _process_deadzone(top, bottom, right, left))
     end
 
 
@@ -232,6 +298,18 @@ module TestaAppiumDriver
 
 
     private
+    def _process_deadzone(top, bottom, right, left)
+      deadzone = nil
+      if !top.nil? || !bottom.nil? || !right.nil? || !left.nil?
+        deadzone = {}
+        deadzone[:top] = top unless top.nil?
+        deadzone[:bottom] = bottom unless bottom.nil?
+        deadzone[:right] = right unless right.nil?
+        deadzone[:left] = left unless left.nil?
+      end
+      deadzone
+    end
+
     def _drag_to(x, y)
       sa = ScrollActions.new(@scrollable_locator,
                              locator: self,
@@ -239,6 +317,8 @@ module TestaAppiumDriver
       sa.drag_to(x, y)
       self
     end
+
+
     def _page(direction, deadzone)
       deadzone = @scrollable_locator.scroll_deadzone if deadzone.nil? && !@scrollable_locator.nil?
       sa = ScrollActions.new(@scrollable_locator,
@@ -266,7 +346,6 @@ module TestaAppiumDriver
       sa = ScrollActions.new(@scrollable_locator,
                              locator: self,
                              deadzone: deadzone,
-                             direction: :left,
                              default_scroll_strategy: @default_scroll_strategy)
       if type == :start
         sa.scroll_to_start
@@ -293,7 +372,6 @@ module TestaAppiumDriver
                              locator: self,
                              deadzone: deadzone,
                              max_scrolls: max_scrolls,
-                             direction: direction,
                              default_scroll_strategy: @default_scroll_strategy)
 
       sa.send("scroll_#{direction}_to")

data/lib/testa_appium_driver/common/locator.rb

@@ -79,6 +79,7 @@ module TestaAppiumDriver
     # method missing is used to fetch the element before executing additional commands like click, send_key, count
     def method_missing(method, *args, &block)
       execute.send(method, *args, &block)
+      @driver.invalidate_cache
     end
 
 

data/lib/testa_appium_driver/common/scroll_actions/w3c_scroll_actions.rb

@@ -3,7 +3,7 @@ module TestaAppiumDriver
 
     private
     # @return [Array]
-    def w3c_each(skip_scroll_to_start, &block)
+    def w3c_each(direction, &block)
       elements = []
       begin
         @driver.disable_wait_for_idle
@@ -13,7 +13,14 @@ module TestaAppiumDriver
         iterations = 0
 
 
-        scroll_to_start unless skip_scroll_to_start
+        if direction.nil?
+          scroll_to_start
+          if @scrollable.scroll_orientation == :vertical
+            direction = :down
+          else
+            direction = :right
+          end
+        end
 
         until is_end_of_scroll?
           matches = @locator.execute(skip_cache: true)
@@ -27,6 +34,7 @@ module TestaAppiumDriver
           end
           iterations += 1
           break if !@max_scrolls.nil? && iterations == @max_scrolls
+          self.send("page_#{direction}")
         end
       rescue => e
         raise e
@@ -37,13 +45,13 @@ module TestaAppiumDriver
       elements
     end
 
-    def w3c_align(with)
+    def w3c_align(with, scroll_to_find)
       @driver.disable_wait_for_idle
       default_deadzone!
 
 
 
-      @locator.scroll_to unless @raise # called with !
+      @locator.scroll_to if scroll_to_find
 
       element = @locator.execute
       @driver.disable_implicit_wait

data/lib/testa_appium_driver/common/scroll_actions.rb

@@ -3,19 +3,24 @@ require_relative 'scroll_actions/w3c_scroll_actions'
 
 
 module TestaAppiumDriver
-  #noinspection RubyResolve,RubyTooManyInstanceVariablesInspection
-  class ScrollActions
 
+  # Class for handling scroll actions
+  class ScrollActions
+    # @param [TestaAppiumDriver::Locator, nil] scrollable container that will be used to determine the bounds for scrolling
+    # @param [Hash] params
+    #   acceptable params
+    #     - locator - element that should be found with scrolling actions
+    #     - deadzone - [Hash] that stores top, bottom, left and right deadzone values. If deadzone[:top] is 200 then 200px from top of the scrollable container will not be used for scrolling
+    #     - max_scrolls - [Integer] maximum number of scrolls before exception is thrown
+    #     - default_scroll_strategy - defines which scroll strategy will be used if a scroll action is valid for multiple strategies
     def initialize(scrollable, params = {})
       @scrollable = scrollable
       @locator = params[:locator]
       @deadzone = params[:deadzone]
-      @direction = params[:direction]
       @max_scrolls = params[:max_scrolls]
       @default_scroll_strategy = params[:default_scroll_strategy]
       @driver = @locator.driver
 
-      @raise = params[:raise]
 
       if @scrollable.nil?
         # if we dont have a scrollable element or if we do have it, but it is not compatible with uiautomator
@@ -35,16 +40,33 @@ module TestaAppiumDriver
     end
 
 
-    def align(with)
-      w3c_align(with)
+    def align(with, scroll_to_find)
+      w3c_align(with, scroll_to_find)
       @locator
     end
 
     # @return [Array]
-    def each(skip_scroll_to_start, &block)
-      w3c_each(skip_scroll_to_start, &block)
+    def each(&block)
+      w3c_each(nil, &block)
+    end
+
+    def each_down(&block)
+      w3c_each(:down, &block)
+    end
+
+    def each_up(&block)
+      w3c_each(:up, &block)
     end
 
+    def each_right(&block)
+      w3c_each(:right, &block)
+    end
+
+    def each_left(&block)
+      w3c_each(:left, &block)
+    end
+
+
     def resolve_strategy
       if @strategy.nil?
         @default_scroll_strategy

data/lib/testa_appium_driver/common/selenium_element.rb

@@ -1,19 +1,19 @@
 module Selenium
   module WebDriver
-    #noinspection RubyClassVariableUsageInspection
     class Element
+      # sets the testa appium driver instance for the current phone
       def self.set_driver(driver, udid)
         udid = "unknown" if udid.nil?
         @@drivers ||= {}
         @@drivers[udid] = driver
       end
 
+      # @return [TestaAppiumDriver::Driver] testa appium driver instance for the current phone
       def get_driver
         udid = @bridge.capabilities.instance_variable_get(:@capabilities)["udid"]
         udid = "unknown" if udid.nil?
         @@drivers[udid]
       end
-
     end
   end
 end

data/lib/testa_appium_driver/driver.rb

@@ -24,12 +24,12 @@ module TestaAppiumDriver
     attr_reader :automation_name
 
     # custom options
-    # - default_strategy: default strategy to be used for finding elements. Available strategies :uiautomator or :xpath
+    # - default_find_strategy: default strategy to be used for finding elements. Available strategies :uiautomator or :xpath
+    # - default_scroll_strategy: default strategy to be used for scrolling. Available strategies: :uiautomator(android only), :w3c
     def initialize(opts = {})
       @testa_opts = opts[:testa_appium_driver] || {}
 
 
-
       core = Appium::Core.for(opts)
       extend_for(core.device, core.automation_name)
       @device = core.device
@@ -38,14 +38,15 @@ module TestaAppiumDriver
       handle_testa_opts
 
       @driver = core.start_driver
-      invalidate_cache!
+      invalidate_cache
 
 
       Selenium::WebDriver::Element.set_driver(self, opts[:caps][:udid])
     end
 
 
-    def invalidate_cache!
+    # invalidates current find_element cache
+    def invalidate_cache
       @cache = {
           strategy: nil,
           selector: nil,
@@ -58,11 +59,13 @@ module TestaAppiumDriver
 
 
 
-    #noinspection RubyScope
+    # Executes the find_element with the resolved locator strategy and selector. Find_element might be skipped if cache is hit.
+    # Cache stores last executed find_element with given selector, strategy and from_element. If given values are the same within
+    # last 5 seconds element is retrieved from cache.
     # @param [TestaAppiumDriver::Locator, TestaAppiumDriver::Driver] from_element element from which start the search
-    # @param [String] selector resolved string of a [TestaAppiumDriver::Locator] selector xpath for xpath strategy, java UiSelectors for uiautomator
+    # @param [String] selector resolved string of a [TestaAppiumDriver::Locator] selector xpath for xpath strategy, java UiSelectors for uiautomator or id for ID strategy
     # @param [Boolean] single fetch single or multiple results
-    # @param [Symbol, nil] strategy [TestaAppiumDriver:FIND_STRATEGY_UIAUTOMATOR] or [FIND_STRATEGY_XPATH]
+    # @param [Symbol, nil] strategy [TestaAppiumDriver::FIND_STRATEGY_UIAUTOMATOR], [TestaAppiumDriver::FIND_STRATEGY_XPATH] or [TestaAppiumDriver::FIND_STRATEGY_ID]
     # @param [Symbol] default_strategy if strategy is not enforced, default can be used
     # @param [Boolean] skip_cache to skip checking and storing cache
     # @return [Selenium::WebDriver::Element, Array] element is returned if single is true, array otherwise
@@ -116,21 +119,26 @@ module TestaAppiumDriver
 
 
     # method missing is used to forward methods to the actual appium driver
+    # after the method is executed, find element cache is invalidated
     def method_missing(method, *args, &block)
       @driver.send(method, *args, &block)
+      invalidate_cache
     end
 
+    # disables implicit wait
     def disable_implicit_wait
       @implicit_wait_ms = @driver.get_timeouts["implicit"]
       @driver.manage.timeouts.implicit_wait = 0
     end
 
+    # enables implicit wait, can be called only after disabling implicit wait
     def enable_implicit_wait
       raise "Implicit wait is not disabled" if @implicit_wait_ms.nil?
       # get_timeouts always returns in milliseconds, but we should set in seconds
       @driver.manage.timeouts.implicit_wait = @implicit_wait_ms / 1000
     end
 
+    # disables wait for idle, only executed for android devices
     def disable_wait_for_idle
       if @device == :android
         @wait_for_idle_timeout = @driver.settings.get["waitForIdleTimeout"]
@@ -138,6 +146,7 @@ module TestaAppiumDriver
       end
     end
 
+    # enables wait for idle, only executed for android devices
     def enable_wait_for_idle
       if @device == :android
         raise "Wait for idle is not disabled" if @wait_for_idle_timeout.nil?
@@ -145,10 +154,13 @@ module TestaAppiumDriver
       end
     end
 
+
+    # @@return [String] current package under test
     def current_package
       @driver.current_package
     end
 
+
     def window_size
       @driver.window_size
     end
@@ -175,6 +187,7 @@ module TestaAppiumDriver
     end
 
 
+    # @return [Array<Selenium::WebDriver::Element] array of 2 elements, the first element without children and the last element without children in the current page
     def first_and_last_leaf(from_element = @driver)
       disable_wait_for_idle
       disable_implicit_wait

data/lib/testa_appium_driver/ios/driver.rb

@@ -7,6 +7,7 @@ module TestaAppiumDriver
     include TypeSelectors
 
 
+    private
     def handle_testa_opts
       if @testa_opts[:default_find_strategy].nil?
         @default_find_strategy = DEFAULT_IOS_FIND_STRATEGY

data/lib/testa_appium_driver/ios/locator.rb

@@ -1,7 +1,6 @@
 require_relative 'locator/attributes'
 
 module TestaAppiumDriver
-  #noinspection RubyTooManyInstanceVariablesInspection
   class Locator
     include TypeSelectors
 
@@ -24,6 +23,7 @@ module TestaAppiumDriver
     end
 
 
+    # @return [Array] returns 2 elements. The first is the resolved find element strategy and the second is the resolved selector
     def strategy_and_selector
       if @can_use_id_strategy
         return FIND_STRATEGY_NAME, @can_use_id_strategy
@@ -32,7 +32,8 @@ module TestaAppiumDriver
     end
 
 
-    # @return [Locator] existing locator element
+
+    # @return [Locator] new child locator element
     def add_child_selector(params)
       params, selectors = extract_selectors_from_params(params)
       single = params[:single]

data/lib/testa_appium_driver/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TestaAppiumDriver
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/testa_appium_driver.gemspec

@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "appium_lib_core", ["= 4.7.0"]
-  spec.add_runtime_dependency "json", [">= 2.3.0"]
+  spec.add_runtime_dependency "json", ["~> 2.3"]
 
   spec.add_development_dependency "rubocop", ["= 1.19.0"]
   spec.add_development_dependency "rake", ["~> 13.0"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: testa_appium_driver
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - karlo.razumovic
@@ -28,16 +28,16 @@ dependencies:
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement