[rb] make pause easier to use in action builder sequence

titusfortner · titusfortner · commit 4fbc8cbb87af · 2021-12-11T19:47:19.000-06:00
includes deprecating ordered parameters in #pause and #pauses in favor of keywords
diff --git a/rb/lib/selenium/webdriver/common/action_builder.rb b/rb/lib/selenium/webdriver/common/action_builder.rb
@@ -193,8 +193,11 @@ def wheel_inputs
       # @return [ActionBuilder] A self reference.
       #
 
-      def pause(device, duration = nil)
-        device.create_pause(duration)
+      def pause(deprecated_device = nil, deprecated_duration = nil, device: nil, duration: 0)
+        deprecate_method(deprecated_device, deprecated_duration)
+
+        device ||= deprecated_device || pointer_input
+        device.create_pause(duration || deprecated_duration)
         self
       end
 
@@ -214,7 +217,14 @@ def pause(device, duration = nil)
       # @return [ActionBuilder] A self reference.
       #
 
-      def pauses(device, number, duration = nil)
+      def pauses(deprecated_device = nil, deprecated_number = nil, deprecated_duration = nil,
+                 device: nil, number: nil, duration: 0)
+        deprecate_method(deprecated_device, deprecated_duration, deprecated_number, method: :pauses)
+
+        number ||= deprecated_number || 2
+        device ||= deprecated_device || pointer_input
+        duration ||= deprecated_duration || 0
+
         number.times { device.create_pause(duration) }
         self
       end
@@ -268,11 +278,20 @@ def add_input(device)
 
         unless @async
           max_device = @devices.max { |a, b| a.actions.length <=> b.actions.length }
-          pauses(device, max_device.actions.length) if max_device
+          pauses(device: device, number: max_device.actions.length) if max_device
         end
         @devices << device
         device
       end
+
+      def deprecate_method(device = nil, duration = nil, number = nil, method: :pause)
+        return unless device || number || duration
+
+        WebDriver.logger.deprecate "ActionBuilder##{method} with ordered parameters",
+                                   ':device, :duration, :number keywords',
+                                   id: method
+      end
+
     end # ActionBuilder
   end # WebDriver
 end # Selenium
diff --git a/rb/spec/integration/selenium/webdriver/action_builder_spec.rb b/rb/spec/integration/selenium/webdriver/action_builder_spec.rb
@@ -210,8 +210,7 @@ module WebDriver
           x_offset = (destination_rect.x - origin_rect.x).ceil
           y_offset = (destination_rect.y - origin_rect.y).ceil
 
-          driver.action.move_to(origin, x_offset, y_offset).click.perform
-          sleep 0.2
+          driver.action.move_to(origin, x_offset, y_offset).pause(duration: 1).click.perform
           expect(destination.attribute(:value)).to eq('Clicked')
         end
       end
diff --git a/rb/spec/unit/selenium/webdriver/common/action_builder_spec.rb b/rb/spec/unit/selenium/webdriver/common/action_builder_spec.rb
@@ -188,27 +188,47 @@ module WebDriver
         it 'creates pause with default duration' do
           allow(mouse).to receive :create_pause
 
-          builder.pause(mouse)
+          builder.pause(device: mouse)
 
-          expect(mouse).to have_received(:create_pause).with(nil)
+          expect(mouse).to have_received(:create_pause).with(0)
         end
 
         it 'creates pause with provided duration' do
           allow(mouse).to receive :create_pause
 
-          builder.pause(mouse, 5)
+          builder.pause(device: mouse, duration: 5)
 
           expect(mouse).to have_received(:create_pause).with(5)
         end
+
+        it 'has deprecated ordered parameters' do
+          expect {
+            builder.pause(mouse, 3)
+          }.to have_deprecated(:pause)
+        end
       end
 
       describe '#pauses' do
+        it 'adds 2 pauses to a pointer device by default' do
+          allow(mouse).to receive :create_pause
+
+          builder.pauses
+
+          expect(mouse).to have_received(:create_pause).with(0).exactly(2).times
+        end
+
         it 'adds multiple pause commands' do
           allow(mouse).to receive :create_pause
 
-          builder.pauses(mouse, 3)
+          builder.pauses(device: mouse, number: 3)
 
-          expect(mouse).to have_received(:create_pause).with(nil).exactly(3).times
+          expect(mouse).to have_received(:create_pause).with(0).exactly(3).times
+        end
+
+        it 'has deprecated ordered parameters' do
+          expect {
+            builder.pauses(mouse, 3)
+          }.to have_deprecated(:pauses)
         end
       end
 
