[rb] rework API for scroll methods

Author: titusfortner

rb/lib/selenium/webdriver/common.rb

@@ -54,6 +54,7 @@
 require 'selenium/webdriver/common/interactions/pointer_input'
 require 'selenium/webdriver/common/interactions/scroll'
 require 'selenium/webdriver/common/interactions/wheel_input'
+require 'selenium/webdriver/common/interactions/scroll_origin'
 require 'selenium/webdriver/common/interactions/wheel_actions'
 require 'selenium/webdriver/common/action_builder'
 require 'selenium/webdriver/common/html5/shared_web_storage'

rb/lib/selenium/webdriver/common/interactions/scroll_origin.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Selenium
+  module WebDriver
+    module WheelActions
+      module ScrollOrigin
+        class << self
+          def element(element, x = 0, y = 0)
+            {origin: element, x: x, y: y}
+          end
+
+          def viewport(x, y)
+            {origin: :viewport, x: x, y: y}
+          end
+        end
+      end
+    end # WheelActions
+  end # WebDriver
+end # Selenium

rb/lib/selenium/webdriver/common/interactions/wheel_actions.rb

@@ -20,39 +20,92 @@
 module Selenium
   module WebDriver
     module WheelActions
+      def default_scroll_duration
+        @default_scroll_duration ||= 0.25 # 250 milliseconds
+      end
+
+      #
+      # Scrolls the viewport so that the provided element is at the bottom. Then the viewport
+      # is further scrolled by the provided x and y offsets.
+      #
+      # @example Scroll to element
+      #
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll_to(el).perform
+      #
+      # @example Scroll to offset from element
+      #
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll_to(el, 0, 1000).perform
+      #
+      # @param [Selenium::WebDriver::Element] element to scroll to.
+      # @param [Integer] x Optional horizontal offset to scroll from the center of the element.
+      #   A negative value means scrolling left.
+      # @param [Integer] y Optional vertical offset to scroll from the center of the element.
+      #   A negative value means scrolling up.
+      # @param [Symbol || String] device optional name of the WheelInput device to scroll with.
+      # @return [ActionBuilder] A self reference.
+      #
 
-      # This scrolls an element to the bottom of the viewport
-      def scroll_to(element, device: nil)
-        scroll_from(element, device: device)
+      def scroll_to(element, x = 0, y = 0, device: nil)
+        scroll(x, y, origin: ScrollOrigin.element(element, 0, 0), device: device)
       end
 
-      # This scrolls from the provided element
-      # The origin of the scroll is the center of the element plus the
-      # offset amounts in origin_offset_x and origin_offset_y
-      # The amount of scrolling is the value of right_by and down_by
-      def scroll_from(element, right_by = 0, down_by = 0, origin_offset_x: 0, origin_offset_y: 0, device: nil)
-        wheel = wheel_input(device)
-        wheel.create_scroll(x: Integer(origin_offset_x),
-                            y: Integer(origin_offset_y),
-                            delta_x: Integer(right_by),
-                            delta_y: Integer(down_by),
-                            origin: element,
-                            duration: default_move_duration)
-        tick(wheel)
-        self
+      #
+      # Scrolls the viewport from its current position by the provided offset.
+      # The origin source is the upper left corner of the viewport
+      #
+      # @example Scroll by the provided amount
+      #
+      #    driver.action.scroll_by(0, 1000).perform
+      #
+      # @param [Integer] x horizontal offset. A negative value means scrolling left.
+      # @param [Integer] y vertical offset. A negative value means scrolling up.
+      # @param [Symbol || String] device Optional name of the WheelInput device to scroll with
+      # @return [ActionBuilder] A self reference.
+      #
+
+      def scroll_by(x = 0, y = 0, device: nil)
+        scroll(x, y, origin: ScrollOrigin.viewport(0, 0), device: device)
       end
 
-      # The origin of the scroll will the upper left corner of the viewport plus the
-      # offset amounts in origin_x and origin_y
-      # The amount of scrolling is the value of right_by and down_by
-      def scroll_by(right_by = 0, down_by = 0, origin_x: 0, origin_y: 0, device: nil)
+      #
+      # Scrolls the viewport based on a ScrollOrigin.
+      #
+      # This method is needed instead of #scroll_to or #scroll_by
+      # when what needs to be scrolled is only in a portion of the viewport.
+      # The origin can be thought of as where on the screen you put the mouse when
+      # executing a wheel scroll, or where you put your cursor when swiping a touch pad, etc.
+      #
+      # The offset for the origin is referenced to either the upper left of the viewport or the center of the element
+      # The methods ScrollOrigin.viewport and ScrollOrigin.element are provided to ensure correct syntax
+      #
+      # @example Scroll by the provided amount originating from a source offset from upper left of the viewport
+      #
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll(0, 100, ScrollOrigin.viewport(400, 200)).perform
+      #
+      # @example Scroll by the provided amount originating from a source offset from the center of the provided element
+      #
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll(0, 100, ScrollOrigin.element(element, x: -400, 100)).perform
+      #
+      # @see ScrollOrigin
+      #
+      # @param [Integer] x horizontal offset. A negative value means scrolling left.
+      # @param [Integer] y vertical offset. A negative value means scrolling up.
+      # @param [Hash] origin The location the scroll originates from
+      # @param [Symbol || String] device Optional name of the WheelInput device to scroll with
+      # @return [ActionBuilder] A self reference.
+      # @raise [MoveTargetOutOfBoundsError] if the origin value is outside the viewport.
+      #
+
+      def scroll(x, y, origin: ScrollOrigin.viewport(0, 0), device: nil)
         wheel = wheel_input(device)
-        wheel.create_scroll(x: Integer(origin_x),
-                            y: Integer(origin_y),
-                            delta_x: Integer(right_by),
-                            delta_y: Integer(down_by),
-                            origin: Interactions::Scroll::VIEWPORT,
-                            duration: default_move_duration)
+        opts = {delta_x: Integer(x),
+                delta_y: Integer(y),
+                duration: default_scroll_duration}.merge!(origin)
+        wheel.create_scroll(**opts)
         tick(wheel)
         self
       end
@@ -62,6 +115,6 @@ def scroll_by(right_by = 0, down_by = 0, origin_x: 0, origin_y: 0, device: nil)
       def wheel_input(name = nil)
         device(name: name, type: Interactions::WHEEL) || add_wheel_input('wheel')
       end
-    end # KeyActions
+    end # WheelActions
   end # WebDriver
 end # Selenium

rb/spec/integration/selenium/webdriver/action_builder_spec.rb

@@ -211,6 +211,7 @@ module WebDriver
           y_offset = (destination_rect.y - origin_rect.y).ceil
 
           driver.action.move_to(origin, x_offset, y_offset).click.perform
+          sleep 0.2
           expect(destination.attribute(:value)).to eq('Clicked')
         end
       end
@@ -280,40 +281,17 @@ def in_viewport?(element)
 
           expect(in_viewport?(iframe)).to eq true
         end
-      end
 
-      describe '#scroll_from', only: {browser: %i[chrome edge]} do
-        it 'scrolls from element by the provided amount' do
+        it 'scrolls to provided offset from element' do
           driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
 
           iframe = driver.find_element(tag_name: 'iframe')
-          driver.action.scroll_from(iframe, 0, 200).perform
+          driver.action.scroll_to(iframe, 0, 200).perform
 
           driver.switch_to.frame(iframe)
           checkbox = driver.find_element(name: 'scroll_checkbox')
           expect(in_viewport?(checkbox)).to eq true
         end
-
-        it 'scrolls from element with offset by the provided amount' do
-          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
-
-          footer = driver.find_element(tag_name: 'footer')
-          driver.action.scroll_from(footer, 0, 200, origin_offset_x: 0, origin_offset_y: -50).perform
-
-          driver.switch_to.frame(driver.find_element(tag_name: 'iframe'))
-          checkbox = driver.find_element(name: 'scroll_checkbox')
-          expect(in_viewport?(checkbox)).to eq true
-        end
-
-        it 'throws MoveTargetOutOfBoundsError when origin offset is out of viewport' do
-          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
-
-          footer = driver.find_element(tag_name: 'footer')
-
-          expect {
-            driver.action.scroll_from(footer, 0, 200, origin_offset_x: 0, origin_offset_y: 50).perform
-          }.to raise_error(Error::MoveTargetOutOfBoundsError)
-        end
       end
 
       describe '#scroll_by', only: {browser: %i[chrome edge]} do
@@ -327,24 +305,56 @@ def in_viewport?(element)
 
           expect(in_viewport?(footer)).to eq true
         end
+      end
 
-        it 'scrolls by amount provided from provided origin' do
-          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame.html')
+      describe '#scroll', only: {browser: %i[chrome edge]} do
+        context 'when origin is offset from viewport' do
+          it 'scrolls by amount provided' do
+            driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame.html')
 
-          iframe = driver.find_element(tag_name: 'iframe')
-          driver.action.scroll_by(0, 200, origin_x: 10, origin_y: 10).perform
+            iframe = driver.find_element(tag_name: 'iframe')
+            origin = WheelActions::ScrollOrigin.viewport(10, 10)
+            driver.action.scroll(0, 200, origin: origin).perform
 
-          driver.switch_to.frame(iframe)
-          checkbox = driver.find_element(name: 'scroll_checkbox')
-          expect(in_viewport?(checkbox)).to eq true
+            driver.switch_to.frame(iframe)
+            checkbox = driver.find_element(name: 'scroll_checkbox')
+            expect(in_viewport?(checkbox)).to eq true
+          end
+
+          it 'raises MoveTargetOutOfBoundsError when origin offset is out of viewport' do
+            driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
+
+            origin = WheelActions::ScrollOrigin.viewport(-10, -10)
+
+            expect {
+              driver.action.scroll(0, 200, origin: origin).perform
+            }.to raise_error(Error::MoveTargetOutOfBoundsError)
+          end
         end
 
-        it 'throws MoveTargetOutOfBoundsError when origin offset is out of viewport' do
-          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame.html')
+        context 'when origin is offset from center of element' do
+          it 'scrolls by amount provided' do
+            driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
+
+            footer = driver.find_element(tag_name: 'footer')
+            origin = WheelActions::ScrollOrigin.element(footer, 10, -20)
+            driver.action.scroll(0, 200, origin: origin).perform
+
+            driver.switch_to.frame(driver.find_element(tag_name: 'iframe'))
+            checkbox = driver.find_element(name: 'scroll_checkbox')
+            expect(in_viewport?(checkbox)).to eq true
+          end
 
-          expect {
-            driver.action.scroll_by(0, 200, origin_x: -10, origin_y: -10).perform
-          }.to raise_error(Error::MoveTargetOutOfBoundsError)
+          it 'raises MoveTargetOutOfBoundsError when origin offset is out of viewport' do
+            driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
+
+            footer = driver.find_element(tag_name: 'footer')
+            origin = WheelActions::ScrollOrigin.element(footer, 10, 20)
+
+            expect {
+              driver.action.scroll(0, 200, origin: origin).perform
+            }.to raise_error(Error::MoveTargetOutOfBoundsError)
+          end
         end
       end
     end # ActionBuilder

rb/spec/unit/selenium/webdriver/common/interactions/pointer_input_spec.rb

@@ -85,11 +85,12 @@ module Interactions
 
         describe '#create_pointer_up' do
           it 'executes #add_action with created interaction' do
-            allow(PointerPress).to receive(:new).with(pointer, :up, :left, {}).and_return(interaction)
+            allow(PointerPress).to receive(:new).and_return(interaction)
             allow(pointer).to receive(:add_action).and_call_original
 
             pointer.create_pointer_up(:left)
 
+            expect(PointerPress).to have_received(:new).with(pointer, :up, :left, {})
             expect(pointer).to have_received(:add_action).with(interaction)
           end
         end