selenium-webdriver 4.1.0 → 4.14.0

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

@@ -20,7 +20,6 @@
 module Selenium
   module WebDriver
     module Error
-
       #
       # Returns exception from its string representation.
       # @param [String, nil] error
@@ -29,19 +28,26 @@ module Selenium
       def self.for_error(error)
         return if error.nil?
 
-        klass_name = error.split(' ').map(&:capitalize).join.sub(/Error$/, '')
+        klass_name = error.split.map(&:capitalize).join.sub(/Error$/, '')
         const_get("#{klass_name}Error", false)
       rescue NameError
         WebDriverError
       end
 
+      SUPPORT_MSG = 'For documentation on this error, please visit:'
+      ERROR_URL = 'https://www.selenium.dev/documentation/webdriver/troubleshooting/errors'
+
       class WebDriverError < StandardError; end
 
       #
       # An element could not be located on the page using the given search parameters.
       #
 
-      class NoSuchElementError < WebDriverError; end
+      class NoSuchElementError < WebDriverError
+        def initialize(msg = '')
+          super("#{msg}; #{SUPPORT_MSG} #{ERROR_URL}#no-such-element-exception")
+        end
+      end
 
       #
       # A command to switch to a frame could not be satisfied because the frame could not be found.
@@ -59,7 +65,11 @@ module Selenium
       # A command failed because the referenced element is no longer attached to the DOM.
       #
 
-      class StaleElementReferenceError < WebDriverError; end
+      class StaleElementReferenceError < WebDriverError
+        def initialize(msg = '')
+          super("#{msg}; #{SUPPORT_MSG} #{ERROR_URL}#stale-element-reference-exception")
+        end
+      end
 
       #
       # A command failed because the referenced shadow root is no longer attached to the DOM.
@@ -133,7 +143,11 @@ module Selenium
       # Argument was an invalid selector.
       #
 
-      class InvalidSelectorError < WebDriverError; end
+      class InvalidSelectorError < WebDriverError
+        def initialize(msg = '')
+          super("#{msg}; #{SUPPORT_MSG} #{ERROR_URL}#invalid-selector-exception")
+        end
+      end
 
       #
       # A new session could not be created.
@@ -214,6 +228,15 @@ module Selenium
 
       class UnsupportedOperationError < WebDriverError; end
 
+      #
+      # Indicates that driver was not specified and could not be located.
+      #
+
+      class NoSuchDriverError < WebDriverError
+        def initialize(msg = '')
+          super("#{msg}; #{SUPPORT_MSG} #{ERROR_URL}/driver_location")
+        end
+      end
     end # Error
   end # WebDriver
 end # Selenium

data/lib/selenium/webdriver/common/html5/shared_web_storage.rb

@@ -26,8 +26,8 @@ module Selenium
         def key?(key)
           keys.include? key
         end
-        alias_method :member?, :key?
-        alias_method :has_key?, :key?
+        alias member? key?
+        alias has_key? key?
 
         def fetch(key)
           return self[key] if key? key

data/lib/selenium/webdriver/common/interactions/input_device.rb

@@ -22,8 +22,15 @@ require 'securerandom'
 module Selenium
   module WebDriver
     module Interactions
+      #
+      # Superclass for the input device sources
+      # Manages Array of Interaction instances for the device
+      #
+      # @api private
+      #
+
       class InputDevice
-        attr_reader :name, :actions
+        attr_reader :name, :actions, :type
 
         def initialize(name = nil)
           @name = name || SecureRandom.uuid
@@ -44,9 +51,8 @@ module Selenium
           add_action(Pause.new(self, duration))
         end
 
-        def no_actions? # Determine if only pauses are present
-          actions = @actions.reject { |action| action.type == Interaction::PAUSE }
-          actions.empty?
+        def encode
+          {type: type, id: name, actions: @actions.map(&:encode)} unless @actions.empty?
         end
       end # InputDevice
     end # Interactions

data/lib/selenium/webdriver/common/interactions/interaction.rb

@@ -20,37 +20,24 @@
 module Selenium
   module WebDriver
     module Interactions
-      class Interaction
-        PAUSE = :pause
+      #
+      # Superclass for classes defining actions
+      # Do not initialize directly, only use subclass
+      #
+      # @api private
+      #
 
-        attr_reader :source
+      class Interaction
+        attr_reader :type
 
         def initialize(source)
-          unless Interactions::SOURCE_TYPES.include? source.type
-            raise TypeError,
-                  "#{source.type} is not a valid input type"
-          end
-
-          @source = source
+          assert_source(source)
         end
-      end
 
-      class Pause < Interaction
-        def initialize(source, duration = nil)
-          super(source)
-          @duration = duration
+        def assert_source(_source)
+          raise NotImplementedError, 'subclass responsibility'
         end
-
-        def type
-          PAUSE
-        end
-
-        def encode
-          output = {type: type}
-          output[:duration] = (@duration * 1000).to_i if @duration
-          output
-        end
-      end # Interaction
+      end
     end # Interactions
   end # WebDriver
 end # Selenium

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

@@ -23,20 +23,40 @@ module Selenium
       KEY = :key
       POINTER = :pointer
       NONE = :none
-      SOURCE_TYPES = [KEY, POINTER, NONE].freeze
+      WHEEL = :wheel
+
+      #
+      # Class methods for initializing known Input devices
+      #
 
       class << self
-        def key(name)
+        def key(name = nil)
           KeyInput.new(name)
         end
 
-        def pointer(kind, **kwargs)
-          PointerInput.new(kind, **kwargs)
+        def pointer(kind = :mouse, name: nil)
+          PointerInput.new(kind, name: name)
+        end
+
+        def mouse(name: nil)
+          pointer(name: name)
+        end
+
+        def pen(name: nil)
+          pointer(:pen, name: name)
+        end
+
+        def touch(name: nil)
+          pointer(:touch, name: name)
         end
 
         def none(name = nil)
           NoneInput.new(name)
         end
+
+        def wheel(name = nil)
+          WheelInput.new(name)
+        end
       end
     end # Interactions
   end # WebDriver

data/lib/selenium/webdriver/common/interactions/key_actions.rb

@@ -134,12 +134,16 @@ module Selenium
       #
 
       def key_action(*args, action: nil, device: nil)
-        key_input = get_device(device) || key_inputs.first
+        key_input = key_input(device)
         click(args.shift) if args.first.is_a? Element
         key_input.send(action, args.last)
         tick(key_input)
         self
       end
+
+      def key_input(name = nil)
+        device(name: name, type: Interactions::KEY) || add_key_input('keyboard')
+      end
     end # KeyActions
   end # WebDriver
 end # Selenium

data/lib/selenium/webdriver/common/interactions/key_input.rb

@@ -20,17 +20,18 @@
 module Selenium
   module WebDriver
     module Interactions
+      #
+      # Creates actions specific to Key Input devices
+      #
+      # @api private
+      #
+
       class KeyInput < InputDevice
         SUBTYPES = {down: :keyDown, up: :keyUp, pause: :pause}.freeze
 
-        def type
-          Interactions::KEY
-        end
-
-        def encode
-          return nil if no_actions?
-
-          {type: type, id: name, actions: @actions.map(&:encode)}
+        def initialize(name = nil)
+          super
+          @type = Interactions::KEY
         end
 
         def create_key_down(key)
@@ -41,25 +42,8 @@ module Selenium
           add_action(TypingInteraction.new(self, :up, key))
         end
 
-        class TypingInteraction < Interaction
-          attr_reader :type
-
-          def initialize(source, type, key)
-            super(source)
-            @type = assert_type(type)
-            @key = Keys.encode_key(key)
-          end
-
-          def assert_type(type)
-            raise TypeError, "#{type.inspect} is not a valid key subtype" unless KeyInput::SUBTYPES.key? type
-
-            KeyInput::SUBTYPES[type]
-          end
-
-          def encode
-            {type: @type, value: @key}
-          end
-        end # TypingInteraction
+        # Backward compatibility in case anyone called this directly
+        class TypingInteraction < Interactions::TypingInteraction; end
       end # KeyInput
     end # Interactions
   end # WebDriver

data/lib/selenium/webdriver/common/interactions/none_input.rb

@@ -20,15 +20,17 @@
 module Selenium
   module WebDriver
     module Interactions
-      class NoneInput < InputDevice
-        def type
-          Interactions::NONE
-        end
+      #
+      # Creates actions specific to null input source
+      # This is primarily used for adding pauses
+      #
+      # @api private
+      #
 
-        def encode
-          return nil if no_actions?
-
-          {type: type, id: name, actions: @actions.map(&:encode)}
+      class NoneInput < InputDevice
+        def initialize(name = nil)
+          super
+          @type = Interactions::NONE
         end
       end # NoneInput
     end # Interactions

data/lib/selenium/webdriver/common/interactions/pause.rb

@@ -0,0 +1,49 @@
+# 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 Interactions
+      #
+      # Action to create a waiting period between actions
+      # Also used for synchronizing actions across devices
+      #
+      # @api private
+      #
+
+      class Pause < Interaction
+        def initialize(source, duration = nil)
+          super(source)
+          @duration = duration
+          @type = :pause
+        end
+
+        def assert_source(source)
+          raise TypeError, "#{source.type} is not a valid input type" unless source.is_a? InputDevice
+        end
+
+        def encode
+          output = {type: type}
+          output[:duration] = (@duration * 1000).to_i if @duration
+          output
+        end
+      end # Pause
+    end # Interactions
+  end # WebDriver
+end # Selenium

data/lib/selenium/webdriver/common/interactions/pointer_actions.rb

@@ -23,11 +23,12 @@ module Selenium
       attr_writer :default_move_duration
 
       #
-      # The overridable duration for movement used by methods in this module
+      # By default this is set to 250ms in the ActionBuilder constructor
+      # It can be overridden with default_move_duration=
       #
 
       def default_move_duration
-        @default_move_duration ||= 0.25 # 250 milliseconds
+        @default_move_duration ||= @duration / 1000.0 # convert ms to seconds
       end
 
       #
@@ -45,8 +46,8 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pointer_down(button, device: nil)
-        button_action(button, action: :create_pointer_down, device: device)
+      def pointer_down(button = :left, device: nil, **opts)
+        button_action(button, :create_pointer_down, device: device, **opts)
       end
 
       #
@@ -62,21 +63,20 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pointer_up(button, device: nil)
-        button_action(button, action: :create_pointer_up, device: device)
+      def pointer_up(button = :left, device: nil, **opts)
+        button_action(button, :create_pointer_up, device: device, **opts)
       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.
+      # Moves the pointer to the in-view center point of the given element.
+      # Then the pointer is moved to optional offset coordinates.
       #
-      # This is adapted to be backward compatible from non- actions.  calculates offset from the center point
-      # of the element
+      # The element is not scrolled into view.
+      # MoveTargetOutOfBoundsError will be raised if element with offset is outside the viewport
       #
-      # Note that when using offsets, both coordinates need to be passed.
+      # When using offsets, both coordinates need to be passed.
       #
-      # @example Scroll element into view and move the mouse to it
+      # @example Move the pointer to element
       #
       #   el = driver.find_element(id: "some_id")
       #   driver.action.move_to(el).perform
@@ -87,69 +87,60 @@ module Selenium
       #   driver.action.move_to(el, 100, 100).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 to the left of the element.
-      # @param [Integer] down_by Optional offset from the top-left corner. A negative value means
-      #   coordinates above the element.
+      # @param [Integer] right_by Optional offset from the in-view center of the
+      #   element. A negative value means coordinates to the left of the center.
+      # @param [Integer] down_by Optional offset from the in-view center of the
+      #   element. A negative value means coordinates to the top of the center.
       # @param [Symbol || String] device optional name of the PointerInput device to move.
       # @return [ActionBuilder] A self reference.
       #
 
-      def move_to(element, right_by = nil, down_by = nil, device: nil)
-        pointer = get_pointer(device)
-        # New actions offset is from center of element
-        if right_by || down_by
-          size = element.size
-          left_offset = (size[:width] / 2).to_i
-          top_offset = (size[:height] / 2).to_i
-          left = -left_offset + (right_by || 0)
-          top = -top_offset + (down_by || 0)
-        else
-          left = 0
-          top = 0
-        end
-        pointer.create_pointer_move(duration: default_move_duration,
-                                    x: left,
-                                    y: top,
-                                    element: element)
+      def move_to(element, right_by = nil, down_by = nil, **opts)
+        pointer = pointer_input(opts.delete(:device))
+        pointer.create_pointer_move(duration: opts.delete(:duration) || default_move_duration,
+                                    x: right_by || 0,
+                                    y: down_by || 0,
+                                    origin: element,
+                                    **opts)
         tick(pointer)
         self
       end
 
       #
-      # Moves the mouse from its current position 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.
+      # Moves the pointer from its current position by the given offset.
       #
-      # @example Move the mouse to a certain offset from its current position
+      # The viewport is not scrolled if the coordinates provided are outside the viewport.
+      # MoveTargetOutOfBoundsError will be raised if the offsets are outside the viewport
+      #
+      # @example Move the pointer 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.
+      # @param [Integer] right_by horizontal offset. A negative value means moving the pointer left.
+      # @param [Integer] down_by vertical offset. A negative value means moving the pointer up.
       # @param [Symbol || String] device optional name of the PointerInput device to move
       # @return [ActionBuilder] A self reference.
       # @raise [MoveTargetOutOfBoundsError] if the provided offset is outside the document's boundaries.
       #
 
-      def move_by(right_by, down_by, device: nil)
-        pointer = get_pointer(device)
-        pointer.create_pointer_move(duration: default_move_duration,
+      def move_by(right_by, down_by, device: nil, duration: default_move_duration, **opts)
+        pointer = pointer_input(device)
+        pointer.create_pointer_move(duration: duration,
                                     x: Integer(right_by),
                                     y: Integer(down_by),
-                                    origin: Interactions::PointerMove::POINTER)
+                                    origin: Interactions::PointerMove::POINTER,
+                                    **opts)
         tick(pointer)
         self
       end
 
       #
-      # Moves the mouse to a given location in the viewport.
-      # If the coordinates provided are outside the viewport (the mouse will
-      # end up outside the browser window) then the viewport is scrolled to
-      # match.
+      # Moves the pointer to a given location in the viewport.
+      #
+      # The viewport is not scrolled if the coordinates provided are outside the viewport.
+      # MoveTargetOutOfBoundsError will be raised if the offsets are outside the viewport
       #
-      # @example Move the mouse to a certain position in the viewport
+      # @example Move the pointer to a certain position in the viewport
       #
       #    driver.action.move_to_location(100, 100).perform
       #
@@ -160,12 +151,13 @@ module Selenium
       # @raise [MoveTargetOutOfBoundsError] if the provided x or y value is outside the document's boundaries.
       #
 
-      def move_to_location(x, y, device: nil)
-        pointer = get_pointer(device)
-        pointer.create_pointer_move(duration: default_move_duration,
+      def move_to_location(x, y, device: nil, duration: default_move_duration, **opts)
+        pointer = pointer_input(device)
+        pointer.create_pointer_move(duration: duration,
                                     x: Integer(x),
                                     y: Integer(y),
-                                    origin: Interactions::PointerMove::VIEWPORT)
+                                    origin: Interactions::PointerMove::VIEWPORT,
+                                    **opts)
         tick(pointer)
         self
       end
@@ -186,9 +178,9 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def click_and_hold(element = nil, device: nil)
+      def click_and_hold(element = nil, button: nil, device: nil)
         move_to(element, device: device) if element
-        pointer_down(:left, device: device)
+        pointer_down(button || :left, device: device)
         self
       end
 
@@ -205,8 +197,8 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def release(device: nil)
-        pointer_up(:left, device: device)
+      def release(button: nil, device: nil)
+        pointer_up(button || :left, device: device)
         self
       end
 
@@ -232,10 +224,10 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def click(element = nil, device: nil)
+      def click(element = nil, button: nil, device: nil)
         move_to(element, device: device) if element
-        pointer_down(:left, device: device)
-        pointer_up(:left, device: device)
+        pointer_down(button || :left, device: device)
+        pointer_up(button || :left, device: device)
         self
       end
 
@@ -290,10 +282,7 @@ module Selenium
       #
 
       def context_click(element = nil, device: nil)
-        move_to(element, device: device) if element
-        pointer_down(:right, device: device)
-        pointer_up(:right, device: device)
-        self
+        click(element, button: :right, device: device)
       end
 
       #
@@ -348,15 +337,15 @@ module Selenium
 
       private
 
-      def button_action(button, action: nil, device: nil)
-        pointer = get_pointer(device)
-        pointer.send(action, button)
+      def button_action(button, action, device: nil, **opts)
+        pointer = pointer_input(device)
+        pointer.send(action, button, **opts)
         tick(pointer)
         self
       end
 
-      def get_pointer(device = nil)
-        get_device(device) || pointer_inputs.first
+      def pointer_input(name = nil)
+        device(name: name, type: Interactions::POINTER) || add_pointer_input(:mouse, 'mouse')
       end
     end # PointerActions
   end # WebDriver

data/lib/selenium/webdriver/common/{driver_extensions/has_network_connection.rb → interactions/pointer_cancel.rb}

@@ -17,21 +17,29 @@
 # specific language governing permissions and limitations
 # under the License.
 
-# TODO: Deprecated; Delete after 4.0 release
 module Selenium
   module WebDriver
-    module DriverExtensions
-      module HasNetworkConnection
-        def network_connection_type
-          raise Error::UnsupportedOperationError,
-                'The W3C standard does not currently support getting network connection'
+    module Interactions
+      #
+      # Action to cancel any other Pointer Action.
+      #
+      # @api private
+      #
+
+      class PointerCancel < Interaction
+        def initialize(source)
+          super(source)
+          @type = :pointerCancel
+        end
+
+        def assert_source(source)
+          raise TypeError, "#{source.type} is not a valid input type" unless source.is_a? PointerInput
         end
 
-        def network_connection_type=(*)
-          raise Error::UnsupportedOperationError,
-                'The W3C standard does not currently support setting network connection'
+        def encode
+          {type: type}
         end
-      end # HasNetworkConnection
-    end # DriverExtensions
+      end # PointerCancel
+    end # Interactions
   end # WebDriver
 end # Selenium