selenium-webdriver 4.2.1 → 4.15.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
@@ -35,13 +34,20 @@ module Selenium
         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/pointer_actions.rb

@@ -68,9 +68,8 @@ module Selenium
       end
 
       #
-      # Moves the pointer to the middle of the given element.
-      # its location is calculated using getBoundingClientRect.
-      # Then the pointer 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.
       #
       # The element is not scrolled into view.
       # MoveTargetOutOfBoundsError will be raised if element with offset is outside the viewport
@@ -88,32 +87,19 @@ 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, duration: default_move_duration, **opts)
-        pointer = pointer_input(device)
-        if right_by || down_by
-          WebDriver.logger.warn("moving to an element with offset currently tries to use
-the top left corner of the element as the origin; in Selenium 4.3 it will use the in-view
-center point of the element as the origin.")
-          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: duration,
-                                    x: left,
-                                    y: top,
+      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)
@@ -192,9 +178,9 @@ center point of the element as the origin.")
       # @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
 
@@ -211,8 +197,8 @@ center point of the element as the origin.")
       # @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
 
@@ -238,10 +224,10 @@ center point of the element as the origin.")
       # @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
 
@@ -296,10 +282,7 @@ center point of the element as the origin.")
       #
 
       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
 
       #

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

@@ -33,12 +33,12 @@ module Selenium
         POINTER = :pointer
         ORIGINS = [VIEWPORT, POINTER].freeze
 
-        def initialize(source, duration, x, y, element: nil, origin: nil, **opts)
+        def initialize(source, duration, x, y, **opts)
           super(source)
           @duration = duration * 1000
           @x_offset = x
           @y_offset = y
-          @origin = element || origin || :viewport
+          @origin = opts.delete(:element) || opts.delete(:origin) || :viewport
           @type = :pointerMove
           @opts = opts
         end

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

@@ -27,15 +27,17 @@ module Selenium
       #
 
       class Scroll < Interaction
-        def initialize(source:, x: 0, y: 0, delta_x: 0, delta_y: 0, origin: :viewport, duration: 0.25)
+        def initialize(source:, origin: :viewport, duration: 0.25, **opts)
           super(source)
           @type = :scroll
           @duration = duration * 1000
           @origin = origin
-          @x_offset = x
-          @y_offset = y
-          @delta_x = delta_x
-          @delta_y = delta_y
+          @x_offset = opts.delete(:x) || 0
+          @y_offset = opts.delete(:y) || 0
+          @delta_x = opts.delete(:delta_x) || 0
+          @delta_y = opts.delete(:delta_y) || 0
+
+          raise ArgumentError, "Invalid arguments: #{opts.keys}" unless opts.empty?
         end
 
         def assert_source(source)

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

@@ -0,0 +1,46 @@
+# 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 LocalDriver
+      def initialize_local_driver(options, service, url)
+        raise ArgumentError, "Can't initialize #{self.class} with :url" if url
+
+        service ||= Service.send(browser)
+        caps = process_options(options, service)
+        url = service_url(service)
+
+        [caps, url]
+      end
+
+      def process_options(options, service)
+        default_options = Options.send(browser)
+        options ||= default_options
+
+        unless options.is_a?(default_options.class)
+          raise ArgumentError, ":options must be an instance of #{default_options.class}"
+        end
+
+        service.executable_path ||= WebDriver::DriverFinder.path(options, service.class)
+        options.as_json
+      end
+    end
+  end
+end

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

@@ -38,19 +38,31 @@ module Selenium
 
       def_delegators :@logger,
                      :close,
-                     :debug, :debug?,
-                     :info, :info?,
+                     :debug?,
+                     :info?,
                      :warn?,
-                     :error, :error?,
+                     :error?,
                      :fatal, :fatal?,
-                     :level, :level=
+                     :level
 
       #
       # @param [String] progname Allow child projects to use Selenium's Logger pattern
       #
-      def initialize(progname = 'Selenium')
-        @logger = create_logger(progname)
-        @ignored = []
+      def initialize(progname = 'Selenium', default_level: nil, ignored: nil, allowed: nil)
+        default_level ||= $DEBUG || ENV.key?('DEBUG') ? :debug : :warn
+
+        @logger = create_logger(progname, level: default_level)
+        @ignored = Array(ignored)
+        @allowed = Array(allowed)
+        @first_warning = false
+      end
+
+      def level=(level)
+        if level == :info && @logger.level == :info
+          info(':info is now the default log level, to see additional logging, set log level to :debug')
+        end
+
+        @logger.level = level
       end
 
       #
@@ -80,27 +92,64 @@ module Selenium
       #
       # Will not log the provided ID.
       #
-      # @param [Array, Symbol] id
+      # @param [Array, Symbol] ids
+      #
+      def ignore(*ids)
+        @ignored += Array(ids).flatten
+      end
+
+      #
+      # Will only log the provided ID.
       #
-      def ignore(id)
-        Array(id).each { |ignore| @ignored << ignore }
+      # @param [Array, Symbol] ids
+      #
+      def allow(ids)
+        @allowed += Array(ids).flatten
       end
 
       #
-      # Overrides default #warn to skip ignored messages by provided id
+      # Used to supply information of interest for debugging a problem
+      # Overrides default #debug to skip ignored messages by provided id
       #
       # @param [String] message
       # @param [Symbol, Array<Sybmol>] id
       # @yield see #deprecate
       #
-      def warn(message, id: [])
-        id = Array(id)
-        return if (@ignored & id).any?
+      def debug(message, id: [], &block)
+        discard_or_log(:debug, message, id, &block)
+      end
 
-        msg = id.empty? ? message : "[#{id.map(&:inspect).join(', ')}] #{message} "
-        msg += " #{yield}" if block_given?
+      #
+      # Used to supply information of general interest
+      #
+      # @param [String] message
+      # @param [Symbol, Array<Sybmol>] id
+      # @yield see #deprecate
+      #
+      def info(message, id: [], &block)
+        discard_or_log(:info, message, id, &block)
+      end
 
-        @logger.warn { msg }
+      #
+      # Used to supply information that suggests an error occurred
+      #
+      # @param [String] message
+      # @param [Symbol, Array<Sybmol>] id
+      # @yield see #deprecate
+      #
+      def error(message, id: [], &block)
+        discard_or_log(:error, message, id, &block)
+      end
+
+      #
+      # Used to supply information that suggests action be taken by user
+      #
+      # @param [String] message
+      # @param [Symbol, Array<Sybmol>] id
+      # @yield see #deprecate
+      #
+      def warn(message, id: [], &block)
+        discard_or_log(:warn, message, id, &block)
       end
 
       #
@@ -114,11 +163,11 @@ module Selenium
       #
       def deprecate(old, new = nil, id: [], reference: '', &block)
         id = Array(id)
-        return if @ignored.include?(:deprecations) || (@ignored & id).any?
+        return if @ignored.include?(:deprecations)
 
-        ids = id.empty? ? '' : "[#{id.map(&:inspect).join(', ')}] "
+        id << :deprecations if @allowed.include?(:deprecations)
 
-        message = +"[DEPRECATION] #{ids}#{old} is deprecated"
+        message = +"[DEPRECATION] #{old} is deprecated"
         message << if new
                      ". Use #{new} instead."
                    else
@@ -126,15 +175,15 @@ module Selenium
                    end
         message << " See explanation for this deprecation: #{reference}." unless reference.empty?
 
-        warn message, &block
+        discard_or_log(:warn, message, id, &block)
       end
 
       private
 
-      def create_logger(name)
+      def create_logger(name, level:)
         logger = ::Logger.new($stdout)
         logger.progname = name
-        logger.level = default_level
+        logger.level = level
         logger.formatter = proc do |severity, time, progname, msg|
           "#{time.strftime('%F %T')} #{severity} #{progname} #{msg}\n"
         end
@@ -142,8 +191,24 @@ module Selenium
         logger
       end
 
-      def default_level
-        $DEBUG || ENV.key?('DEBUG') ? :debug : :warn
+      def discard_or_log(level, message, id)
+        id = Array(id)
+        return if (@ignored & id).any?
+        return if @allowed.any? && (@allowed & id).none?
+
+        return if ::Logger::Severity.const_get(level.upcase) < @logger.level
+
+        unless @first_warning
+          @first_warning = true
+          info("Details on how to use and modify Selenium logger:\n", id: [:logger_info]) do
+            "https://selenium.dev/documentation/webdriver/troubleshooting/logging\n"
+          end
+        end
+
+        msg = id.empty? ? message : "[#{id.map(&:inspect).join(', ')}] #{message} "
+        msg += " #{yield}" if block_given?
+
+        @logger.send(level) { msg }
       end
     end # Logger
   end # WebDriver

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

@@ -104,33 +104,6 @@ module Selenium
         @timeouts ||= Timeouts.new(@bridge)
       end
 
-      def logs
-        WebDriver.logger.deprecate('Manager#logs', 'Chrome::Driver#logs')
-        @logs ||= Logs.new(@bridge)
-      end
-
-      #
-      # @param type [Symbol] Supports two values: :tab and :window.
-      # @return [String] The value of the window handle
-      #
-      def new_window(type = :tab)
-        WebDriver.logger.deprecate('Manager#new_window', 'TargetLocator#new_window', id: :new_window) do
-          'e.g., `driver.switch_to.new_window(:tab)`'
-        end
-        case type
-        when :tab, :window
-          result = @bridge.new_window(type)
-          unless result.key?('handle')
-            raise UnknownError, "the driver did not return a handle. " \
-                                "The returned result: #{result.inspect}"
-          end
-          result['handle']
-        else
-          raise ArgumentError, "invalid argument for type. Got: '#{type.inspect}'. " \
-                               "Try :tab or :window"
-        end
-      end
-
       def window
         @window ||= Window.new(@bridge)
       end

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

@@ -24,6 +24,8 @@ module Selenium
                        set_window_rect timeouts unhandled_prompt_behavior strict_file_interactability
                        web_socket_url].freeze
 
+      GRID_OPTIONS = %i[enable_downloads].freeze
+
       class << self
         attr_reader :driver_path
 
@@ -38,12 +40,12 @@ module Selenium
         def ie(**opts)
           IE::Options.new(**opts)
         end
-        alias_method :internet_explorer, :ie
+        alias internet_explorer ie
 
         def edge(**opts)
           Edge::Options.new(**opts)
         end
-        alias_method :microsoftedge, :edge
+        alias microsoftedge edge
 
         def safari(**opts)
           Safari::Options.new(**opts)
@@ -66,17 +68,10 @@ module Selenium
 
       attr_accessor :options
 
-      def initialize(options: nil, **opts)
+      def initialize(**opts)
         self.class.set_capabilities
 
-        @options = if options
-                     WebDriver.logger.deprecate(":options as keyword for initializing #{self.class}",
-                                                "custom values directly in #new constructor",
-                                                id: :options_options)
-                     opts.merge(options)
-                   else
-                     opts
-                   end
+        @options = opts
         @options[:browser_name] = self.class::BROWSER
       end
 
@@ -92,7 +87,7 @@ module Selenium
       #
 
       def add_option(name, value = nil)
-        @options[name.keys.first] = name.values.first if value.nil? && name.is_a?(Hash)
+        name, value = name.first if value.nil? && name.is_a?(Hash)
         @options[name] = value
       end
 
@@ -102,7 +97,7 @@ module Selenium
         as_json == other.as_json
       end
 
-      alias_method :eql?, :==
+      alias eql? ==
 
       #
       # @api private
@@ -111,13 +106,18 @@ module Selenium
       def as_json(*)
         options = @options.dup
 
+        downloads = options.delete(:enable_downloads)
+        options['se:downloadsEnabled'] = downloads unless downloads.nil?
         w3c_options = process_w3c_options(options)
 
-        self.class::CAPABILITIES.each do |capability_alias, capability_name|
+        browser_options = self.class::CAPABILITIES.each_with_object({}) do |(capability_alias, capability_name), hash|
           capability_value = options.delete(capability_alias)
-          options[capability_name] = capability_value if !capability_value.nil? && !options.key?(capability_name)
+          hash[capability_name] = capability_value unless capability_value.nil?
         end
-        browser_options = defined?(self.class::KEY) ? {self.class::KEY => options} : options
+
+        raise Error::WebDriverError, "These options are not w3c compliant: #{options}" unless options.empty?
+
+        browser_options = {self.class::KEY => browser_options} if defined?(self.class::KEY)
 
         process_browser_options(browser_options)
         generate_as_json(w3c_options.merge(browser_options))
@@ -130,7 +130,7 @@ module Selenium
       end
 
       def process_w3c_options(options)
-        w3c_options = options.select { |key, _val| w3c?(key) }
+        w3c_options = options.select { |key, val| w3c?(key) && !val.nil? }
         w3c_options[:unhandled_prompt_behavior] &&= w3c_options[:unhandled_prompt_behavior]&.to_s&.tr('_', ' ')
         options.delete_if { |key, _val| w3c?(key) }
         w3c_options

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

@@ -62,22 +62,14 @@ module Selenium
         end
       end
 
-      def bitsize
-        @bitsize ||= if defined?(FFI::Platform::ADDRESS_SIZE)
-                       FFI::Platform::ADDRESS_SIZE
-                     elsif defined?(FFI)
-                       FFI.type_size(:pointer) == 4 ? 32 : 64
-                     elsif jruby?
-                       Integer(ENV_JAVA['sun.arch.data.model'])
-                     else
-                       1.size == 4 ? 32 : 64
-                     end
-      end
-
       def jruby?
         engine == :jruby
       end
 
+      def truffleruby?
+        engine == :truffleruby
+      end
+
       def ruby_version
         RUBY_VERSION
       end
@@ -105,7 +97,6 @@ module Selenium
 
       def cygwin?
         RUBY_PLATFORM.include?('cygwin')
-        !Regexp.last_match.nil?
       end
 
       def null_device
@@ -155,43 +146,6 @@ module Selenium
         at_exit { yield if Process.pid == pid }
       end
 
-      def find_binary(*binary_names)
-        paths = ENV['PATH'].split(File::PATH_SEPARATOR)
-
-        if windows?
-          binary_names.map! { |n| "#{n}.exe" }
-          binary_names.dup.each { |n| binary_names << n.gsub('exe', 'bat') }
-        end
-
-        binary_names.each do |binary_name|
-          paths.each do |path|
-            full_path = File.join(path, binary_name)
-            full_path = unix_path(full_path) if windows?
-            exe = Dir.glob(full_path).find { |f| File.executable?(f) }
-            return exe if exe
-          end
-        end
-
-        nil
-      end
-
-      def find_in_program_files(*binary_names)
-        paths = [
-          ENV.fetch('PROGRAMFILES', '\\Program Files'),
-          ENV.fetch('ProgramFiles(x86)', '\\Program Files (x86)'),
-          ENV.fetch('ProgramW6432', '\\Program Files')
-        ]
-
-        paths.each do |root|
-          binary_names.each do |name|
-            exe = File.join(root, name)
-            return exe if File.executable?(exe)
-          end
-        end
-
-        nil
-      end
-
       def localhost
         info = Socket.getaddrinfo 'localhost', 80, Socket::AF_INET, Socket::SOCK_STREAM
 

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

@@ -34,7 +34,7 @@ module Selenium
         Platform.interfaces.each do |host|
           TCPServer.new(host, port).close
         rescue *IGNORED_ERRORS => e
-          WebDriver.logger.debug("port prober could not bind to #{host}:#{port} (#{e.message})")
+          WebDriver.logger.debug("port prober could not bind to #{host}:#{port} (#{e.message})", id: :driver_service)
           # ignored - some machines appear unable to bind to some of their interfaces
         end
 

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

@@ -40,7 +40,7 @@ module Selenium
       end
 
       def as_json(*)
-        {"zip" => encoded}
+        {'zip' => encoded}
       end
 
       def to_json(*)