selenium-webdriver 4.1.0 → 4.23.0

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

@@ -0,0 +1,85 @@
+# 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 clicking, tapping or pressing the pointer.
+      #
+      # @api private
+      #
+
+      class PointerPress < Interaction
+        include PointerEventProperties
+
+        BUTTONS = {left: 0,
+                   touch: 0,
+                   pen_contact: 0,
+                   middle: 1,
+                   right: 2,
+                   pen_barrel: 2,
+                   x1: 3,
+                   back: 3,
+                   x2: 4,
+                   forward: 4}.freeze
+        DIRECTIONS = {down: :pointerDown, up: :pointerUp}.freeze
+
+        def initialize(source, direction, button, **opts)
+          super(source)
+          @direction = assert_direction(direction)
+          @button = assert_button(button)
+          @type = @direction
+          @opts = opts
+        end
+
+        def encode
+          process_opts.merge('type' => type.to_s, 'button' => @button)
+        end
+
+        private
+
+        def assert_source(source)
+          raise TypeError, "#{source.type} is not a valid input type" unless source.is_a? PointerInput
+        end
+
+        def assert_button(button)
+          case button
+          when Symbol
+            raise ArgumentError, "#{button} is not a valid button!" unless BUTTONS.key? button
+
+            BUTTONS[button]
+          when Integer
+            raise ArgumentError, 'Button number cannot be negative!' if button.negative?
+
+            button
+          else
+            raise TypeError, "button must be a positive integer or one of #{BUTTONS.keys}, not #{button.class}"
+          end
+        end
+
+        def assert_direction(direction)
+          raise ArgumentError, "#{direction.inspect} is not a valid button direction" unless DIRECTIONS.key? direction
+
+          DIRECTIONS[direction]
+        end
+      end # PointerPress
+    end # Interactions
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,59 @@
+# 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 related to scrolling a wheel.
+      #
+      # @api private
+      #
+
+      class Scroll < Interaction
+        def initialize(source:, origin: :viewport, duration: 0.25, **opts)
+          super(source)
+          @type = :scroll
+          @duration = duration * 1000
+          @origin = origin
+          @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)
+          raise TypeError, "#{source.type} is not a valid input type" unless source.is_a? WheelInput
+        end
+
+        def encode
+          {'type' => type.to_s,
+           'duration' => @duration.to_i,
+           'x' => @x_offset,
+           'y' => @y_offset,
+           'deltaX' => @delta_x,
+           'deltaY' => @delta_y,
+           'origin' => @origin.is_a?(Element) ? @origin : @origin.to_s}
+        end
+      end # PointerPress
+    end # Interactions
+  end # WebDriver
+end # Selenium

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,114 @@
+# 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] element Which element to scroll into the viewport.
+      # @param [Object] device Which device to use to scroll
+      # @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
+          @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,53 @@
+# 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 ||= begin
+          finder = WebDriver::DriverFinder.new(options, service)
+          if options.respond_to?(:binary) && finder.browser_path?
+            options.binary = finder.browser_path
+            options.browser_version = nil
+          end
+          finder.driver_path
+        end
+        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
+      # @param [Symbol, Array<Symbol>] 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<Symbol>] 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<Symbol>] 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<Symbol>] 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,24 +175,40 @@ 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)
-        logger = ::Logger.new($stdout)
+      def create_logger(name, level:)
+        logger = ::Logger.new($stderr)
         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"
+          "#{time.strftime('%F %T')} #{severity} #{progname} #{msg}\n".force_encoding('UTF-8')
         end
 
         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

@@ -56,7 +56,7 @@ module Selenium
         opts[:httpOnly] = http_only if http_only
 
         obj = opts.delete(:expires)
-        opts[:expiry] = seconds_from(obj).to_i if obj
+        opts[:expiry] = seconds_from(obj).to_int if obj
 
         @bridge.add_cookie opts
       end
@@ -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