selenium-webdriver 3.142.7 → 4.0.0

data/lib/selenium/webdriver/common/action_builder.rb

@@ -19,346 +19,194 @@
 
 module Selenium
   module WebDriver
-    #
-    # The ActionBuilder provides the user a way to set up and perform
-    # complex user interactions.
-    #
-    # This class should not be instantiated directly, but is created by Driver#action
-    #
-    # @example
-    #
-    #  driver.action.key_down(:shift).
-    #                click(element).
-    #                click(second_element).
-    #                key_up(:shift).
-    #                drag_and_drop(element, third_element).
-    #                perform
-    #
-
     class ActionBuilder
-      #
-      # @api private
-      #
+      include KeyActions # Actions specific to key inputs
+      include PointerActions # Actions specific to pointer inputs
 
-      def initialize(mouse, keyboard)
-        @devices = {
-          mouse: mouse,
-          keyboard: keyboard
-        }
-
-        @actions = []
-      end
+      attr_reader :devices
 
       #
-      # Performs a modifier key press. Does not release
-      # the modifier key - subsequent interactions may assume it's kept pressed.
-      # Note that the modifier key is never released implicitly - either
-      # #key_up(key) or #send_keys(:null) must be called to release the modifier.
+      # Initialize a W3C Action Builder. Differs from previous by requiring a bridge and allowing asynchronous actions.
+      # The W3C implementation allows asynchronous actions per device. e.g. A key can be pressed at the same time that
+      # the mouse is moving. Keep in mind that pauses must be added for other devices in order to line up the actions
+      # correctly when using asynchronous.
       #
-      # Equivalent to:
-      #   driver.action.click(element).send_keys(key)
-      #   # or
-      #   driver.action.click.send_keys(key)
-      #
-      # @example Press a key
-      #
-      #    driver.action.key_down(:control).perform
-      #
-      # @example Press a key on an element
-      #
-      #    el = driver.find_element(id: "some_id")
-      #    driver.action.key_down(el, :shift).perform
+      # @param [Selenium::WebDriver::Remote::Bridge] bridge the bridge for the current driver instance
+      # @param [Selenium::WebDriver::Interactions::PointerInput] mouse PointerInput for the mouse.
+      # @param [Selenium::WebDriver::Interactions::KeyInput] keyboard KeyInput for the keyboard.
+      # @param [Boolean] async Whether to perform the actions asynchronously per device. Defaults to false for
+      #   backwards compatibility.
+      # @return [ActionBuilder] A self reference.
       #
-      # @overload key_down(key)
-      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to press
-      # @overload key_down(element, key)
-      #   @param [Element] element An optional element to move to first
-      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to press
-      # @raise [ArgumentError] if the given key is not a modifier
-      # @return [ActionBuilder] A self reference
 
-      def key_down(*args)
-        @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element
-
-        @actions << [:keyboard, :press, args]
-        self
+      def initialize(bridge, mouse, keyboard, async = false)
+        # For backwards compatibility, automatically include mouse & keyboard
+        @bridge = bridge
+        @devices = [mouse, keyboard]
+        @async = async
       end
 
       #
-      # Performs a modifier key release.
-      # Releasing a non-depressed modifier key will yield undefined behaviour.
+      # Adds a PointerInput device of the given kind
       #
-      # @example Release a key
+      # @example Add a touch pointer input device
       #
-      #   driver.action.key_up(:shift).perform
+      #    builder = device.action
+      #    builder.add_pointer_input('touch', :touch)
       #
-      # @example Release a key from an element
+      # @param [String] name name for the device
+      # @param [Symbol] kind kind of pointer device to create
+      # @return [Interactions::PointerInput] The pointer input added
       #
-      #   el = driver.find_element(id: "some_id")
-      #   driver.action.key_up(el, :alt).perform
       #
-      # @overload key_up(key)
-      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to release
-      # @overload key_up(element, key)
-      #   @param [Element] element An optional element to move to first
-      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to release
-      # @raise [ArgumentError] if the given key is not a modifier
-      # @return [ActionBuilder] A self reference
-      #
-
-      def key_up(*args)
-        @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element
 
-        @actions << [:keyboard, :release, args]
-        self
+      def add_pointer_input(kind, name)
+        new_input = Interactions.pointer(kind, name: name)
+        add_input(new_input)
+        new_input
       end
 
       #
-      # Sends keys to the active element. This differs from calling
-      # Element#send_keys(keys) on the active element in two ways:
-      #
-      # * The modifier keys included in this call are not released.
-      # * There is no attempt to re-focus the element - so send_keys(:tab) for switching elements should work.
-      #
-      # @example Send the text "help" to an element
-      #
-      #   el = driver.find_element(id: "some_id")
-      #   driver.action.send_keys(el, "help").perform
+      # Adds a KeyInput device
       #
-      # @example Send the text "help" to the currently focused element
+      # @example Add a key input device
       #
-      #   driver.action.send_keys("help").perform
+      #    builder = device.action
+      #    builder.add_key_input('keyboard2')
       #
-      # @overload send_keys(keys)
-      #   @param [Array, Symbol, String] keys The key(s) to press and release
-      # @overload send_keys(element, keys)
-      #   @param [Element] element An optional element to move to first
-      #   @param [Array, Symbol, String] keys The key(s) to press and release
-      # @return [ActionBuilder] A self reference
+      # @param [String] name name for the device
+      # @return [Interactions::KeyInput] The key input added
       #
 
-      def send_keys(*args)
-        @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element
-
-        @actions << [:keyboard, :send_keys, args]
-        self
+      def add_key_input(name)
+        new_input = Interactions.key(name)
+        add_input(new_input)
+        new_input
       end
 
       #
-      # Clicks (without releasing) in the middle of the given element. This is
-      # equivalent to:
-      #
-      #   driver.action.move_to(element).click_and_hold
-      #
-      # @example Clicking and holding on some element
+      # Retrieves the input device for the given name
       #
-      #    el = driver.find_element(id: "some_id")
-      #    driver.action.click_and_hold(el).perform
-      #
-      # @param [Element] element the element to move to and click.
-      # @return [ActionBuilder] A self reference.
+      # @param [String] name name of the input device
+      # @return [Selenium::WebDriver::Interactions::InputDevice] input device with given name
       #
 
-      def click_and_hold(element = nil)
-        @actions << [:mouse, :down, [element]]
-        self
+      def get_device(name)
+        @devices.find { |device| device.name == name.to_s }
       end
 
       #
-      # Releases the depressed left mouse button at the current mouse location.
+      # Retrieves the current PointerInput devices
       #
-      # @example Releasing an element after clicking and holding it
-      #
-      #    el = driver.find_element(id: "some_id")
-      #    driver.action.click_and_hold(el).release.perform
-      #
-      # @return [ActionBuilder] A self reference.
+      # @return [Array] array of current PointerInput devices
       #
 
-      def release(element = nil)
-        @actions << [:mouse, :up, [element]]
-        self
+      def pointer_inputs
+        @devices.select { |device| device.type == Interactions::POINTER }
       end
 
       #
-      # Clicks in the middle of the given element. Equivalent to:
-      #
-      #   driver.action.move_to(element).click
-      #
-      # When no element is passed, the current mouse position will be clicked.
-      #
-      # @example Clicking on an element
+      # Retrieves the current KeyInput device
       #
-      #    el = driver.find_element(id: "some_id")
-      #    driver.action.click(el).perform
-      #
-      # @example Clicking at the current mouse position
-      #
-      #    driver.action.click.perform
-      #
-      # @param [Selenium::WebDriver::Element] element An optional element to click.
-      # @return [ActionBuilder] A self reference.
+      # @return [Selenium::WebDriver::Interactions::InputDevice] current KeyInput device
       #
 
-      def click(element = nil)
-        @actions << [:mouse, :click, [element]]
-        self
+      def key_inputs
+        @devices.select { |device| device.type == Interactions::KEY }
       end
 
       #
-      # Performs a double-click at middle of the given element. Equivalent to:
-      #
-      #   driver.action.move_to(element).double_click
+      # Creates a pause for the given device of the given duration. If no duration is given, the pause will only wait
+      # for all actions to complete in that tick.
       #
-      # @example Double click an element
+      # @example Send keys to an element
       #
-      #    el = driver.find_element(id: "some_id")
-      #    driver.action.double_click(el).perform
+      #   action_builder = driver.action
+      #   keyboard = action_builder.key_input
+      #   el = driver.find_element(id: "some_id")
+      #   driver.action.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys('keys').perform
       #
-      # @param [Selenium::WebDriver::Element] element An optional element to move to.
+      # @param [InputDevice] device Input device to pause
+      # @param [Float] duration Duration to pause
       # @return [ActionBuilder] A self reference.
       #
 
-      def double_click(element = nil)
-        @actions << [:mouse, :double_click, [element]]
+      def pause(device, duration = nil)
+        device.create_pause(duration)
         self
       end
 
       #
-      # Moves the mouse to the middle of the given element. The element is scrolled into
-      # view and its location is calculated using getBoundingClientRect.  Then the
-      # mouse is moved to optional offset coordinates from the element.
-      #
-      # Note that when using offsets, both coordinates need to be passed.
-      #
-      # @example Scroll element into view and move the mouse to it
+      # Creates multiple pauses for the given device of the given duration.
       #
-      #   el = driver.find_element(id: "some_id")
-      #   driver.action.move_to(el).perform
-      #
-      # @example
+      # @example Send keys to an element
       #
+      #   action_builder = driver.action
+      #   keyboard = action_builder.key_input
       #   el = driver.find_element(id: "some_id")
-      #   driver.action.move_to(el, 100, 100).perform
+      #   driver.action.click(el).pauses(keyboard, 3).send_keys('keys').perform
       #
-      # @param [Selenium::WebDriver::Element] element to move to.
-      # @param [Integer] right_by Optional offset from the top-left corner. A negative value means
-      #   coordinates right from the element.
-      # @param [Integer] down_by Optional offset from the top-left corner. A negative value means
-      #   coordinates above the element.
+      # @param [InputDevice] device Input device to pause
+      # @param [Integer] number of pauses to add for the device
+      # @param [Float] duration Duration to pause
       # @return [ActionBuilder] A self reference.
       #
 
-      def move_to(element, right_by = nil, down_by = nil)
-        @actions << if right_by && down_by
-                      [:mouse, :move_to, [element, Integer(right_by), Integer(down_by)]]
-                    else
-                      [:mouse, :move_to, [element]]
-                    end
-
+      def pauses(device, number, duration = nil)
+        number.times { device.create_pause(duration) }
         self
       end
 
       #
-      # Moves the mouse from its current position (or 0,0) by the given offset.
-      # If the coordinates provided are outside the viewport (the mouse will
-      # end up outside the browser window) then the viewport is scrolled to
-      # match.
-      #
-      # @example Move the mouse to a certain offset from its current position
-      #
-      #    driver.action.move_by(100, 100).perform
-      #
-      # @param [Integer] right_by horizontal offset. A negative value means moving the
-      #   mouse left.
-      # @param [Integer] down_by vertical offset. A negative value means moving the mouse
-      #   up.
-      # @return [ActionBuilder] A self reference.
-      # @raise [MoveTargetOutOfBoundsError] if the provided offset is outside
-      #   the document's boundaries.
+      # Executes the actions added to the builder.
       #
 
-      def move_by(right_by, down_by)
-        @actions << [:mouse, :move_by, [Integer(right_by), Integer(down_by)]]
-        self
+      def perform
+        @bridge.send_actions @devices.map(&:encode).compact
+        clear_all_actions
+        nil
       end
 
       #
-      # Performs a context-click at middle of the given element. First performs
-      # a move_to to the location of the element.
-      #
-      # @example Context-click at middle of given element
-      #
-      #   el = driver.find_element(id: "some_id")
-      #   driver.action.context_click(el).perform
-      #
-      # @param [Selenium::WebDriver::Element] element An element to context click.
-      # @return [ActionBuilder] A self reference.
+      # Clears all actions from the builder.
       #
 
-      def context_click(element = nil)
-        @actions << [:mouse, :context_click, [element]]
-        self
+      def clear_all_actions
+        @devices.each(&:clear_actions)
       end
 
       #
-      # A convenience method that performs click-and-hold at the location of the
-      # source element, moves to the location of the target element, then
-      # releases the mouse.
-      #
-      # @example Drag and drop one element onto another
-      #
-      #   el1 = driver.find_element(id: "some_id1")
-      #   el2 = driver.find_element(id: "some_id2")
-      #   driver.action.drag_and_drop(el1, el2).perform
-      #
-      # @param [Selenium::WebDriver::Element] source element to emulate button down at.
-      # @param [Selenium::WebDriver::Element] target element to move to and release the
-      #   mouse at.
-      # @return [ActionBuilder] A self reference.
+      # Releases all action states from the browser.
       #
 
-      def drag_and_drop(source, target)
-        click_and_hold source
-        move_to        target
-        release
-
-        self
+      def release_actions
+        @bridge.release_actions
       end
 
+      private
+
       #
-      # A convenience method that performs click-and-hold at the location of
-      # the source element, moves by a given offset, then releases the mouse.
-      #
-      # @example Drag and drop an element by offset
+      # Adds pauses for all devices but the given devices
       #
-      #   el = driver.find_element(id: "some_id1")
-      #   driver.action.drag_and_drop_by(el, 100, 100).perform
-      #
-      # @param [Selenium::WebDriver::Element] source Element to emulate button down at.
-      # @param [Integer] right_by horizontal move offset.
-      # @param [Integer] down_by vertical move offset.
-      # @return [ActionBuilder] A self reference.
+      # @param [Array[InputDevice]] action_devices Array of Input Devices performing an action in this tick.
       #
 
-      def drag_and_drop_by(source, right_by, down_by)
-        click_and_hold source
-        move_by        right_by, down_by
-        release
+      def tick(*action_devices)
+        return if @async
 
-        self
+        @devices.each { |device| device.create_pause unless action_devices.include? device }
       end
 
       #
-      # Executes the actions added to the builder.
+      # Adds an InputDevice
       #
 
-      def perform
-        @actions.each do |receiver, method, args|
-          @devices.fetch(receiver).__send__(method, *args)
+      def add_input(device)
+        unless @async
+          max_device = @devices.max { |a, b| a.actions.length <=> b.actions.length }
+          pauses(device, max_device.actions.length)
         end
-
-        nil
+        @devices << device
       end
     end # ActionBuilder
   end # WebDriver

data/lib/selenium/webdriver/common/driver.rb

@@ -30,6 +30,7 @@ module Selenium
 
     class Driver
       include SearchContext
+      include TakesScreenshot
 
       class << self
         #
@@ -43,19 +44,17 @@ module Selenium
         def for(browser, opts = {})
           case browser
           when :chrome
-            Chrome::Driver.new(opts)
+            Chrome::Driver.new(**opts)
           when :internet_explorer, :ie
-            IE::Driver.new(opts)
+            IE::Driver.new(**opts)
           when :safari
-            Safari::Driver.new(opts)
-          when :phantomjs
-            PhantomJS::Driver.new(opts)
+            Safari::Driver.new(**opts)
           when :firefox, :ff
-            Firefox::Driver.new(opts)
+            Firefox::Driver.new(**opts)
           when :edge
-            Edge::Driver.new(opts)
+            Edge::Driver.new(**opts)
           when :remote
-            Remote::Driver.new(opts)
+            Remote::Driver.new(**opts)
           else
             raise ArgumentError, "unknown driver: #{browser.inspect}"
           end
@@ -69,13 +68,27 @@ module Selenium
       # @api private
       #
 
-      def initialize(bridge, listener: nil)
-        @bridge = bridge
-        @bridge = Support::EventFiringBridge.new(bridge, listener) if listener
+      def initialize(bridge: nil, listener: nil, **opts)
+        @service = nil
+        @devtools = nil
+        bridge ||= create_bridge(**opts)
+        add_extensions(bridge.browser)
+        @bridge = listener ? Support::EventFiringBridge.new(bridge, listener) : bridge
       end
 
       def inspect
-        format '#<%<class>s:0x%<hash>x browser=%<browser>s>', class: self.class, hash: hash * 2, browser: bridge.browser.inspect
+        format '#<%<class>s:0x%<hash>x browser=%<browser>s>', class: self.class, hash: hash * 2,
+                                                              browser: bridge.browser.inspect
+      end
+
+      #
+      # information about whether a remote end is in a state in which it can create new sessions,
+      # and may include additional meta information.
+      #
+      # @return [Hash]
+      #
+      def status
+        @bridge.status
       end
 
       #
@@ -106,8 +119,8 @@ module Selenium
       end
 
       #
-      # @return [ActionBuilder, W3CActionBuilder]
-      # @see ActionBuilder, W3CActionBuilder
+      # @return [ActionBuilder]
+      # @see ActionBuilder
       #
 
       def action
@@ -166,6 +179,9 @@ module Selenium
 
       def quit
         bridge.quit
+      ensure
+        @service&.stop
+        @devtools&.close
       end
 
       #
@@ -271,7 +287,7 @@ module Selenium
       end
 
       def browser
-        bridge.browser
+        bridge&.browser
       end
 
       def capabilities
@@ -283,26 +299,99 @@ module Selenium
       # @see SearchContext
       #
 
-      def ref; end
+      def ref
+        [:driver, nil]
+      end
 
       private
 
       attr_reader :bridge
 
+      def create_bridge(**opts)
+        opts[:url] ||= service_url(opts)
+        caps = opts.delete(:capabilities)
+        # NOTE: This is deprecated
+        cap_array = caps.is_a?(Hash) ? [caps] : Array(caps)
+
+        desired_capabilities = opts.delete(:desired_capabilities)
+        if desired_capabilities
+          WebDriver.logger.deprecate(':desired_capabilities as a parameter for driver initialization',
+                                     ':capabilities with an Array value of capabilities/options if necessary',
+                                     id: :desired_capabilities)
+          desired_capabilities = Remote::Capabilities.new(desired_capabilities) if desired_capabilities.is_a?(Hash)
+          cap_array << desired_capabilities
+        end
+
+        options = opts.delete(:options)
+        if options
+          WebDriver.logger.deprecate(':options as a parameter for driver initialization',
+                                     ':capabilities with an Array of value capabilities/options if necessary',
+                                     id: :browser_options)
+          cap_array << options
+        end
+
+        capabilities = generate_capabilities(cap_array)
+
+        bridge_opts = {http_client: opts.delete(:http_client), url: opts.delete(:url)}
+        raise ArgumentError, "Unable to create a driver with parameters: #{opts}" unless opts.empty?
+
+        bridge = Remote::Bridge.new(**bridge_opts)
+
+        bridge.create_session(capabilities)
+        bridge
+      end
+
+      def generate_capabilities(cap_array)
+        cap_array.map { |cap|
+          if cap.is_a? Symbol
+            cap = Remote::Capabilities.send(cap)
+          elsif cap.is_a? Hash
+            new_message = 'Capabilities instance initialized with the Hash, or build values with Options class'
+            WebDriver.logger.deprecate("passing a Hash value to :capabilities",
+                                       new_message,
+                                       id: :capabilities_hash)
+            cap = Remote::Capabilities.new(cap)
+          elsif !cap.respond_to? :as_json
+            msg = ":capabilities parameter only accepts objects responding to #as_json which #{cap.class} does not"
+            raise ArgumentError, msg
+          end
+          cap&.as_json
+        }.inject(:merge) || Remote::Capabilities.send(browser || :new)
+      end
+
       def service_url(opts)
-        @service = opts.delete(:service)
+        service_config = opts.delete(:service)
         %i[driver_opts driver_path port].each do |key|
           next unless opts.key? key
 
-          WebDriver.logger.deprecate(":#{key}", ':service with an instance of Selenium::WebDriver::Service')
+          WebDriver.logger.deprecate(":#{key}", ':service with an instance of Selenium::WebDriver::Service',
+                                     id: "service_#{key}".to_sym)
         end
-        @service ||= Service.send(browser,
-                                  args: opts.delete(:driver_opts),
-                                  path: opts.delete(:driver_path),
-                                  port: opts.delete(:port))
-        @service.start
+        service_config ||= Service.send(browser,
+                                        args: opts.delete(:driver_opts),
+                                        path: opts.delete(:driver_path),
+                                        port: opts.delete(:port))
+        @service = service_config.launch
         @service.uri
       end
+
+      def screenshot
+        bridge.screenshot
+      end
+
+      def add_extensions(browser)
+        extensions = case browser
+                     when :chrome, :msedge
+                       Chrome::Driver::EXTENSIONS
+                     when :firefox
+                       Firefox::Driver::EXTENSIONS
+                     when :safari, :safari_technology_preview
+                       Safari::Driver::EXTENSIONS
+                     else
+                       []
+                     end
+        extensions.each { |extension| extend extension }
+      end
     end # Driver
   end # WebDriver
 end # Selenium