selenium-webdriver 4.46.0 → 4.47.0

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

@@ -25,21 +25,29 @@ module BiDiGenerate
   # 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)
-    modules = build_ir(Schema.new(JSON.parse(File.read(schema_path(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 = modules.reject do |mod|
+    stale = build_ir(schema).filter_map do |mod|
       path = File.join(protocol_dir, "#{mod.filename}.rb")
-      File.exist?(path) && File.read(path) == render(mod, template)
+      "#{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.map { |m| "#{m.filename}.rb" }.sort.join(', ')}"
+    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

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

@@ -25,13 +25,18 @@ module Selenium
       #
       # @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::WebDriverError, error_message(reply) if reply['error']
+          raise error_for(reply) if reply['error']
 
           value = reply['result']
           result ? result.from_json(value) : value
@@ -43,8 +48,8 @@ module Selenium
           params&.as_json || {}
         end
 
-        def error_message(reply)
-          "#{reply['error']}: #{reply['message']}\n#{reply['stacktrace']}"
+        def error_for(reply)
+          Protocol::ErrorCode.for(reply['error']).new("#{reply['message']}\n#{reply['stacktrace']}")
         end
       end # Transport
     end # BiDi

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/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

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/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,7 +136,6 @@ module Selenium
       def as_json(*)
         json_result = {
           'proxyType' => TYPES[type].downcase,
-          'ftpProxy' => ftp,
           'httpProxy' => http,
           'noProxy' => no_proxy.is_a?(String) ? no_proxy.split(',').map(&:strip).reject(&:empty?) : no_proxy,
           'proxyAutoconfigUrl' => pac,

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

@@ -76,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/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,9 +29,6 @@ module Selenium
         EXTENSIONS = [DriverExtensions::HasAddons,
                       DriverExtensions::FullPageScreenshot,
                       DriverExtensions::HasContext,
-                      DriverExtensions::HasBiDi,
-                      DriverExtensions::HasLogEvents,
-                      DriverExtensions::HasNetworkInterception,
                       DriverExtensions::PrintsPage].freeze
 
         include LocalDriver

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

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

@@ -40,7 +40,6 @@ module Selenium
         LOCK_FILES = %w[.parentlock parent.lock lock].freeze
 
         attr_reader :name, :log_file
-        attr_writer :secure_ssl, :load_no_focus_lib
 
         class << self
           def ini
@@ -110,19 +109,28 @@ module Selenium
         end
 
         def port=(port)
+          WebDriver.logger.deprecate('Firefox::Profile#port=', 'the Service class', id: :firefox_profile)
           self[WEBDRIVER_PREFS[:port]] = port
         end
 
+        def secure_ssl=(value)
+          WebDriver.logger.deprecate('Firefox::Profile#secure_ssl=', id: :firefox_profile)
+          @secure_ssl = value
+        end
+
+        def load_no_focus_lib=(value)
+          WebDriver.logger.deprecate('Firefox::Profile#load_no_focus_lib=', id: :firefox_profile)
+          @load_no_focus_lib = value
+        end
+
         def log_file=(file)
           @log_file = file
           self[WEBDRIVER_PREFS[:log_file]] = file
         end
 
-        #
-        # Add the extension (directory, .zip or .xpi) at the given path to the profile.
-        #
-
         def add_extension(path, name = extension_name_for(path))
+          WebDriver.logger.deprecate('Firefox::Profile#add_extension', 'Driver#install_addon',
+                                     id: :firefox_profile)
           @extensions[name] = Extension.new(path)
         end
 
@@ -133,7 +141,6 @@ module Selenium
           when :manual
             self['network.proxy.type'] = 1
 
-            set_manual_proxy_preference 'ftp', proxy.ftp
             set_manual_proxy_preference 'http', proxy.http
             set_manual_proxy_preference 'ssl', proxy.ssl
             set_manual_proxy_preference 'socks', proxy.socks

data/lib/selenium/webdriver/remote/bidi_bridge.rb

@@ -18,40 +18,55 @@
 # under the License.
 
 require 'selenium/webdriver/bidi'
-require 'selenium/webdriver/bidi/transport'
+require 'selenium/webdriver/bidi/protocol'
 
 module Selenium
   module WebDriver
     module Remote
       class BiDiBridge < Bridge
-        attr_reader :bidi, :transport
+        attr_reader :bidi, :connection
+
+        READINESS_STATE = {
+          'none' => :none,
+          'eager' => :interactive,
+          'normal' => :complete
+        }.freeze
 
         def create_session(capabilities)
           super
-          socket_url = @capabilities[:web_socket_url]
-          @bidi = Selenium::WebDriver::BiDi.new(url: socket_url)
-          # Share the BiDi object's socket until the bridge owns the connection directly.
-          @transport = BiDi::Transport.new(@bidi.ws)
+
+          begin
+            @bidi = Selenium::WebDriver::BiDi.new(url: validated_socket_url)
+            # Reuse the BiDi object's socket as the connection until the bridge owns it directly.
+            @connection = @bidi.ws
+          rescue StandardError
+            quit
+            raise
+          end
         end
 
         def get(url)
-          browsing_context.navigate(url)
+          browsing_context.navigate(context: window_handle, url: url, wait: readiness_state)
+          nil
         end
 
         def go_back
-          browsing_context.traverse_history(-1)
+          browsing_context.traverse_history(context: window_handle, delta: -1)
+          nil
         end
 
         def go_forward
-          browsing_context.traverse_history(1)
+          browsing_context.traverse_history(context: window_handle, delta: 1)
+          nil
         end
 
         def refresh
-          browsing_context.reload
+          browsing_context.reload(context: window_handle, wait: readiness_state)
+          nil
         end
 
         def quit
-          bidi.close
+          bidi&.close
         rescue *QUIT_ERRORS
           nil
         ensure
@@ -64,8 +79,20 @@ module Selenium
 
         private
 
+        def validated_socket_url
+          url = @capabilities[:web_socket_url]
+          return url if url.is_a?(String) && url.start_with?('ws://', 'wss://')
+
+          raise Error::WebDriverError,
+                "BiDi was enabled, but the remote end did not return a valid webSocketUrl: #{url.inspect}."
+        end
+
         def browsing_context
-          @browsing_context ||= WebDriver::BiDi::BrowsingContext.new(self)
+          @browsing_context ||= BiDi::Protocol::BrowsingContext.new(connection)
+        end
+
+        def readiness_state
+          READINESS_STATE.fetch(capabilities[:page_load_strategy] || 'normal')
         end
       end # BiDiBridge
     end # Remote

data/lib/selenium/webdriver/remote/bridge.rb

@@ -598,7 +598,7 @@ module Selenium
           raise(WebDriver::Error::WebDriverError, msg)
         end
 
-        def transport
+        def connection
           msg = 'BiDi must be enabled by setting #web_socket_url to true in options class'
           raise(WebDriver::Error::WebDriverError, msg)
         end

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

@@ -37,7 +37,9 @@ module Selenium
 
           caps = process_options(options, capabilities)
           http_client ||= Remote::Http::Default.new(client_config: client_config)
-          http_client.server_url = url || client_config&.server_url || "http://#{Platform.localhost}:4444/wd/hub"
+          server_url = url || client_config&.server_url || "http://#{Platform.localhost}:4444/wd/hub"
+          http_client.server_url = server_url
+          caps['se:remoteUrl'] = server_url.to_s.chomp('/')
           super(caps: caps, http_client: http_client, **)
           @bridge.file_detector = ->((filename, *)) { File.exist?(filename) && filename.to_s }
           command_list = @bridge.command_list

data/lib/selenium/webdriver/remote/http/default.rb

@@ -124,7 +124,7 @@ module Selenium
           end
 
           def follow_redirect(response, redirects)
-            WebDriver.logger.debug("Redirect to #{response['Location']}; times: #{redirects}")
+            WebDriver.logger.debug("Redirect to #{response['Location']}; times: #{redirects}", id: :redirect)
             raise Error::WebDriverError, 'too many redirects' if redirects >= client_config.max_redirects
 
             request(:get, URI.parse(response['Location']), DEFAULT_HEADERS.dup, nil, redirects + 1)

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

@@ -25,7 +25,8 @@ module Selenium
 
         # @see https://developer.apple.com/documentation/webkit/about_webdriver_for_safari
         CAPABILITIES = {automatic_inspection: 'safari:automaticInspection',
-                        automatic_profiling: 'safari:automaticProfiling'}.freeze
+                        automatic_profiling: 'safari:automaticProfiling',
+                        experimental_web_socket_url: 'safari:experimentalWebSocketUrl'}.freeze
         BROWSER = 'safari'
         TECHNOLOGY_PREVIEW = 'Safari Technology Preview'
 
@@ -43,6 +44,20 @@ module Selenium
         def browser_name
           @options[:browser_name] = Safari.technology_preview? ? TECHNOLOGY_PREVIEW : BROWSER
         end
+
+        #
+        # Enables WebDriver BiDi for Safari, which also requires the experimental capability, and
+        # warns that Safari's BiDi support is experimental.
+        #
+        # @return [Boolean]
+        #
+
+        def enable_bidi!
+          super
+          WebDriver.logger.warn("Safari's WebDriver BiDi support is experimental and may be incomplete",
+                                id: :safari_bidi)
+          @options[:experimental_web_socket_url] = true
+        end
       end # Options
     end # Safari
   end # WebDriver

data/lib/selenium/webdriver/support/guards/guard.rb

@@ -30,7 +30,7 @@ module Selenium
           attr_reader :guarded, :type, :messages, :reason, :tracker
 
           def initialize(guarded, type, guards = nil)
-            @guarded = guarded
+            @guarded = guarded.dup
             @tracker = guards&.bug_tracker || ''
             @messages = guards&.messages || {}
             @messages[:unknown] = 'TODO: Investigate why this is failing and file a bug report'
@@ -47,7 +47,7 @@ module Selenium
                       when Symbol
                         messages[reason]
                       else
-                        "Guarded by #{guarded};"
+                        "#{type.to_s.tr('_', ' ')} #{guarded};"
                       end
 
             case type
@@ -57,8 +57,10 @@ module Selenium
               "Test skipped because it is unreliable in this configuration; #{details}"
             when :skip_unless, :exclusive
               "Test does not apply to this configuration; #{details}"
-            else
+            when :pending_if, :pending_unless, :except, :only
               "Test guarded; #{details}"
+            else
+              raise ArgumentError, "unknown guard type: #{type}"
             end
           end
 
@@ -81,6 +83,21 @@ module Selenium
           def exclusive?
             @type == :skip_unless || @type == :exclusive
           end
+
+          # A pending guard that only applies when the failure matches an expected exception.
+          def exception?
+            (except? || only?) && !@guarded[:exception].nil?
+          end
+
+          # Whether the exception is the guard's `exception:` class and matches its optional `message:`
+          # (Regexp pattern or exact String), following RSpec's `raise_error` semantics.
+          def matches_exception?(exception)
+            spec = @guarded[:exception]
+            return false unless spec && exception.is_a?(spec[:class])
+
+            message = spec[:message]
+            message.nil? || (message.is_a?(Regexp) ? message.match?(exception.message) : message == exception.message)
+          end
         end # Guard
       end # Guards
     end # Support

data/lib/selenium/webdriver/support/guards.rb

@@ -41,7 +41,7 @@ module Selenium
         def add_condition(name, condition = false, &block)
           condition = false if condition.nil?
           @guard_conditions << GuardCondition.new(name, condition, &block)
-          WebDriver.logger.debug "Running with Guard '#{name}' set to: #{condition}"
+          WebDriver.logger.debug "Running with Guard '#{name}' set to: #{condition}", id: :guard
         end
 
         def add_message(name, message)
@@ -52,12 +52,18 @@ module Selenium
           if !skipping_guard.nil?
             [:skip, skipping_guard.message]
           elsif !pending_guard.nil? && ENV.fetch('SKIP_PENDING', nil)
-            [:skip, pending_guard.message]
-          elsif !pending_guard.nil?
+            [:skip, "(skipped by SKIP_PENDING) #{pending_guard.message}"]
+          elsif !pending_guard.nil? && !pending_guard.exception?
             [:pending, pending_guard.message]
           end
         end
 
+        # The deferred `exception:` pending guard, evaluated against the failure after the run, else nil.
+        def pending_exception_guard
+          guard = pending_guard
+          guard if disposition.nil? && guard&.exception?
+        end
+
         def satisfied?(guard)
           @guard_conditions.all? { |condition| condition.satisfied?(guard) }
         end