selenium-webdriver 4.34.0 → 4.41.0

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

@@ -39,7 +39,13 @@ module Selenium
 
           begin
             Zip::File.open("#{file_name}.zip") do |zip|
-              zip.each { |entry| zip.extract(entry, "#{target_directory}#{file_name}") }
+              zip.each do |entry|
+                if Zipper::RUBYZIP_V3
+                  zip.extract(entry, file_name, destination_directory: target_directory)
+                else
+                  zip.extract(entry, "#{target_directory}#{file_name}")
+                end
+              end
             end
           ensure
             FileUtils.rm_f("#{file_name}.zip")

data/lib/selenium/webdriver/common/driver_extensions/has_session_events.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 DriverExtensions
+      module HasSessionEvents
+        #
+        # Fires a custom session event to the remote server event bus.
+        # This allows test code to trigger server-side utilities that subscribe to
+        # the event bus.
+        #
+        # @param [String] event_type The type of event (e.g., "test:failed", "log:collect")
+        # @param [Hash] payload Optional data to include with the event
+        # @return [Hash] Response data including success status, event type, and timestamp
+        #
+        # @example Fire a simple event
+        #   driver.fire_session_event("test:started")
+        #
+        # @example Fire an event with payload
+        #   driver.fire_session_event("test:failed", {
+        #     testName: "LoginTest",
+        #     error: "Element not found"
+        #   })
+        #
+        def fire_session_event(event_type, payload = nil)
+          @bridge.fire_session_event(event_type, payload)
+        end
+      end # HasSessionEvents
+    end # DriverExtensions
+  end # WebDriver
+end # Selenium

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

@@ -38,9 +38,9 @@ module Selenium
       ERROR_URL = 'https://www.selenium.dev/documentation/webdriver/troubleshooting/errors'
 
       URLS = {
-        NoSuchElementError: "#{ERROR_URL}#no-such-element-exception",
-        StaleElementReferenceError: "#{ERROR_URL}#stale-element-reference-exception",
-        InvalidSelectorError: "#{ERROR_URL}#invalid-selector-exception",
+        NoSuchElementError: "#{ERROR_URL}#nosuchelementexception",
+        StaleElementReferenceError: "#{ERROR_URL}#staleelementreferenceexception",
+        InvalidSelectorError: "#{ERROR_URL}#invalidselectorexception",
         NoSuchDriverError: "#{ERROR_URL}/driver_location"
       }.freeze
 
@@ -119,6 +119,13 @@ module Selenium
 
       class NoSuchWindowError < WebDriverError; end
 
+      #
+      # A command to find a devtools target could not be satisfied because
+      # the target could not be found.
+      #
+
+      class NoSuchTargetError < WebDriverError; end
+
       #
       # The element does not have a shadow root.
       #

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

@@ -27,7 +27,17 @@ module Selenium
         caps = process_options(options, service)
         url = service_url(service)
 
-        [caps, url]
+        begin
+          yield(caps, url) if block_given?
+        rescue Selenium::WebDriver::Error::WebDriverError
+          @service_manager&.stop
+          raise
+        end
+      end
+
+      def service_url(service)
+        @service_manager = service.launch
+        @service_manager.uri
       end
 
       def process_options(options, service)

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

@@ -55,9 +55,32 @@ module Selenium
         @ignored = Array(ignored)
         @allowed = Array(allowed)
         @first_warning = false
+        @level_forced = false
+        @output_forced = false
+      end
+
+      #
+      # Forces debug level and prevents it from being overridden.
+      #
+      def debug!
+        @level_forced = true
+        @logger.level = :debug
+      end
+
+      #
+      # Forces output to stderr and prevents it from being overridden.
+      #
+      def stderr!
+        @output_forced = true
+        @logger.reopen($stderr)
       end
 
       def level=(level)
+        if @level_forced
+          warn('Logger level is forced; ignoring override', id: :logger)
+          return
+        end
+
         if level == :info && @logger.level == :info
           info(':info is now the default log level, to see additional logging, set log level to :debug')
         end
@@ -71,6 +94,11 @@ module Selenium
       # @param [String] io
       #
       def output=(io)
+        if @output_forced
+          warn('Logger output is forced; ignoring override', id: :logger)
+          return
+        end
+
         @logger.reopen(io)
       end
 

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

@@ -79,6 +79,8 @@ module Selenium
       #
 
       def delete_cookie(name)
+        raise ArgumentError, 'Cookie name cannot be null or empty' if name.nil? || name.to_s.strip.empty?
+
         @bridge.delete_cookie name
       end
 

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

@@ -71,6 +71,8 @@ module Selenium
       def initialize(**opts)
         self.class.set_capabilities
 
+        opts[:web_socket_url] = opts.delete(:bidi) if opts.key?(:bidi)
+
         @options = opts
         @options[:browser_name] = self.class::BROWSER
       end
@@ -91,6 +93,14 @@ module Selenium
         @options[name] = value
       end
 
+      def enable_bidi!
+        @options[:web_socket_url] = true
+      end
+
+      def bidi?
+        !!@options[:web_socket_url]
+      end
+
       def ==(other)
         return false unless other.is_a? self.class
 
@@ -131,11 +141,20 @@ module Selenium
 
       def process_w3c_options(options)
         w3c_options = options.select { |key, val| w3c?(key) && !val.nil? }
-        w3c_options[:unhandled_prompt_behavior] &&= w3c_options[:unhandled_prompt_behavior]&.to_s&.tr('_', ' ')
+        w3c_options[:unhandled_prompt_behavior] &&=
+          process_unhandled_prompt_behavior_value(w3c_options[:unhandled_prompt_behavior])
         options.delete_if { |key, _val| w3c?(key) }
         w3c_options
       end
 
+      def process_unhandled_prompt_behavior_value(value)
+        if value.is_a?(Hash)
+          value.transform_values { |v| process_unhandled_prompt_behavior_value(v) }
+        else
+          value&.to_s&.tr('_', ' ')
+        end
+      end
+
       def process_browser_options(_browser_options)
         nil
       end

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

@@ -51,9 +51,7 @@ module Selenium
       end
 
       def ci
-        if ENV['TRAVIS']
-          :travis
-        elsif ENV['JENKINS']
+        if ENV['JENKINS']
           :jenkins
         elsif ENV['APPVEYOR']
           :appveyor

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

@@ -104,6 +104,12 @@ module Selenium
       def env_path
         ENV.fetch(self.class::DRIVER_PATH_ENV_KEY, nil)
       end
+
+      private
+
+      def warn_driver_log_override
+        WebDriver.logger.warn('SE_DEBUG is set; overriding user-specified driver logging settings', id: :se_debug)
+      end
     end # Service
   end # WebDriver
 end # Selenium

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

@@ -80,7 +80,13 @@ module Selenium
       def build_process(*command)
         WebDriver.logger.debug("Executing Process #{command}", id: :driver_service)
         @process = ChildProcess.build(*command)
-        @io ||= WebDriver.logger.io if WebDriver.logger.debug?
+        if ENV.key?('SE_DEBUG')
+          if @io && @io != WebDriver.logger.io
+            WebDriver.logger.warn('SE_DEBUG is set; overriding user-specified driver log output to use stderr',
+                                  id: :se_debug)
+          end
+          @io = WebDriver.logger.io
+        end
         @process.io = @io if @io
 
         @process
@@ -127,10 +133,36 @@ module Selenium
       end
 
       def connect_until_stable
-        socket_poller = SocketPoller.new @host, @port, START_TIMEOUT
-        return if socket_poller.connected?
+        deadline = current_time + START_TIMEOUT
+
+        loop do
+          error = check_connection_error
+          return unless error
+
+          raise Error::WebDriverError, "#{cannot_connect_error_text}: #{error}" if current_time > deadline
+
+          sleep 0.1
+        end
+      end
+
+      def check_connection_error
+        response = Net::HTTP.start(@host, @port, open_timeout: 0.5, read_timeout: 1) do |http|
+          http.get('/status', {'Connection' => 'close'})
+        end
+
+        return "status returned #{response.code}\n#{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+        status = JSON.parse(response.body)
+        ready = status['ready'] || status.dig('value', 'ready')
+        "driver not ready: #{response.body}" unless ready
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE, Errno::ETIMEDOUT,
+             Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH, Net::OpenTimeout, Net::ReadTimeout,
+             EOFError, SocketError, Net::HTTPBadResponse, JSON::ParserError => e
+        "#{e.class}: #{e.message}"
+      end
 
-        raise Error::WebDriverError, cannot_connect_error_text
+      def current_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
 
       def cannot_connect_error_text

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

@@ -93,7 +93,7 @@ module Selenium
           true
         rescue *NOT_CONNECTED_ERRORS
           sock&.close
-          WebDriver.logger.debug("polling for socket on #{[@host, @port].inspect}", id: :driver_service)
+          WebDriver.logger.debug("polling for socket on #{[@host, @port].inspect}", id: :socket_poller)
           false
         end
       end

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

@@ -29,7 +29,7 @@ module Selenium
       # @param [Hash] opts Options for this instance
       # @option opts [Numeric] :timeout (5) Seconds to wait before timing out.
       # @option opts [Numeric] :interval (0.2) Seconds to sleep between polls.
-      # @option opts [String] :message Exception mesage if timed out.
+      # @option opts [String] :message Exception message if timed out.
       # @option opts [Array, Exception] :ignore Exceptions to ignore while polling (default: Error::NoSuchElementError)
       #
 
@@ -37,7 +37,8 @@ module Selenium
         @timeout  = opts.fetch(:timeout, DEFAULT_TIMEOUT)
         @interval = opts.fetch(:interval, DEFAULT_INTERVAL)
         @message  = opts[:message]
-        @ignored  = Array(opts[:ignore] || Error::NoSuchElementError)
+        @message_provider = opts[:message_provider]
+        @ignored = Array(opts[:ignore] || Error::NoSuchElementError)
       end
 
       #
@@ -64,6 +65,8 @@ module Selenium
 
         msg = if @message
                 @message.dup
+              elsif @message_provider
+                @message_provider.call
               else
                 "timed out after #{@timeout} seconds"
               end

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

@@ -24,7 +24,10 @@ module Selenium
     class WebSocketConnection
       CONNECTION_ERRORS = [
         Errno::ECONNRESET, # connection is aborted (browser process was killed)
-        Errno::EPIPE # broken pipe (browser process was killed)
+        Errno::EPIPE, # broken pipe (browser process was killed)
+        Errno::EBADF, # file descriptor already closed (double-close or GC)
+        IOError, # Ruby socket read/write after close
+        EOFError # socket reached EOF after remote closed cleanly
       ].freeze
 
       RESPONSE_WAIT_TIMEOUT = 30
@@ -35,6 +38,11 @@ module Selenium
       def initialize(url:)
         @callback_threads = ThreadGroup.new
 
+        @callbacks_mtx = Mutex.new
+        @messages_mtx = Mutex.new
+        @closing_mtx = Mutex.new
+
+        @closing = false
         @session_id = nil
         @url = url
 
@@ -43,9 +51,26 @@ module Selenium
       end
 
       def close
-        @callback_threads.list.each(&:exit)
-        @socket_thread.exit
-        socket.close
+        @closing_mtx.synchronize do
+          return if @closing
+
+          @closing = true
+        end
+
+        begin
+          socket.close
+        rescue *CONNECTION_ERRORS => e
+          WebDriver.logger.debug "WebSocket listener closed: #{e.class}: #{e.message}", id: :ws
+          # already closed
+        end
+
+        # Let threads unwind instead of calling exit
+        @socket_thread&.join(0.5)
+        @callback_threads.list.each do |thread|
+          thread.join(0.5)
+        rescue StandardError => e
+          WebDriver.logger.debug "Failed to join thread during close: #{e.class}: #{e.message}", id: :ws
+        end
       end
 
       def callbacks
@@ -53,62 +78,73 @@ module Selenium
       end
 
       def add_callback(event, &block)
-        callbacks[event] << block
-        block.object_id
+        @callbacks_mtx.synchronize do
+          callbacks[event] << block
+          block.object_id
+        end
       end
 
       def remove_callback(event, id)
-        return if callbacks[event].reject! { |callback| callback.object_id == id }
+        @callbacks_mtx.synchronize do
+          return if @closing
+
+          callbacks_for_event = callbacks[event]
+          return if callbacks_for_event.reject! { |cb| cb.object_id == id }
 
-        ids = callbacks[event]&.map(&:object_id)
-        raise Error::WebDriverError, "Callback with ID #{id} does not exist for event #{event}: #{ids}"
+          ids = callbacks_for_event.map(&:object_id)
+          raise Error::WebDriverError, "Callback with ID #{id} does not exist for event #{event}: #{ids}"
+        end
       end
 
       def send_cmd(**payload)
         id = next_id
         data = payload.merge(id: id)
-        WebDriver.logger.debug "WebSocket -> #{data}"[...MAX_LOG_MESSAGE_SIZE], id: :bidi
+        WebDriver.logger.debug "WebSocket -> #{data}"[...MAX_LOG_MESSAGE_SIZE], id: :ws
         data = JSON.generate(data)
         out_frame = WebSocket::Frame::Outgoing::Client.new(version: ws.version, data: data, type: 'text')
-        socket.write(out_frame.to_s)
 
-        wait.until { messages.delete(id) }
+        begin
+          socket.write(out_frame.to_s)
+        rescue *CONNECTION_ERRORS => e
+          raise e, "WebSocket is closed (#{e.class}: #{e.message})"
+        end
+
+        wait.until { @messages_mtx.synchronize { messages.delete(id) } }
       end
 
       private
 
-      # We should be thread-safe to use the hash without synchronization
-      # because its keys are WebSocket message identifiers and they should be
-      # unique within a devtools session.
       def messages
         @messages ||= {}
       end
 
       def process_handshake
         socket.print(ws.to_s)
-        ws << socket.readpartial(1024)
+        ws << socket.readpartial(1024) until ws.finished?
       end
 
       def attach_socket_listener
         Thread.new do
-          Thread.current.abort_on_exception = true
           Thread.current.report_on_exception = false
 
-          until socket.eof?
+          loop do
+            break if @closing
+
             incoming_frame << socket.readpartial(1024)
 
             while (frame = incoming_frame.next)
+              break if @closing
+
               message = process_frame(frame)
               next unless message['method']
 
-              params = message['params']
-              callbacks[message['method']].each do |callback|
-                @callback_threads.add(callback_thread(params, &callback))
+              @messages_mtx.synchronize { callbacks[message['method']].dup }.each do |callback|
+                @callback_threads.add(callback_thread(message['params'], &callback))
               end
             end
           end
-        rescue *CONNECTION_ERRORS
-          Thread.stop
+        rescue *CONNECTION_ERRORS, WebSocket::Error => e
+          WebDriver.logger.debug "WebSocket listener closed: #{e.class}: #{e.message}", id: :ws
         end
       end
 
@@ -122,27 +158,27 @@ module Selenium
         # Firefox will periodically fail on unparsable empty frame
         return {} if message.empty?
 
-        message = JSON.parse(message)
-        messages[message['id']] = message
-        WebDriver.logger.debug "WebSocket <- #{message}"[...MAX_LOG_MESSAGE_SIZE], id: :bidi
+        msg = JSON.parse(message)
+        @messages_mtx.synchronize { messages[msg['id']] = msg if msg.key?('id') }
 
-        message
+        WebDriver.logger.debug "WebSocket <- #{msg}"[...MAX_LOG_MESSAGE_SIZE], id: :ws
+        msg
       end
 
       def callback_thread(params)
         Thread.new do
-          Thread.current.abort_on_exception = true
-
-          # We might end up blocked forever when we have an error in event.
-          # For example, if network interception event raises error,
-          # the browser will keep waiting for the request to be proceeded
-          # before returning back to the original thread. In this case,
-          # we should at least print the error.
-          Thread.current.report_on_exception = true
+          Thread.current.abort_on_exception = false
+          Thread.current.report_on_exception = false
+          next if @closing
 
           yield params
-        rescue Error::WebDriverError, *CONNECTION_ERRORS
-          Thread.stop
+        rescue Error::WebDriverError, *CONNECTION_ERRORS => e
+          WebDriver.logger.debug "Callback aborted: #{e.class}: #{e.message}", id: :ws
+        rescue StandardError => e
+          next if @closing
+
+          bt = Array(e.backtrace).first(5).join("\n")
+          WebDriver.logger.error "Callback error: #{e.class}: #{e.message}\n#{bt}", id: :ws
         end
       end
 

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

@@ -18,6 +18,7 @@
 # under the License.
 
 require 'zip'
+require 'zip/version' # Not required automatically
 require 'tempfile'
 require 'find'
 require 'base64'
@@ -30,6 +31,7 @@ module Selenium
 
     module Zipper
       EXTENSIONS = %w[.zip .xpi].freeze
+      RUBYZIP_V3 = Zip::VERSION >= '3.0.0'
 
       class << self
         def unzip(path)
@@ -42,7 +44,11 @@ module Selenium
               dirname = File.dirname(to)
 
               FileUtils.mkdir_p dirname
-              zip.extract(entry, to)
+              if RUBYZIP_V3
+                zip.extract(entry, entry.name, destination_directory: destination)
+              else
+                zip.extract(entry, to)
+              end
             end
           end
 
@@ -75,7 +81,11 @@ module Selenium
           # Don't use Tempfile since it lacks rb_file_s_rename permission on Windows.
           Dir.mktmpdir do |tmp_dir|
             zip_path = File.join(tmp_dir, 'webdriver-zip')
-            Zip::File.open(zip_path, Zip::File::CREATE, &blk)
+            if RUBYZIP_V3
+              Zip::File.open(zip_path, create: true, &blk)
+            else
+              Zip::File.open(zip_path, Zip::File::CREATE, &blk)
+            end
           end
         end
 

data/lib/selenium/webdriver/common.rb

@@ -78,6 +78,7 @@ 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'
 require 'selenium/webdriver/common/driver_extensions/has_authentication'
 require 'selenium/webdriver/common/driver_extensions/has_logs'
 require 'selenium/webdriver/common/driver_extensions/has_log_events'

data/lib/selenium/webdriver/devtools.rb

@@ -84,7 +84,7 @@ module Selenium
       def start_session(target_type:)
         targets = target.get_targets.dig('result', 'targetInfos')
         found_target = targets.find { |target| target['type'] == target_type }
-        raise Error::WebDriverError, "Target type '#{target_type}' not found" unless found_target
+        raise Error::NoSuchTargetError, "Target type '#{target_type}' not found" unless found_target
 
         session = target.attach_to_target(target_id: found_target['targetId'], flatten: true)
         @session_id = session.dig('result', 'sessionId')

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

@@ -31,8 +31,9 @@ module Selenium
         include LocalDriver
 
         def initialize(options: nil, service: nil, url: nil, **)
-          caps, url = initialize_local_driver(options, service, url)
-          super(caps: caps, url: url, **)
+          initialize_local_driver(options, service, url) do |caps, driver_url|
+            super(caps: caps, url: driver_url, **)
+          end
         end
 
         def browser

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

@@ -25,6 +25,17 @@ module Selenium
         EXECUTABLE = 'msedgedriver'
         SHUTDOWN_SUPPORTED = true
         DRIVER_PATH_ENV_KEY = 'SE_EDGEDRIVER'
+
+        def initialize(args: nil, **)
+          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
+
+          super
+        end
+
         def log
           return @log unless @log.is_a? String
 

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

@@ -37,8 +37,9 @@ module Selenium
         include LocalDriver
 
         def initialize(options: nil, service: nil, url: nil, **)
-          caps, url = initialize_local_driver(options, service, url)
-          super(caps: caps, url: url, **)
+          initialize_local_driver(options, service, url) do |caps, driver_url|
+            super(caps: caps, url: driver_url, **)
+          end
         end
 
         def browser

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

@@ -26,14 +26,33 @@ module Selenium
         SHUTDOWN_SUPPORTED = false
         DRIVER_PATH_ENV_KEY = 'SE_GECKODRIVER'
 
-        def initialize(path: nil, port: nil, log: nil, args: nil)
-          args ||= []
+        def initialize(args: nil, **)
+          args = Array(args.dup)
           unless args.any? { |arg| arg.include?('--connect-existing') || arg.include?('--websocket-port') }
             args << '--websocket-port'
             args << '0'
           end
+
+          if ENV.key?('SE_DEBUG')
+            remove_log_args(args)
+            args << '-v'
+          end
+
           super
         end
+
+        private
+
+        def remove_log_args(args)
+          if (index = args.index('--log'))
+            args.delete_at(index) # delete '--log'
+            args.delete_at(index) if args[index] && !args[index].start_with?('-') # delete value if present
+            warn_driver_log_override
+          elsif (index = args.index { |arg| arg.start_with?('--log=') })
+            args.delete_at(index)
+            warn_driver_log_override
+          end
+        end
       end # Service
     end # Firefox
   end # WebDriver