selenium-webdriver 4.45.0 → 4.47.0

data/lib/selenium/webdriver/bidi/support/check_generated.rb

@@ -0,0 +1,63 @@
+# 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 'json'
+require_relative 'bidi_generate'
+
+module BiDiGenerate
+  # Verifies the checked-in protocol .rb match what the generator would produce from the
+  # current schema — catching a hand-edit or a forgotten regeneration. Re-renders each module
+  # in memory (no file writes) and compares. The .rbs are covered by Steep.
+  def self.check!(schema_rootpath)
+    schema = Schema.new(JSON.parse(File.read(schema_path(schema_rootpath))))
+    protocol_dir = File.expand_path('../protocol', __dir__)
+    template = File.join(__dir__, 'templates', 'module.rb.erb')
+
+    stale = build_ir(schema).filter_map do |mod|
+      path = File.join(protocol_dir, "#{mod.filename}.rb")
+      "#{mod.filename}.rb" unless File.exist?(path) && File.read(path) == render(mod, template)
+    end
+    stale << 'error_code.rb' unless error_module_current?(schema, protocol_dir)
+    return if stale.empty?
+
+    warn "Generated BiDi protocol code is stale or hand-edited: #{stale.sort.join(', ')}"
+    warn 'Regenerate with: bazel run //rb/lib/selenium/webdriver:bidi-generate'
+    exit 1
+  end
+
+  # Whether the checked-in protocol/error_code.rb matches what the generator would render now.
+  def self.error_module_current?(schema, protocol_dir)
+    mod = ErrorModule.new(filename: 'error_code', codes: error_code_map(schema))
+    path = File.join(protocol_dir, 'error_code.rb')
+    File.exist?(path) && File.read(path) == render(mod, File.join(__dir__, 'templates', 'error_code.rb.erb'))
+  end
+
+  # $(rootpath) is relative to the runfiles root; __dir__ anchors us there so it resolves the
+  # same way locally and on RBE (an execpath would not). This file lives at
+  # rb/lib/selenium/webdriver/bidi/support, so expand six levels up to the root — File.expand_path
+  # is separator-agnostic, unlike stripping a "/"-spelled suffix (which would miss on Windows).
+  # The cwd-relative rootpath fallback matches how spec_support's `rlocation` resolves.
+  def self.schema_path(rootpath)
+    runfiles_root = File.expand_path('../../../../../..', __dir__)
+    [File.join(runfiles_root, rootpath), rootpath].find { |p| File.exist?(p) } ||
+      raise("BiDi schema not found (looked for #{rootpath})")
+  end
+end
+
+BiDiGenerate.check!(ARGV.fetch(0)) if $PROGRAM_NAME == __FILE__

data/lib/selenium/webdriver/bidi/transport.rb

@@ -0,0 +1,57 @@
+# 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
+    class BiDi
+      # The seam between the generated Protocol layer and the websocket: serializes a
+      # command's params, sends it, and parses the reply into its declared type.
+      #
+      # @api private
+      class Transport
+        # The websocket the transport sends over. Exposed so a domain can build a sibling
+        # domain (e.g. a vendor variant) over the same connection without Transport ever
+        # becoming a public constructor argument.
+        attr_reader :connection
+
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def execute(cmd:, params: nil, result: nil)
+          reply = @connection.send_cmd(method: cmd, params: serialize(params))
+          raise error_for(reply) if reply['error']
+
+          value = reply['result']
+          result ? result.from_json(value) : value
+        end
+
+        private
+
+        def serialize(params)
+          params&.as_json || {}
+        end
+
+        def error_for(reply)
+          Protocol::ErrorCode.for(reply['error']).new("#{reply['message']}\n#{reply['stacktrace']}")
+        end
+      end # Transport
+    end # BiDi
+  end # WebDriver
+end # Selenium

data/lib/selenium/webdriver/bidi.rb

@@ -35,6 +35,9 @@ module Selenium
         @ws = WebSocketConnection.new(url: url)
       end
 
+      # @api private
+      attr_reader :ws
+
       def close
         @ws.close
       end

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

@@ -30,9 +30,9 @@ module Selenium
       class Driver < Chromium::Driver
         include LocalDriver
 
-        def initialize(options: nil, service: nil, url: nil, **)
-          initialize_local_driver(options, service, url) do |caps, driver_url|
-            super(caps: caps, url: driver_url, **)
+        def initialize(options: nil, service: nil, url: nil, http_client: nil, client_config: nil, **)
+          initialize_local_driver(options, service, url, http_client, client_config) do |caps, client|
+            super(caps: caps, http_client: client, **)
           end
         end
 

data/lib/selenium/webdriver/chrome/service.rb

@@ -27,8 +27,11 @@ module Selenium
         DRIVER_PATH_ENV_KEY = 'SE_CHROMEDRIVER'
 
         def initialize(args: nil, **)
+          args = Array(args.dup)
+          # skip when CHROME_LOG_FILE is set; --enable-chrome-logs would override the user's log file
+          args << '--enable-chrome-logs' unless ENV.key?('CHROME_LOG_FILE') || args.include?('--enable-chrome-logs')
+
           if ENV.key?('SE_DEBUG')
-            args = Array(args.dup)
             warn_driver_log_override if args.reject! { |arg| arg.include?('log-level') || arg.include?('silent') }
             args << '--verbose'
           end

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

@@ -27,7 +27,6 @@ module Selenium
 
       class Driver < WebDriver::Driver
         EXTENSIONS = [DriverExtensions::HasCDP,
-                      DriverExtensions::HasBiDi,
                       DriverExtensions::HasCasting,
                       DriverExtensions::HasFedCmDialog,
                       DriverExtensions::HasNetworkConditions,

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

@@ -86,6 +86,7 @@ module Selenium
           @logging_prefs = options.delete(:logging_prefs) || {}
           @encoded_extensions = @options.delete(:encoded_extensions) || []
           @extensions = []
+          @vendor_options = {}
           @options.delete(:extensions).each { |ext| validate_extension(ext) }
         end
 
@@ -184,6 +185,24 @@ module Selenium
           @options[:emulation] = opts
         end
 
+        #
+        # Add a Chromium-specific capability nested in the browser options object
+        # (e.g. `goog:chromeOptions` / `ms:edgeOptions`) that is not yet exposed
+        # through a dedicated method. This is the escape hatch for legitimate
+        # vendor capabilities the bindings do not model.
+        #
+        # @example Set an option not handled by other methods
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_chromium_option('unhandledCapability', 'value')
+        #
+        # @param [String, Symbol] name Name of the capability, as expected by the driver
+        # @param [Object] value Value of the capability
+        #
+
+        def add_chromium_option(name, value)
+          @vendor_options[name.to_s] = value
+        end
+
         #
         # Enables mobile browser use on Android.
         #
@@ -209,6 +228,7 @@ module Selenium
           enable_logging(browser_options) unless @logging_prefs.empty?
 
           options = browser_options[self.class::KEY]
+          options.merge!(@vendor_options)
           options['binary'] ||= binary_path if binary_path
 
           if @profile

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

@@ -0,0 +1,97 @@
+# 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 'uri'
+
+module Selenium
+  module WebDriver
+    #
+    # Configuration for HTTP clients.
+    #
+
+    class ClientConfig
+      class << self
+        attr_accessor :default_extra_headers
+        attr_writer :default_user_agent
+
+        def default_user_agent
+          @default_user_agent ||= "selenium/#{WebDriver::VERSION} (ruby #{Platform.os})"
+        end
+      end
+
+      attr_accessor :open_timeout, :read_timeout, :max_redirects, :proxy
+      attr_writer :extra_headers, :user_agent
+      attr_reader :server_url
+
+      #
+      # @param [Numeric] open_timeout Seconds to wait for the connection to open.
+      # @param [Numeric] read_timeout Seconds to wait for a response.
+      # @param [Integer] max_redirects Maximum number of redirects to follow.
+      # @param [Proxy] proxy Proxy to use for the connection.
+      # @param [Hash] extra_headers Additional headers to send with each request.
+      # @param [String] user_agent Value to send as the User-Agent header.
+      # @param [String, URI] server_url URL of the server to connect to.
+      #
+      def initialize(open_timeout: 60,
+                     read_timeout: 120,
+                     max_redirects: 20,
+                     proxy: nil,
+                     extra_headers: nil,
+                     user_agent: nil,
+                     server_url: nil)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @max_redirects = max_redirects
+        @proxy = proxy || proxy_from_environment
+        @extra_headers = extra_headers
+        @user_agent = user_agent
+        self.server_url = server_url
+      end
+
+      def user_agent
+        @user_agent || self.class.default_user_agent
+      end
+
+      def extra_headers
+        @extra_headers || self.class.default_extra_headers
+      end
+
+      def server_url=(url)
+        if url.nil?
+          @server_url = nil
+        else
+          url = url.to_s
+          url += '/' unless url.end_with?('/')
+          @server_url = URI.parse(url)
+        end
+      end
+
+      private
+
+      def proxy_from_environment
+        proxy = ENV.fetch('http_proxy', nil) || ENV.fetch('HTTP_PROXY', nil)
+        return unless proxy
+
+        no_proxy = ENV.fetch('no_proxy', nil) || ENV.fetch('NO_PROXY', nil)
+        proxy = "http://#{proxy}" unless proxy.match?(%r{\Ahttps?://})
+        Proxy.new(http: proxy, no_proxy: no_proxy)
+      end
+    end
+  end
+end

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

@@ -90,6 +90,17 @@ module Selenium
         @bridge.status
       end
 
+      #
+      # Returns the WebDriver BiDi connection for this session.
+      #
+      # @return [BiDi]
+      # @raise [Error::WebDriverError] if BiDi was not enabled for this session
+      #
+
+      def bidi
+        @bridge.bidi
+      end
+
       #
       # @return [Navigation]
       # @see Navigation
@@ -319,9 +330,9 @@ module Selenium
 
       attr_reader :bridge
 
-      def create_bridge(caps:, url:, http_client: nil)
+      def create_bridge(caps:, http_client:)
         klass = caps['webSocketUrl'] ? Remote::BiDiBridge : Remote::Bridge
-        klass.new(http_client: http_client, url: url).tap do |bridge|
+        klass.new(http_client: http_client).tap do |bridge|
           bridge.create_session(caps)
         end
       end

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

@@ -57,13 +57,6 @@ module Selenium
         #
 
         def on_log_event(kind, &block)
-          if browser == :firefox
-            WebDriver.logger.deprecate(
-              'Driver#on_log_event on Firefox',
-              'the script.add_console_message_handler or the script.add_javascript_error_handler methods',
-              id: :on_log_event
-            )
-          end
           raise Error::WebDriverError, "Don't know how to handle #{kind} events" unless KINDS.include?(kind)
 
           enabled = log_listeners[kind].any?

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

@@ -60,13 +60,6 @@ module Selenium
         #
 
         def intercept(&block)
-          if browser == :firefox
-            WebDriver.logger.deprecate(
-              'Driver#intercept on Firefox',
-              'the new bidi.network.add_intercept method',
-              id: :intercept
-            )
-          end
           @interceptor ||= DevTools::NetworkInterceptor.new(devtools)
           @interceptor.intercept(&block)
         end

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

@@ -52,8 +52,8 @@ module Selenium
           path = @service.executable_path || env_path || class_path
           path ? paths_from_service(path) : paths_from_manager
         rescue StandardError => e
-          WebDriver.logger.error("Exception occurred: #{e.message}")
-          WebDriver.logger.error("Backtrace:\n\t#{e.backtrace&.join("\n\t")}")
+          WebDriver.logger.error("Exception occurred: #{e.message}", id: :driver_finder)
+          WebDriver.logger.error("Backtrace:\n\t#{e.backtrace&.join("\n\t")}", id: :driver_finder)
           raise Error::NoSuchDriverError, "Unable to obtain #{@service.class::EXECUTABLE}"
         end
       end
@@ -69,7 +69,8 @@ module Selenium
 
       def paths_from_service(path)
         exe = @service.class::EXECUTABLE
-        WebDriver.logger.debug("Skipping Selenium Manager; path to #{exe} specified in service class: #{path}")
+        WebDriver.logger.debug("Skipping Selenium Manager; path to #{exe} specified in service class: #{path}",
+                               id: :driver_finder)
         Platform.assert_executable(path)
         {driver_path: path}
       end

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

@@ -20,15 +20,16 @@
 module Selenium
   module WebDriver
     module LocalDriver
-      def initialize_local_driver(options, service, url)
-        raise ArgumentError, "Can't initialize #{self.class} with :url" if url
+      def initialize_local_driver(options, service, url, http_client, client_config)
+        assert_local_arguments(url, http_client, client_config)
 
         service ||= Service.send(browser)
         caps = process_options(options, service)
-        url = service_url(service)
+        http_client ||= Remote::Http::Default.new(client_config: client_config)
+        http_client.server_url = service_url(service)
 
         begin
-          yield(caps, url) if block_given?
+          yield(caps, http_client) if block_given?
         rescue Selenium::WebDriver::Error::WebDriverError
           @service_manager&.stop
           raise
@@ -54,6 +55,16 @@ module Selenium
         options.browser_version = nil if options.respond_to?(:binary) && options.binary
         options.as_json
       end
+
+      private
+
+      def assert_local_arguments(url, http_client, client_config)
+        if url || client_config&.server_url
+          raise ArgumentError, "Can't set the server URL for #{self.class}; the service provides it"
+        elsif http_client && client_config
+          raise ArgumentError, 'Cannot use both :http_client and :client_config'
+        end
+      end
     end
   end
 end

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

@@ -75,6 +75,8 @@ module Selenium
 
         @options = opts
         @options[:browser_name] = self.class::BROWSER
+
+        enable_bidi! if @options[:web_socket_url]
       end
 
       #
@@ -93,6 +95,12 @@ module Selenium
         @options[name] = value
       end
 
+      #
+      # Enables WebDriver BiDi by requesting the W3C webSocketUrl capability.
+      #
+      # @return [Boolean]
+      #
+
       def enable_bidi!
         @options[:web_socket_url] = true
       end
@@ -130,11 +138,23 @@ module Selenium
         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))
+        generate_as_json(merge_browser_options(w3c_options, browser_options))
       end
 
       private
 
+      # Preserve a hand-built vendor options hash (e.g. passed through #add_option) by merging it
+      # with the binding's own, rather than letting one silently overwrite the other.
+      def merge_browser_options(w3c_options, browser_options)
+        w3c_options.merge(browser_options) do |_key, w3c_value, browser_value|
+          if w3c_value.is_a?(Hash) && browser_value.is_a?(Hash)
+            browser_value.merge(w3c_value)
+          else
+            browser_value
+          end
+        end
+      end
+
       def w3c?(key)
         W3C_OPTIONS.include?(key) || key.to_s.include?(':')
       end

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

@@ -29,7 +29,6 @@ module Selenium
       }.freeze
 
       ALLOWED = {type: 'proxyType',
-                 ftp: 'ftpProxy',
                  http: 'httpProxy',
                  no_proxy: 'noProxy',
                  pac: 'proxyAutoconfigUrl',
@@ -76,12 +75,6 @@ module Selenium
       end
       alias eql? ==
 
-      def ftp=(value)
-        WebDriver.logger.deprecate('FTP proxy support', nil, id: :ftp_proxy)
-        self.type = :manual
-        @ftp = value
-      end
-
       def http=(value)
         self.type = :manual
         @http = value
@@ -143,9 +136,8 @@ module Selenium
       def as_json(*)
         json_result = {
           'proxyType' => TYPES[type].downcase,
-          'ftpProxy' => ftp,
           'httpProxy' => http,
-          'noProxy' => no_proxy.is_a?(String) ? no_proxy.split(', ') : no_proxy,
+          'noProxy' => no_proxy.is_a?(String) ? no_proxy.split(',').map(&:strip).reject(&:empty?) : no_proxy,
           'proxyAutoconfigUrl' => pac,
           'sslProxy' => ssl,
           'autodetect' => auto_detect,

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

@@ -50,7 +50,8 @@ module Selenium
         def binary
           @binary ||= begin
             if (location = ENV.fetch('SE_MANAGER_PATH', nil))
-              WebDriver.logger.debug("Selenium Manager set by ENV['SE_MANAGER_PATH']: #{location}")
+              WebDriver.logger.debug("Selenium Manager set by ENV['SE_MANAGER_PATH']: #{location}",
+                                     id: :selenium_manager)
             end
             location ||= platform_location
 

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

@@ -36,7 +36,7 @@ module Selenium
                                 'It should end with .png extension',
                                 id: :screenshot
         end
-        WebDriver.logger.debug("Saving screenshot to #{Dir.pwd}/#{png_path}")
+        WebDriver.logger.debug("Saving screenshot to #{Dir.pwd}/#{png_path}", id: :screenshot)
         File.open(png_path, 'wb') { |f| f << screenshot_as(:png, full_page: full_page) }
       end
 

data/lib/selenium/webdriver/common.rb

@@ -18,6 +18,7 @@
 # under the License.
 
 require 'selenium/webdriver/common/error'
+require 'selenium/webdriver/common/client_config'
 require 'selenium/webdriver/common/local_driver'
 require 'selenium/webdriver/common/driver_finder'
 require 'selenium/webdriver/common/platform'
@@ -75,7 +76,6 @@ require 'selenium/webdriver/common/driver_extensions/prints_page'
 require 'selenium/webdriver/common/driver_extensions/uploads_files'
 require 'selenium/webdriver/common/driver_extensions/full_page_screenshot'
 require 'selenium/webdriver/common/driver_extensions/has_addons'
-require 'selenium/webdriver/common/driver_extensions/has_bidi'
 require 'selenium/webdriver/common/driver_extensions/has_devtools'
 require 'selenium/webdriver/common/driver_extensions/has_file_downloads'
 require 'selenium/webdriver/common/driver_extensions/has_session_events'

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

@@ -30,9 +30,9 @@ module Selenium
       class Driver < Chromium::Driver
         include LocalDriver
 
-        def initialize(options: nil, service: nil, url: nil, **)
-          initialize_local_driver(options, service, url) do |caps, driver_url|
-            super(caps: caps, url: driver_url, **)
+        def initialize(options: nil, service: nil, url: nil, http_client: nil, client_config: nil, **)
+          initialize_local_driver(options, service, url, http_client, client_config) do |caps, client|
+            super(caps: caps, http_client: client, **)
           end
         end
 

data/lib/selenium/webdriver/edge/service.rb

@@ -27,8 +27,11 @@ module Selenium
         DRIVER_PATH_ENV_KEY = 'SE_EDGEDRIVER'
 
         def initialize(args: nil, **)
+          args = Array(args.dup)
+          # yes, it is --enable-chrome-logs, even on msedgedriver; skip when CHROME_LOG_FILE is set
+          args << '--enable-chrome-logs' unless ENV.key?('CHROME_LOG_FILE') || args.include?('--enable-chrome-logs')
+
           if ENV.key?('SE_DEBUG')
-            args = Array(args.dup)
             warn_driver_log_override if args.reject! { |arg| arg.include?('log-level') || arg.include?('silent') }
             args << '--verbose'
           end

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

@@ -29,16 +29,13 @@ module Selenium
         EXTENSIONS = [DriverExtensions::HasAddons,
                       DriverExtensions::FullPageScreenshot,
                       DriverExtensions::HasContext,
-                      DriverExtensions::HasBiDi,
-                      DriverExtensions::HasLogEvents,
-                      DriverExtensions::HasNetworkInterception,
                       DriverExtensions::PrintsPage].freeze
 
         include LocalDriver
 
-        def initialize(options: nil, service: nil, url: nil, **)
-          initialize_local_driver(options, service, url) do |caps, driver_url|
-            super(caps: caps, url: driver_url, **)
+        def initialize(options: nil, service: nil, url: nil, http_client: nil, client_config: nil, **)
+          initialize_local_driver(options, service, url, http_client, client_config) do |caps, client|
+            super(caps: caps, http_client: client, **)
           end
         end
 

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

@@ -69,6 +69,7 @@ module Selenium
           @options[:prefs]['remote.active-protocols'] = 1
           @options[:env] ||= {}
           @options[:log] ||= {level: log_level} if log_level
+          @vendor_options = {}
 
           process_profile(@options.delete(:profile))
         end
@@ -102,6 +103,23 @@ module Selenium
           @options[:prefs][name] = value
         end
 
+        #
+        # Add a Firefox-specific capability nested in the `moz:firefoxOptions`
+        # object that is not yet exposed through a dedicated method. This is the
+        # escape hatch for legitimate vendor capabilities the bindings do not model.
+        #
+        # @example Set an option not handled by other methods
+        #   options = Selenium::WebDriver::Firefox::Options.new
+        #   options.add_firefox_option('unhandledCapability', 'value')
+        #
+        # @param [String, Symbol] name Name of the capability, as expected by geckodriver
+        # @param [Object] value Value of the capability
+        #
+
+        def add_firefox_option(name, value)
+          @vendor_options[name.to_s] = value
+        end
+
         #
         # Sets Firefox profile.
         #
@@ -153,6 +171,7 @@ module Selenium
         def process_browser_options(browser_options)
           browser_options['moz:debuggerAddress'] = true if @debugger_address
           options = browser_options[KEY]
+          options.merge!(@vendor_options)
           options['binary'] ||= Firefox.path if Firefox.path
           options['profile'] = @profile if @profile
         end