selenium-webdriver 4.1.0 → 4.7.1

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

@@ -22,6 +22,7 @@ module Selenium
     class ActionBuilder
       include KeyActions # Actions specific to key inputs
       include PointerActions # Actions specific to pointer inputs
+      include WheelActions # Actions specific to wheel inputs
 
       attr_reader :devices
 
@@ -31,19 +32,40 @@ module Selenium
       # the mouse is moving. Keep in mind that pauses must be added for other devices in order to line up the actions
       # correctly when using asynchronous.
       #
-      # @param [Selenium::WebDriver::Remote::Bridge] bridge the bridge for the current driver instance
-      # @param [Selenium::WebDriver::Interactions::PointerInput] mouse PointerInput for the mouse.
-      # @param [Selenium::WebDriver::Interactions::KeyInput] keyboard KeyInput for the keyboard.
-      # @param [Boolean] async Whether to perform the actions asynchronously per device. Defaults to false for
-      #   backwards compatibility.
+      # @param [Selenium::WebDriver::Remote::Bridge] bridge the bridge for the current driver instance.
+      # @param [Selenium::WebDriver::Interactions::PointerInput] deprecated_mouse PointerInput for the mouse.
+      # @param [Selenium::WebDriver::Interactions::KeyInput] deprecated_keyboard KeyInput for the keyboard.
+      # @param [Boolean] deprecated_async Whether to perform the actions asynchronously per device.
+      #   Defaults to false for backwards compatibility.
+      # @param [Array<Selenium::WebDriver::Interactions::InputDevices>] devices list of valid sources of input.
+      # @param [Boolean] async Whether to perform the actions asynchronously per device.
       # @return [ActionBuilder] A self reference.
       #
 
-      def initialize(bridge, mouse, keyboard, async = false)
-        # For backwards compatibility, automatically include mouse & keyboard
+      def initialize(bridge, deprecated_mouse = nil, deprecated_keyboard = nil, deprecated_async = nil,
+                     devices: [], async: false, duration: 250)
         @bridge = bridge
-        @devices = [mouse, keyboard]
-        @async = async
+        @duration = duration
+
+        @async = if deprecated_async.nil?
+                   async
+                 else
+                   WebDriver.logger.deprecate('initializing ActionBuilder with async parameter',
+                                              ':async keyword',
+                                              id: :action_async)
+                   deprecated_async
+                 end
+
+        @devices = []
+        if deprecated_keyboard || deprecated_mouse
+          WebDriver.logger.deprecate "initializing ActionBuilder with keyboard and mouse parameters",
+                                     "devices keyword or, even better, Driver#action",
+                                     id: :action_devices
+          add_input(deprecated_mouse)
+          add_input(deprecated_keyboard)
+        else
+          Array(devices).each { |device| add_input(device) }
+        end
       end
 
       #
@@ -61,9 +83,7 @@ module Selenium
       #
 
       def add_pointer_input(kind, name)
-        new_input = Interactions.pointer(kind, name: name)
-        add_input(new_input)
-        new_input
+        add_input(Interactions.pointer(kind, name: name))
       end
 
       #
@@ -79,9 +99,23 @@ module Selenium
       #
 
       def add_key_input(name)
-        new_input = Interactions.key(name)
-        add_input(new_input)
-        new_input
+        add_input(Interactions.key(name))
+      end
+
+      #
+      # Adds a WheelInput device
+      #
+      # @example Add a wheel input device
+      #
+      #    builder = device.action
+      #    builder.add_wheel_input('wheel2')
+      #
+      # @param [String] name name for the device
+      # @return [Interactions::WheelInput] The wheel input added
+      #
+
+      def add_wheel_input(name)
+        add_input(Interactions.wheel(name))
       end
 
       #
@@ -92,7 +126,26 @@ module Selenium
       #
 
       def get_device(name)
-        @devices.find { |device| device.name == name.to_s }
+        WebDriver.logger.deprecate('#get_device with name parameter',
+                                   '#device with :name or :type keyword',
+                                   id: :get_device)
+        device(name: name)
+      end
+
+      #
+      # Retrieves the input device for the given name or type
+      #
+      # @param [String] name name of the input device
+      # @param [String] type name of the input device
+      # @return [Selenium::WebDriver::Interactions::InputDevice] input device with given name or type
+      #
+
+      def device(name: nil, type: nil)
+        input = @devices.find { |device| (device.name == name.to_s || name.nil?) && (device.type == type || type.nil?) }
+
+        raise(ArgumentError, "Can not find device: #{name}") if name && input.nil?
+
+        input
       end
 
       #
@@ -115,6 +168,16 @@ module Selenium
         @devices.select { |device| device.type == Interactions::KEY }
       end
 
+      #
+      # Retrieves the current WheelInput device
+      #
+      # @return [Selenium::WebDriver::Interactions::InputDevice] current WheelInput devices
+      #
+
+      def wheel_inputs
+        @devices.select { |device| device.type == Interactions::WHEEL }
+      end
+
       #
       # Creates a pause for the given device of the given duration. If no duration is given, the pause will only wait
       # for all actions to complete in that tick.
@@ -131,8 +194,11 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pause(device, duration = nil)
-        device.create_pause(duration)
+      def pause(deprecated_device = nil, deprecated_duration = nil, device: nil, duration: 0)
+        deprecate_method(deprecated_device, deprecated_duration)
+
+        device ||= deprecated_device || pointer_input
+        device.create_pause(deprecated_duration || duration)
         self
       end
 
@@ -152,7 +218,14 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pauses(device, number, duration = nil)
+      def pauses(deprecated_device = nil, deprecated_number = nil, deprecated_duration = nil,
+                 device: nil, number: nil, duration: 0)
+        deprecate_method(deprecated_device, deprecated_duration, deprecated_number, method: :pauses)
+
+        number ||= deprecated_number || 2
+        device ||= deprecated_device || pointer_input
+        duration ||= deprecated_duration || 0
+
         number.times { device.create_pause(duration) }
         self
       end
@@ -162,7 +235,7 @@ module Selenium
       #
 
       def perform
-        @bridge.send_actions @devices.map(&:encode).compact
+        @bridge.send_actions @devices.filter_map(&:encode)
         clear_all_actions
         nil
       end
@@ -202,12 +275,26 @@ module Selenium
       #
 
       def add_input(device)
+        device = Interactions.send(device) if device.is_a?(Symbol) && Interactions.respond_to?(device)
+
+        raise TypeError, "#{device.inspect} is not a valid InputDevice" unless device.is_a?(Interactions::InputDevice)
+
         unless @async
           max_device = @devices.max { |a, b| a.actions.length <=> b.actions.length }
-          pauses(device, max_device.actions.length)
+          pauses(device: device, number: max_device.actions.length) if max_device
         end
         @devices << device
+        device
       end
+
+      def deprecate_method(device = nil, duration = nil, number = nil, method: :pause)
+        return unless device || number || duration
+
+        WebDriver.logger.deprecate "ActionBuilder##{method} with ordered parameters",
+                                   ':device, :duration, :number keywords',
+                                   id: method
+      end
+
     end # ActionBuilder
   end # WebDriver
 end # Selenium

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

@@ -0,0 +1,126 @@
+# 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
+
+    #
+    # @api private
+    #
+
+    class ChildProcess
+      TimeoutError = Class.new(StandardError)
+
+      SIGTERM = 'TERM'
+      SIGKILL = 'KILL'
+
+      POLL_INTERVAL = 0.1
+
+      attr_accessor :detach
+      attr_writer :io
+
+      def self.build(*command)
+        new(*command)
+      end
+
+      def initialize(*command)
+        @command = command
+        @detach = false
+        @pid = nil
+        @status = nil
+      end
+
+      def io
+        @io ||= Platform.null_device
+      end
+
+      def start
+        options = {%i[out err] => io}
+        options[:pgroup] = true unless Platform.windows? # NOTE: this is a bug only in Windows 7
+
+        WebDriver.logger.debug("Starting process: #{@command} with #{options}")
+        @pid = Process.spawn(*@command, options)
+        WebDriver.logger.debug("  -> pid: #{@pid}")
+
+        Process.detach(@pid) if detach
+      end
+
+      def stop(timeout = 3)
+        return unless @pid
+        return if exited?
+
+        WebDriver.logger.debug("Sending TERM to process: #{@pid}")
+        terminate(@pid)
+        poll_for_exit(timeout)
+
+        WebDriver.logger.debug("  -> stopped #{@pid}")
+      rescue TimeoutError, Errno::EINVAL
+        WebDriver.logger.debug("    -> sending KILL to process: #{@pid}")
+        kill(@pid)
+        wait
+        WebDriver.logger.debug("      -> killed #{@pid}")
+      end
+
+      def alive?
+        @pid && !exited?
+      end
+
+      def exited?
+        return unless @pid
+
+        WebDriver.logger.debug("Checking if #{@pid} is exited:")
+        _, @status = Process.waitpid2(@pid, Process::WNOHANG | Process::WUNTRACED) if @status.nil?
+        return if @status.nil?
+
+        exit_code = @status.exitstatus || @status.termsig
+        WebDriver.logger.debug("  -> exit code is #{exit_code.inspect}")
+
+        !!exit_code
+      end
+
+      def poll_for_exit(timeout)
+        WebDriver.logger.debug("Polling #{timeout} seconds for exit of #{@pid}")
+
+        end_time = Time.now + timeout
+        sleep POLL_INTERVAL until exited? || Time.now > end_time
+
+        raise TimeoutError, "  ->  #{@pid} still alive after #{timeout} seconds" unless exited?
+      end
+
+      def wait
+        return if exited?
+
+        _, @status = Process.waitpid2(@pid)
+      end
+
+      private
+
+      def terminate(pid)
+        Process.kill(SIGTERM, pid)
+      end
+
+      def kill(pid)
+        Process.kill(SIGKILL, pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        # already dead
+      end
+
+    end # ChildProcess
+  end # WebDriver
+end # Selenium

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

@@ -123,8 +123,8 @@ module Selenium
       # @see ActionBuilder
       #
 
-      def action
-        bridge.action
+      def action(**opts)
+        bridge.action(**opts)
       end
 
       def mouse
@@ -248,6 +248,15 @@ module Selenium
         bridge.execute_async_script(script, *args)
       end
 
+      #
+      # @return [VirtualAuthenticator]
+      # @see VirtualAuthenticator
+      #
+
+      def add_virtual_authenticator(options)
+        bridge.add_virtual_authenticator(options)
+      end
+
       #-------------------------------- sugar  --------------------------------
 
       #
@@ -307,71 +316,29 @@ module Selenium
 
       attr_reader :bridge
 
-      def create_bridge(**opts)
-        opts[:url] ||= service_url(opts)
-        caps = opts.delete(:capabilities)
-        # NOTE: This is deprecated
-        cap_array = caps.is_a?(Hash) ? [caps] : Array(caps)
-
-        desired_capabilities = opts.delete(:desired_capabilities)
-        if desired_capabilities
-          WebDriver.logger.deprecate(':desired_capabilities as a parameter for driver initialization',
-                                     ':capabilities with an Array value of capabilities/options if necessary',
-                                     id: :desired_capabilities)
-          desired_capabilities = Remote::Capabilities.new(desired_capabilities) if desired_capabilities.is_a?(Hash)
-          cap_array << desired_capabilities
-        end
-
-        options = opts.delete(:options)
-        if options
-          WebDriver.logger.deprecate(':options as a parameter for driver initialization',
-                                     ':capabilities with an Array of value capabilities/options if necessary',
-                                     id: :browser_options)
-          cap_array << options
+      def create_bridge(capabilities: nil, options: nil, url: nil, service: nil, http_client: nil)
+        Remote::Bridge.new(http_client: http_client,
+                           url: url || service_url(service)).tap do |bridge|
+          generated_caps = options ? options.as_json : generate_capabilities(capabilities)
+          bridge.create_session(generated_caps)
         end
-
-        capabilities = generate_capabilities(cap_array)
-
-        bridge_opts = {http_client: opts.delete(:http_client), url: opts.delete(:url)}
-        raise ArgumentError, "Unable to create a driver with parameters: #{opts}" unless opts.empty?
-
-        bridge = Remote::Bridge.new(**bridge_opts)
-
-        bridge.create_session(capabilities)
-        bridge
       end
 
-      def generate_capabilities(cap_array)
-        cap_array.map { |cap|
+      def generate_capabilities(capabilities)
+        Array(capabilities).map { |cap|
           if cap.is_a? Symbol
             cap = Remote::Capabilities.send(cap)
-          elsif cap.is_a? Hash
-            new_message = 'Capabilities instance initialized with the Hash, or build values with Options class'
-            WebDriver.logger.deprecate("passing a Hash value to :capabilities",
-                                       new_message,
-                                       id: :capabilities_hash)
-            cap = Remote::Capabilities.new(cap)
           elsif !cap.respond_to? :as_json
             msg = ":capabilities parameter only accepts objects responding to #as_json which #{cap.class} does not"
             raise ArgumentError, msg
           end
-          cap&.as_json
+          cap.as_json
         }.inject(:merge) || Remote::Capabilities.send(browser || :new)
       end
 
-      def service_url(opts)
-        service_config = opts.delete(:service)
-        %i[driver_opts driver_path port].each do |key|
-          next unless opts.key? key
-
-          WebDriver.logger.deprecate(":#{key}", ':service with an instance of Selenium::WebDriver::Service',
-                                     id: "service_#{key}".to_sym)
-        end
-        service_config ||= Service.send(browser,
-                                        args: opts.delete(:driver_opts),
-                                        path: opts.delete(:driver_path),
-                                        port: opts.delete(:port))
-        @service = service_config.launch
+      def service_url(service)
+        service ||= Service.send(browser)
+        @service = service.launch
         @service.uri
       end
 

data/lib/selenium/webdriver/common/driver_extensions/{has_remote_status.rb → has_bidi.rb}

@@ -20,12 +20,19 @@
 module Selenium
   module WebDriver
     module DriverExtensions
-      module HasRemoteStatus
-        def remote_status
-          WebDriver.logger.deprecate('#remote_status', '#status')
-          @bridge.status
+      module HasBiDi
+
+        #
+        # Retrieves WebDriver BiDi connection.
+        #
+        # @return [BiDi]
+        #
+
+        def bidi
+          @bidi ||= Selenium::WebDriver::BiDi.new(url: capabilities[:web_socket_url])
         end
-      end # HasRemoteStatus
+
+      end # HasBiDi
     end # DriverExtensions
   end # WebDriver
 end # Selenium

data/lib/selenium/webdriver/common/driver_extensions/has_casting.rb

@@ -52,6 +52,16 @@ module Selenium
           @bridge.start_cast_tab_mirroring(name)
         end
 
+        #
+        # Starts a tab mirroring session on a specific receiver target.
+        #
+        # @param [String] name the sink to use as the target
+        #
+
+        def start_cast_desktop_mirroring(name)
+          @bridge.start_cast_desktop_mirroring(name)
+        end
+
         #
         # Gets error messages when there is any issue in a Cast session.
         #

data/lib/selenium/webdriver/common/driver_extensions/has_context.rb

@@ -27,8 +27,7 @@ module Selenium
         #         a `with` statement. The state of the context on the server is
         #         saved before entering the block, and restored upon exiting it.
         #
-        # @param [String] name which permission to set
-        # @param [String] value what to set the permission to
+        # @param [String] value which context gets set (either 'chrome' or 'content')
         #
 
         def context=(value)

data/lib/selenium/webdriver/common/driver_extensions/has_log_events.rb

@@ -114,7 +114,7 @@ module Selenium
           execute_script(mutation_listener)
           devtools.page.add_script_to_evaluate_on_new_document(source: mutation_listener)
 
-          devtools.runtime.on(:binding_called, &method(:log_mutation_event))
+          devtools.runtime.on(:binding_called) { |event| log_mutation_event(event) }
         end
 
         def log_mutation_event(params)

data/lib/selenium/webdriver/common/driver_extensions/has_network_interception.rb

@@ -61,75 +61,10 @@ module Selenium
         #
 
         def intercept(&block)
-          devtools.network.set_cache_disabled(cache_disabled: true)
-          devtools.fetch.on(:request_paused) do |params|
-            id = params['requestId']
-            if params.key?('responseStatusCode') || params.key?('responseErrorReason')
-              intercept_response(id, params, &pending_response_requests.delete(id))
-            else
-              intercept_request(id, params, &block)
-            end
-          end
-          devtools.fetch.enable(patterns: [{requestStage: 'Request'}, {requestStage: 'Response'}])
+          @interceptor ||= DevTools::NetworkInterceptor.new(devtools)
+          @interceptor.intercept(&block)
         end
 
-        private
-
-        def pending_response_requests
-          @pending_response_requests ||= {}
-        end
-
-        def intercept_request(id, params, &block)
-          original = DevTools::Request.from(id, params)
-          mutable = DevTools::Request.from(id, params)
-
-          block.call(mutable) do |&continue| # rubocop:disable Performance/RedundantBlockCall
-            pending_response_requests[id] = continue
-
-            if original == mutable
-              devtools.fetch.continue_request(request_id: id)
-            else
-              devtools.fetch.continue_request(
-                request_id: id,
-                url: mutable.url,
-                method: mutable.method,
-                post_data: mutable.post_data,
-                headers: mutable.headers.map do |k, v|
-                  {name: k, value: v}
-                end
-              )
-            end
-          end
-        end
-
-        def intercept_response(id, params)
-          return devtools.fetch.continue_request(request_id: id) unless block_given?
-
-          body = fetch_response_body(id)
-          original = DevTools::Response.from(id, body, params)
-          mutable = DevTools::Response.from(id, body, params)
-          yield mutable
-
-          if original == mutable
-            devtools.fetch.continue_request(request_id: id)
-          else
-            devtools.fetch.fulfill_request(
-              request_id: id,
-              body: (Base64.strict_encode64(mutable.body) if mutable.body),
-              response_code: mutable.code,
-              response_headers: mutable.headers.map do |k, v|
-                {name: k, value: v}
-              end
-            )
-          end
-        end
-
-        def fetch_response_body(id)
-          devtools.fetch.get_response_body(request_id: id).dig('result', 'body')
-        rescue Error::WebDriverError
-          # CDP fails to get body on certain responses (301) and raises:
-          # Can only get response body on requests captured after headers received.
-        end
       end # HasNetworkInterception
     end # DriverExtensions
   end # WebDriver

data/lib/selenium/webdriver/common/driver_extensions/has_pinned_scripts.rb

@@ -62,7 +62,7 @@ module Selenium
         #
         # Unpins script making it undefined for the subsequent calls.
         #
-        # @param [DevTools::PinnedScript]
+        # @param [DevTools::PinnedScript] script
         #
 
         def unpin_script(script)

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

@@ -46,7 +46,7 @@ module Selenium
       alias_method :eql?, :==
 
       def hash
-        @id.hash ^ @bridge.hash
+        [@id, @bridge].hash
       end
 
       #
@@ -101,7 +101,7 @@ module Selenium
       # if it exists. If it does not, then the value of the attribute with the given name is returned.
       # If neither exists, null is returned.
       #
-      # The "style" attribute is converted as best can be to a text representation with a trailing semi-colon.
+      # The "style" attribute is converted as best can be to a text representation with a trailing semicolon.
       #
       # The following are deemed to be "boolean" attributes, and will return either "true" or "false":
       #

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

@@ -29,7 +29,7 @@ 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

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