selenium-webdriver 4.1.0 → 4.9.0

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

@@ -0,0 +1,48 @@
+# 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
+      class ScrollOrigin
+        class << self
+          def element(element, x_offset = 0, y_offset = 0)
+            new(element, x_offset, y_offset)
+          end
+
+          def viewport(x_offset = 0, y_offset = 0)
+            new(:viewport, x_offset, y_offset)
+          end
+        end
+
+        attr_reader :origin, :x_offset, :y_offset
+
+        #
+        # Use a static method to access
+        # @api private
+        #
+        def initialize(origin, x_offset, y_offset)
+          @origin = origin
+          @x_offset = x_offset
+          @y_offset = y_offset
+        end
+      end # ScrollOrigin
+    end # WheelActions
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,54 @@
+# 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
+      #
+      # Actions related to pressing keys.
+      #
+      # @api private
+      #
+
+      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_source(source)
+          raise TypeError, "#{source.type} is not a valid input type" unless source.is_a? KeyInput
+        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
+    end # Interactions
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,113 @@
+# 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
+      attr_writer :default_scroll_duration
+
+      #
+      # By default this is set to 250ms in the ActionBuilder constructor
+      # It can be overridden with default_scroll_duration=
+      #
+
+      def default_scroll_duration
+        @default_scroll_duration ||= @duration / 1000.0 # convert ms to seconds
+      end
+
+      #
+      # If the element is outside the viewport, scrolls the bottom of the element to the bottom of the viewport.
+      #
+      # @example Scroll to element
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll_to(element).perform
+      #
+      # @param [Object] Which element to scroll into the viewport.
+      # @return [Selenium::WebDriver::WheelActions] A self reference.
+      def scroll_to(element, device: nil)
+        scroll(origin: element, device: device)
+      end
+
+      #
+      # Scrolls by provided amounts with the origin in the top left corner of the viewport.
+      #
+      # @example Scroll viewport by a specified amount
+      #    el = driver.find_element(id: "some_id")
+      #    driver.action.scroll_by(100, 200).perform
+      #
+      # @param [Integer] delta_x Distance along X axis to scroll using the wheel. A negative value scrolls left.
+      # @param [Integer] delta_y Distance along Y axis to scroll using the wheel. A negative value scrolls up.
+      # @return [Selenium::WebDriver::WheelActions] A self reference.
+      def scroll_by(delta_x, delta_y, device: nil)
+        scroll(delta_x: delta_x, delta_y: delta_y, device: device)
+      end
+
+      #
+      # Scrolls by provided amount based on a provided origin.
+      #
+      # The scroll origin is either the center of an element or the upper left of the viewport plus any offsets.
+      # If the origin is an element, and the element is not in the viewport, the bottom of the element will first
+      #   be scrolled to the bottom of the viewport.
+      #
+      # @example Scroll from element by a specified amount
+      #    el = driver.find_element(id: "some_id")
+      #    origin = WheelActions::ScrollOrigin.element(el)
+      #    driver.action.scroll_from(origin, 0, 200).perform
+      #
+      # @example Scroll from element by a specified amount with an offset
+      #    el = driver.find_element(id: "some_id")
+      #    origin = WheelActions::ScrollOrigin.element(el, 10, 10)
+      #    driver.action.scroll_from(origin, 100, 200).perform
+      #
+      # @example Scroll viewport by a specified amount with an offset
+      #    origin = WheelActions::ScrollOrigin.viewport(10, 10)
+      #    driver.action.scroll_from(origin, 0, 200).perform
+      #
+      # @param [ScrollOrigin] scroll_origin Where scroll originates (viewport or element center) plus provided offsets.
+      # @param [Integer] delta_x Distance along X axis to scroll using the wheel. A negative value scrolls left.
+      # @param [Integer] delta_y Distance along Y axis to scroll using the wheel. A negative value scrolls up.
+      # @return [Selenium::WebDriver::WheelActions] A self reference.
+      # @raise [Error::MoveTargetOutOfBoundsError] If the origin with offset is outside the viewport.
+      def scroll_from(scroll_origin, delta_x, delta_y, device: nil)
+        raise TypeError, "#{scroll_origin.inspect} isn't a valid ScrollOrigin" unless scroll_origin.is_a?(ScrollOrigin)
+
+        scroll(x: scroll_origin.x_offset,
+               y: scroll_origin.y_offset,
+               delta_x: delta_x,
+               delta_y: delta_y,
+               origin: scroll_origin.origin,
+               device: device)
+      end
+
+      private
+
+      def scroll(**opts)
+        opts[:duration] = default_scroll_duration
+        wheel = wheel_input(opts.delete(:device))
+        wheel.create_scroll(**opts)
+        tick(wheel)
+        self
+      end
+
+      def wheel_input(name = nil)
+        device(name: name, type: Interactions::WHEEL) || add_wheel_input('wheel')
+      end
+    end # WheelActions
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,42 @@
+# 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
+      #
+      # Creates actions specific to Pointer Input devices
+      #
+      # @api private
+      #
+
+      class WheelInput < InputDevice
+        def initialize(name = nil)
+          super(name)
+          @type = Interactions::WHEEL
+        end
+
+        def create_scroll(**opts)
+          opts[:source] = self
+          add_action(Scroll.new(**opts))
+        end
+      end # PointerInput
+    end # Interactions
+  end # WebDriver
+end # Selenium

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

@@ -90,6 +90,7 @@ module Selenium
         meta: "\ue03D",
         command: "\ue03D", # alias
         left_meta: "\ue03D", # alias
+        zenkaku_hankaku: "\uE040",
         right_shift: "\ue050",
         right_control: "\ue051",
         right_alt: "\ue052",

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

@@ -0,0 +1,55 @@
+# 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(capabilities, options, service, url)
+        raise ArgumentError, "Can't initialize #{self.class} with :url" if url
+
+        service ||= Service.send(browser)
+        caps = process_options(options, capabilities, service)
+        url = service_url(service)
+
+        [caps, url]
+      end
+
+      def process_options(options, capabilities, service)
+        default_options = Options.send(browser)
+
+        if options && capabilities
+          msg = "Don't use both :options and :capabilities when initializing #{self.class}, prefer :options"
+          raise ArgumentError, msg
+        elsif options && !options.is_a?(default_options.class)
+          raise ArgumentError, ":options must be an instance of #{default_options.class}"
+        elsif capabilities
+          WebDriver.logger.deprecate("The :capabilities parameter for #{self.class}",
+                                     ":options argument with an instance of #{self.class}",
+                                     id: :capabilities)
+          service.executable_path ||= WebDriver::DriverFinder.path(capabilities, service.class)
+          generate_capabilities(capabilities)
+        else
+          options ||= default_options
+          service.executable_path ||= WebDriver::DriverFinder.path(options, service.class)
+          options.as_json
+        end
+      end
+    end
+  end
+end

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

@@ -48,9 +48,10 @@ module Selenium
       #
       # @param [String] progname Allow child projects to use Selenium's Logger pattern
       #
-      def initialize(progname = 'Selenium')
+      def initialize(progname = 'Selenium', ignored: nil)
         @logger = create_logger(progname)
-        @ignored = []
+        @ignored = Array(ignored)
+        @first_warning = false
       end
 
       #
@@ -94,6 +95,13 @@ module Selenium
       # @yield see #deprecate
       #
       def warn(message, id: [])
+        unless @first_warning
+          @first_warning = true
+          warn("Details on how to use and modify Selenium logger:\n", id: [:logger_info]) do
+            "https://selenium.dev/documentation/webdriver/troubleshooting/logging#ruby\n"
+          end
+        end
+
         id = Array(id)
         return if (@ignored & id).any?
 

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

@@ -38,12 +38,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 +66,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 +85,13 @@ 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)
+
+        unless name.to_s.include?(':')
+          WebDriver.logger.deprecate('Options#add_option for w3c or browser specific capabilities',
+                                     'applicable attribute accessors or pass into constructor',
+                                     id: :add_option)
+        end
         @options[name] = value
       end
 
@@ -102,7 +101,7 @@ module Selenium
         as_json == other.as_json
       end
 
-      alias_method :eql?, :==
+      alias eql? ==
 
       #
       # @api private
@@ -113,11 +112,27 @@ module Selenium
 
         w3c_options = process_w3c_options(options)
 
-        self.class::CAPABILITIES.each do |capability_alias, capability_name|
-          capability_value = options.delete(capability_alias)
-          options[capability_name] = capability_value if !capability_value.nil? && !options.key?(capability_name)
+        browser_options = self.class::CAPABILITIES.each_with_object({}) do |(capability_alias, capability_name), hash|
+          from_name = options.delete(capability_name)
+          from_alias = options.delete(capability_alias)
+          capability_value = if !from_name.nil? && capability_alias != capability_name
+                               WebDriver.logger.deprecate("#{capability_name} as option",
+                                                          capability_alias.to_s, id: :option_symbols)
+                               from_name
+                             elsif !from_alias.nil?
+                               from_alias
+                             end
+
+          hash[capability_name] = capability_value unless capability_value.nil?
         end
-        browser_options = defined?(self.class::KEY) ? {self.class::KEY => options} : options
+
+        unless options.empty?
+          msg = 'These options are not w3c compliant and will result in failures in a future release'
+          WebDriver.logger.warn("#{msg}: #{options}")
+          browser_options.merge!(options)
+        end
+
+        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))

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

@@ -78,6 +78,10 @@ module Selenium
         engine == :jruby
       end
 
+      def truffleruby?
+        engine == :truffleruby
+      end
+
       def ruby_version
         RUBY_VERSION
       end
@@ -104,8 +108,7 @@ module Selenium
       end
 
       def cygwin?
-        RUBY_PLATFORM =~ /cygwin/
-        !Regexp.last_match.nil?
+        RUBY_PLATFORM.include?('cygwin')
       end
 
       def null_device
@@ -177,9 +180,9 @@ module Selenium
 
       def find_in_program_files(*binary_names)
         paths = [
-          ENV['PROGRAMFILES'] || '\\Program Files',
-          ENV['ProgramFiles(x86)'] || '\\Program Files (x86)',
-          ENV['ProgramW6432'] || '\\Program Files'
+          ENV.fetch('PROGRAMFILES', '\\Program Files'),
+          ENV.fetch('ProgramFiles(x86)', '\\Program Files (x86)'),
+          ENV.fetch('ProgramW6432', '\\Program Files')
         ]
 
         paths.each do |root|

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(*)

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

@@ -74,7 +74,7 @@ module Selenium
       def ==(other)
         other.is_a?(self.class) && as_json == other.as_json
       end
-      alias_method :eql?, :==
+      alias eql? ==
 
       def ftp=(value)
         self.type = :manual

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

@@ -61,9 +61,6 @@ module Selenium
         raise ArgumentError, "cannot find element by #{how.inspect}" unless by
 
         bridge.find_element_by by, what, ref
-      rescue Selenium::WebDriver::Error::TimeoutError
-        # Implicit Wait times out in Edge
-        raise Selenium::WebDriver::Error::NoSuchElementError
       end
 
       #
@@ -79,9 +76,6 @@ module Selenium
         raise ArgumentError, "cannot find elements by #{how.inspect}" unless by
 
         bridge.find_elements_by by, what, ref
-      rescue Selenium::WebDriver::Error::TimeoutError
-        # Implicit Wait times out in Edge
-        []
       end
 
       private

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

@@ -0,0 +1,108 @@
+# 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.
+
+require 'open3'
+
+module Selenium
+  module WebDriver
+    #
+    # Wrapper for getting information from the Selenium Manager binaries.
+    # This implementation is still in beta, and may change.
+    # @api private
+    #
+    class SeleniumManager
+      BIN_PATH = '../../../../../bin'
+
+      class << self
+        # @param [Options] options browser options.
+        # @return [String] the path to the correct driver.
+        def driver_path(options)
+          message = 'applicable driver not found; attempting to install with Selenium Manager'
+          WebDriver.logger.warn(message)
+
+          unless options.is_a?(Options)
+            raise ArgumentError, "SeleniumManager requires a WebDriver::Options instance, not #{options.inspect}"
+          end
+
+          command = [binary, '--browser', options.browser_name, '--output', 'json']
+          if options.browser_version
+            command << '--browser-version'
+            command << options.browser_version
+          end
+          if options.respond_to?(:binary) && !options.binary.nil?
+            command << '--browser-path'
+            command << options.binary.gsub('\\', '\\\\\\')
+          end
+          command << '--debug' if WebDriver.logger.debug?
+
+          location = run(*command)
+          WebDriver.logger.debug("Driver found at #{location}")
+          Platform.assert_executable location
+
+          location
+        end
+
+        private
+
+        # @return [String] the path to the correct selenium manager
+        def binary
+          @binary ||= begin
+            path = File.expand_path(BIN_PATH, __FILE__)
+            path << if Platform.windows?
+                      '/windows/selenium-manager.exe'
+                    elsif Platform.mac?
+                      '/macos/selenium-manager'
+                    elsif Platform.linux?
+                      '/linux/selenium-manager'
+                    end
+            location = File.expand_path(path, __FILE__)
+            unless location.is_a?(String) && File.exist?(location) && File.executable?(location)
+              raise Error::WebDriverError, 'Unable to obtain Selenium Manager'
+            end
+
+            WebDriver.logger.debug("Selenium Manager found at #{location}")
+            location
+          end
+        end
+
+        def run(*command)
+          WebDriver.logger.debug("Executing Process #{command}")
+
+          begin
+            stdout, stderr, status = Open3.capture3(*command)
+            json_output = stdout.empty? ? nil : JSON.parse(stdout)
+            result = json_output&.dig('result', 'message')
+          rescue StandardError => e
+            raise Error::WebDriverError, "Unsuccessful command executed: #{command}", e.message
+          end
+
+          if status.exitstatus.positive?
+            raise Error::WebDriverError, "Unsuccessful command executed: #{command}\n#{result}#{stderr}"
+          end
+
+          json_output['logs'].each do |log|
+            WebDriver.logger.send(log['level'].downcase, log['message'])
+          end
+
+          result
+        end
+      end
+    end # SeleniumManager
+  end # WebDriver
+end # Selenium