fix: align scroll_until_element_visible offset params

README.md

@@ -388,7 +388,7 @@ Both of these lists (Strategy/Id) must have the same size (number of elements):
 		- //some/path2
 	  NoRaise: false/true (Default - false -> will rise error on fail)
 
-By default, the click action will be executed on the element midpoint (width * 0.5, height * 0.5), but it is possible to add offsets. These can be either absolute (in pixels) or relative (in fractions of the element width/height):
+By default, the click action will be executed on the element midpoint (width * 0.5, height * 0.5), but it is possible to add offsets. These can be either absolute (in pixels) or relative (in fractions of the element width/height). While the values are not bound by the element dimensions, if using relative offsets, the [-0.5..0.5] range will cover the entire element width/height.
 
 	- Type: click
 	  Role: role1 (Optional. if not specified will use the first one defined in the case Roles)
@@ -811,17 +811,22 @@ Set a specific background element to scroll on (the scroll target). If not speci
 	    RecheckAfterScrolls: 2 (Sometimes the scroll target dimensions may change, e.g. in mobile browsers, the URL bar may auto-hide. Setting this value recalculates the scroll target dimensions after the specified number of swipes)
 
 Customize the swipe action:
+- Adjust the position of the swipe action. By default, the action swipes downwards on the scroll target, at its width * 0.5, from its height * 0.7, to its height * 0.3 (meaning, the swipe distance is the scroll target height * 0.4). This can be changed using offsets relative to the scroll target midpoint (in fractions of its width/height). See the [click](#click) action description for the values that these offsets can take.
+- Change the swipe speed by passing a value which will be multiplied by the default speed value
+- Change the pause duration (time in seconds to wait after every swipe). Default 0.2s for iOS, otherwise 0.1s
+
+Example of changing all 5 parameters:
 
 	- Type: scroll_until_element_visible
 	  Role: role1
 	  Strategy: id/css/xpath/uiautomator/class_chain/...
 	  Id: //some/path
 	  SwipeAction:
-	    OffsetFractionX: 0.3 (Fraction of the scroll target width where the swipe action will execute. Default 0.5, i.e. the midpoint of the scroll target width)
-	    StartFractionY: 0.2 (Fraction of the scroll target height where the swipe action will start. Default 0.7)
-	    EndFractionY: 0.8 (Fraction of the scroll target height where the swipe action will end. Default 0.3)
-	    SwipeSpeedMultiplier: 1.2 (Speed multiplier to apply to the default scroll speed)
-	    SwipePauseDuration: 0.5 (Time in seconds to wait after every swipe action. Default 0.2 for iOS, otherwise 0.1)
+	    OffsetFractionX: 0.3 (Translates to 0.5 + 0.3 = 0.8 * width)
+	    OffsetStartFractionY: -0.3 (Translates to 0.5 - 0.3 = 0.2 * height)
+	    OffsetEndFractionY: 0.3 (Translates to 0.5 + 0.3 = 0.8 * height)
+	    SwipeSpeedMultiplier: 1.2
+	    SwipePauseDuration: 0.5
 
 Set the scrolling timeout:
 
@@ -853,7 +858,7 @@ Instruct the target element to be scrolled into full view. This means that once
 
 ### <a id="swipe_on_element"></a>swipe_on_element
 
-Swipe in an arbitrary direction over a single element. By default, the swipe start and endpoints are at the element midpoint (width * 0.5, height * 0.5), which can be changed using offsets. These can be either absolute (in pixels) or relative (in fractions of the element width/height). The swipe duration can also be configured (default is 1 second).
+Swipe in an arbitrary direction over a single element. By default, the swipe start and endpoints are at the element midpoint (width * 0.5, height * 0.5), which can be changed using offsets. These can be either absolute (in pixels) or relative (in fractions of the element width/height). See the [click](#click) action description for the values that these offsets can take. The swipe duration can also be configured (default is 1 second).
 
 	- Type: swipe_on_element
 	  Role: role1 (Optional. if not specified will use the first one defined in the case Roles)

lib/core/device.rb

@@ -730,16 +730,16 @@ def scroll_until_element_visible(action)
     action["NoRaise"] = true
     action["Time"] = 0.5
     # configure swipe action properties
-    x_frac = 0.5
-    y_start_frac = 0.7
-    y_end_frac = 0.3
+    x_frac = 0
+    y_start_frac = 0.2
+    y_end_frac = -0.2
     scroll_mul = @platform == "iOS" ? 3 : 1.5
     scroll_pause = @platform == "iOS" ? 0.2 : 0.1
     if action.key?("SwipeAction")
       sw_action = action["SwipeAction"]
       x_frac = convert_value(sw_action["OffsetFractionX"]).to_f if sw_action.key?("OffsetFractionX")
-      y_start_frac = convert_value(sw_action["StartFractionY"]).to_f if sw_action.key?("StartFractionY")
-      y_end_frac = convert_value(sw_action["EndFractionY"]).to_f if sw_action.key?("EndFractionY")
+      y_start_frac = convert_value(sw_action["OffsetStartFractionY"]).to_f if sw_action.key?("OffsetStartFractionY")
+      y_end_frac = convert_value(sw_action["OffsetEndFractionY"]).to_f if sw_action.key?("OffsetEndFractionY")
       scroll_mul /= convert_value(sw_action["SwipeSpeedMultiplier"]).to_f if sw_action.key?("SwipeSpeedMultiplier")
       scroll_pause = convert_value(sw_action["SwipePauseDuration"]).to_f if sw_action.key?("SwipePauseDuration")
     end
@@ -754,16 +754,16 @@ def scroll_until_element_visible(action)
       bg_el = wait_for(action["ScrollTarget"])
       y_top = bg_el.location.y
       y_bottom = bg_el.location.y + bg_el.size.height
-      x_point = bg_el.location.x + (bg_el.size.width * x_frac)
-      y_start = y_top + (bg_el.size.height * y_start_frac)
-      y_end = y_top + (bg_el.size.height * y_end_frac)
+      x_point = bg_el.location.x + (bg_el.size.width * (0.5 + x_frac))
+      y_start = y_top + (bg_el.size.height * (0.5 + y_start_frac))
+      y_end = y_top + (bg_el.size.height * (0.5 + y_end_frac))
     else
       screen_size = @driver.window_size
       y_top = 0
       y_bottom = screen_size.height
-      x_point = screen_size.width * x_frac
-      y_start = screen_size.height * y_start_frac
-      y_end = screen_size.height * y_end_frac
+      x_point = screen_size.width * (0.5 + x_frac)
+      y_start = screen_size.height * (0.5 + y_start_frac)
+      y_end = screen_size.height * (0.5 + y_end_frac)
     end
     # configure FullView parameters
     # if FullViewOffsetY is provided, assume that FullView is requested