selenium-webdriver 4.46.0 → 4.47.0

data/lib/selenium/webdriver/bidi/serialization/record.rb

@@ -29,7 +29,8 @@ module Selenium
         # @api private
         class Record < ::Data
           # Named Field, not Member, to avoid colliding with +::Data#members+.
-          Field = ::Data.define(:name, :wire_key, :nullable, :ref, :list, :fixed, :enum, :required, :primitive)
+          Field = ::Data.define(:name, :wire_key, :nullable, :ref, :list, :fixed, :enum, :required, :primitive,
+                                :scalar, :const)
 
           def self.define(**spec)
             extensible = spec.delete(:extensible) || false
@@ -59,7 +60,8 @@ module Selenium
             Field.new(name: name.to_sym, wire_key: meta.fetch(:wire_key, name.to_s),
                       nullable: meta[:nullable] || false, ref: meta[:ref],
                       list: meta[:list] || false, fixed: meta.fetch(:fixed, UNSET), enum: meta[:enum],
-                      required: meta.fetch(:required, true), primitive: meta[:primitive])
+                      required: meta.fetch(:required, true), primitive: meta[:primitive],
+                      scalar: meta[:scalar], const: meta.fetch(:const, UNSET))
           end
           private_class_method :field
 
@@ -77,9 +79,10 @@ module Selenium
               construct(**attributes)
             end
 
-            # Inbound: builds from the wire. A missing required field raises (in +wire_value+),
-            # enum tokens are mapped back to symbols and an unrecognized one raises (in +read+), and
-            # extra keys are captured (extensible) or ignored (closed) — strict on shape, lenient on extras.
+            # Inbound: builds from the wire. A missing required field is omitted and warned (or
+            # raised in strict mode, in +wire_value+); enum tokens are mapped back to symbols and an
+            # unrecognized one raises (in +read+); an undeclared property is captured silently
+            # (extensible) or warned and dropped (closed) — strict on shape, lenient on extras.
             def from_json(json_payload)
               unless json_payload.is_a?(::Hash)
                 raise Error::WebDriverError, "#{name} expected an object on the wire, got #{json_payload.inspect}"
@@ -88,7 +91,12 @@ module Selenium
               attributes = fields.to_h do |f|
                 [f.name, wire_value(f, json_payload)]
               end
-              attributes[:extensions] = extra(json_payload) if extensible?
+              undeclared = extra(json_payload)
+              if extensible?
+                attributes[:extensions] = undeclared # the spec sanctions these extras; preserve them silently
+              else
+                warn_undeclared(undeclared) unless undeclared.empty?
+              end
               construct(**attributes)
             end
 
@@ -96,9 +104,11 @@ module Selenium
 
             # Checks each field's value: a required field cannot be omitted (UNSET), a non-nullable
             # field cannot be nil (nil is neither a value nor the UNSET omit-sentinel, so it would be
-            # silently dropped on the wire), and an enum field must be in its allowed set. The enum
-            # constant is resolved lazily so a cross-domain enum need not be loaded first. Outbound
-            # only (from +new+); inbound presence/enum are checked separately in +wire_value+/+read+.
+            # silently dropped on the wire), a nullable-const field must carry its literal (not some
+            # other value), a primitive field must be the matching Ruby type, and an enum field must be
+            # in its allowed set. The enum constant is resolved lazily so a cross-domain enum need not be
+            # loaded first. Outbound only (from +new+); inbound presence/primitive/enum are checked
+            # separately in +wire_value+/+read+.
             def validate_values(attributes)
               fields.each do |f|
                 value = attributes[f.name]
@@ -106,11 +116,79 @@ module Selenium
                 raise ::ArgumentError, "#{name}##{f.name} cannot be nil" if value.nil? && !f.nullable
                 next if value.nil? || UNSET.equal?(value)
 
-                check_outbound_shape(f, value)
-                Serialization.validate!("#{name}##{f.name}", value, Protocol.const_get(f.enum)) if f.enum
+                validate_present(f, value)
               end
             end
 
+            # Checks a field that carries an actual value (neither omitted nor nil): a nullable-const
+            # field against its literal, list/scalar shape, primitive type (lists excepted, as inbound
+            # does), ref type, and enum membership (resolved lazily so a cross-domain enum need not load first).
+            def validate_present(field, value)
+              validate_const(field, value)
+              check_outbound_shape(field, value)
+              check_outbound_primitive(field, value) unless field.list
+              validate_ref(field, value) if field.ref
+              Serialization.validate!("#{name}##{field.name}", value, Protocol.const_get(field.enum)) if field.enum
+            end
+
+            # Outbound mirror of read_ref: a ref-typed value must be the type it declares, so a wrong
+            # record or a value no union variant accepts is a caller error caught here, not a browser
+            # round-trip. Shape is already checked, so a list is an Array.
+            def validate_ref(field, value)
+              klass = (@refs ||= {})[field.name] ||= Protocol.const_get(field.ref)
+              field.list ? validate_ref_list(field, klass, value) : validate_ref_value(field, klass, value)
+            end
+
+            # Mirrors read_list: a scalar field is a [key, value] map, a nested list recurses, otherwise
+            # each element is checked against the ref.
+            def validate_ref_list(field, klass, list)
+              list.each do |element|
+                if field.scalar
+                  validate_ref_entry(field, klass, element)
+                elsif element.is_a?(::Array)
+                  validate_ref_list(field, klass, element)
+                else
+                  validate_ref_value(field, klass, element)
+                end
+              end
+            end
+
+            # A [key, value] map entry: the key may be a variant or a bare scalar, the value is a variant.
+            def validate_ref_entry(field, klass, element)
+              unless element.is_a?(::Array) && element.size == 2
+                raise ::ArgumentError, "#{name}##{field.name} expected a [key, value] pair, got #{element.inspect}"
+              end
+
+              key, value = element
+              key.is_a?(Serializable) ? validate_ref_value(field, klass, key) : check_outbound_scalar(field, key)
+              validate_ref_value(field, klass, value)
+            end
+
+            # A record ref must be an instance of that record; a union ref must be one the union accepts.
+            def validate_ref_value(field, klass, value)
+              return if klass < Union ? klass.valid_outbound?(value) : value.is_a?(klass)
+
+              raise ::ArgumentError, "#{name}##{field.name} expected #{field.ref}, got #{value.inspect}"
+            end
+
+            # Outbound mirror of scalar_value: a bare map key must match one of the arm's primitives.
+            def check_outbound_scalar(field, value)
+              expected = Array(field.scalar).flat_map { |primitive| PRIMITIVE_TYPES[primitive] || [] }
+              return if expected.empty? || expected.any? { |type| value.is_a?(type) }
+
+              raise ::ArgumentError,
+                    "#{name}##{field.name} expected #{Array(field.scalar).join(' or ')}, got #{value.inspect}"
+            end
+
+            # A nullable constant (`literal / null`) is caller-settable but its only non-null value is
+            # the literal, so a value that is neither the literal nor nil (nil is handled above) is a
+            # local error rather than a wire round-trip. A non-const field carries UNSET here and passes.
+            def validate_const(field, value)
+              return if UNSET.equal?(field.const) || value == field.const
+
+              raise ::ArgumentError, "#{name}##{field.name} must be #{field.const.inspect}, got #{value.inspect}"
+            end
+
             # Outbound mirror of check_shape: a list-typed arg must be an array, a scalar-shaped one
             # (enum or ref, not a list) must not — a local ArgumentError, not a wire round-trip.
             def check_outbound_shape(field, value)
@@ -121,6 +199,17 @@ module Selenium
               raise ::ArgumentError, "#{name}##{field.name} expected #{kind}, got #{value.inspect}"
             end
 
+            # Outbound mirror of check_primitive: a primitive-typed arg (`string`/`integer`/…) must be
+            # the matching Ruby type, so a caller mistake (a string width, a float count) is a local
+            # ArgumentError here rather than a rejection the browser reports a round-trip later. A field
+            # with no primitive descriptor (enum, ref, opaque) passes; lists are skipped, as inbound does.
+            def check_outbound_primitive(field, value)
+              expected = PRIMITIVE_TYPES[field.primitive]
+              return if expected.nil? || expected.any? { |type| value.is_a?(type) }
+
+              raise ::ArgumentError, "#{name}##{field.name} expected #{field.primitive}, got #{value.inspect}"
+            end
+
             def fixed?(field)
               !UNSET.equal?(field.fixed)
             end
@@ -130,7 +219,19 @@ module Selenium
               return read(field, json_payload[field.wire_key]) if json_payload.key?(field.wire_key)
               return UNSET unless field.required
 
-              raise Error::WebDriverError, "#{name}##{field.name} is required but was missing from the response"
+              missing_required(field)
+            end
+
+            # A required field absent from the response is tolerated as omitted (UNSET) and warned, so a
+            # schema ahead of the browser does not block the caller; strict mode (SE_BIDI_STRICT) escalates
+            # to an error for callers who want it. Omitted (UNSET) stays distinct from an explicit null (nil),
+            # which matters for the required-and-nullable fields the schema flags.
+            def missing_required(field)
+              message = "#{name}##{field.name} is required but was missing from the response"
+              raise Error::WebDriverError, message if Serialization.strict?
+
+              WebDriver.logger.warn(message, id: :bidi_missing_required)
+              UNSET
             end
 
             def read(field, raw)
@@ -147,8 +248,18 @@ module Selenium
                 return raw
               end
 
+              read_ref(field, raw)
+            end
+
+            # Reads a ref-typed value into its class. A `scalar` position is an inline union with
+            # a scalar arm collapsed onto its union ref (a map's string keys): a non-object leaf
+            # passes through instead of being handed to the object_only union, but only when it
+            # matches the arm's primitive (+scalar+ carries it). A list recurses per element.
+            def read_ref(field, raw)
               klass = (@refs ||= {})[field.name] ||= Protocol.const_get(field.ref)
-              field.list ? read_list(raw, klass) : klass.from_json(raw)
+              return read_list(field, raw, klass) if field.list
+
+              field.scalar && !raw.is_a?(::Hash) ? scalar_value(field, raw) : klass.from_json(raw)
             end
 
             # A declared list must arrive as an array; a scalar-shaped field (enum or ref, not a
@@ -181,16 +292,64 @@ module Selenium
               (@enums ||= {})[field.name] ||= Protocol.const_get(field.enum)
             end
 
-            # Parses each element, recursing into nested lists (e.g. a map's [key, value] pairs)
-            # so their entries become typed too.
-            def read_list(raw, klass)
-              raw.map { |element| element.is_a?(::Array) ? read_list(element, klass) : klass.from_json(element) }
+            # Parses each element. A `scalar` field is a map encoded as `[key, value]` pairs, so
+            # every element must be a 2-item pair — each is read as one, and a malformed entry is
+            # rejected. Non-scalar lists recurse into nested lists; other elements deserialize.
+            def read_list(field, raw, klass)
+              raw.map do |element|
+                if field.scalar
+                  read_map_entry(field, element, klass)
+                elsif element.is_a?(::Array)
+                  read_list(field, element, klass)
+                else
+                  klass.from_json(element)
+                end
+              end
+            end
+
+            # A map entry is a `[key, value]` pair. The key is `Ref / text` — an object key
+            # deserializes, a bare-string key passes through once validated against the arm's
+            # primitive. The value is the object-only Ref and always deserializes, so a bare scalar
+            # there is rejected (object_only holds at the value position). A non-pair element is a
+            # malformed entry and is rejected outright.
+            def read_map_entry(field, element, klass)
+              unless element.is_a?(::Array) && element.size == 2
+                raise Error::WebDriverError,
+                      "#{name}##{field.name} expected a [key, value] pair, got #{element.inspect}"
+              end
+
+              key, value = element
+              key = key.is_a?(::Hash) ? klass.from_json(key) : scalar_value(field, key)
+              [key, klass.from_json(value)]
+            end
+
+            # A bare scalar at a scalar-tolerant union position must match one of the union's
+            # scalar-arm primitives (+scalar+ is a primitive name or an array of them); a
+            # wrong-typed scalar (a number where a string is expected) is a wire error, not
+            # something to pass through. An unrecognized primitive (none in PRIMITIVE_TYPES) is
+            # left unchecked, matching the lenient default elsewhere.
+            def scalar_value(field, value)
+              expected = Array(field.scalar).flat_map { |primitive| PRIMITIVE_TYPES[primitive] || [] }
+              return value if expected.empty? || expected.any? { |type| value.is_a?(type) }
+
+              raise Error::WebDriverError,
+                    "#{name}##{field.name} expected #{Array(field.scalar).join(' or ')}, got #{value.inspect}"
             end
 
             def extra(json_payload)
               known = (@wire_keys ||= fields.map(&:wire_key))
               json_payload.except(*known)
             end
+
+            # Forward-compat signal: a property a closed type does not model is dropped and warned so
+            # schema drift is visible (an extensible type keeps its extras silently — the spec sanctions
+            # them). Tagged +:bidi_undeclared_property+ so a caller can silence it via +logger.ignore+.
+            def warn_undeclared(undeclared)
+              undeclared.each_key do |key|
+                WebDriver.logger.warn("#{name} received an undeclared property: #{key.inspect}",
+                                      id: :bidi_undeclared_property)
+              end
+            end
           end
 
           # @api private
@@ -215,9 +374,26 @@ module Selenium
                 value = Serialization.to_wire(value, Protocol.const_get(f.enum)) if f.enum
                 payload[f.wire_key] = Serializable.as_json(value)
               end
-              payload.merge!(extensions) if self.class.extensible? && !extensions.empty?
+              merge_extensions!(payload) if self.class.extensible? && !extensions.empty?
               payload
             end
+
+            private
+
+            # Merge the passthrough extras onto the wire, erroring rather than letting an extra whose key
+            # is a declared field's wire key silently clobber that typed value; an extra is by definition
+            # a field the spec does not declare. Keys are stringified first so a symbol key (e.g. `name:`)
+            # cannot slip past the guard and then reappear as a duplicate wire key once serialized. The
+            # single gate every outbound path funnels through: +new+, +with+, and in-place mutation.
+            def merge_extensions!(payload)
+              extras = extensions.transform_keys(&:to_s)
+              collisions = extras.keys & self.class.fields.map(&:wire_key)
+              unless collisions.empty?
+                raise ::ArgumentError, "#{self.class.name} extensions shadow declared fields: #{collisions.join(', ')}"
+              end
+
+              payload.merge!(extras)
+            end
           end
         end
       end

data/lib/selenium/webdriver/bidi/serialization/union.rb

@@ -44,10 +44,24 @@ module Selenium
             def presence(rules) = @presence = rules
             def fallback(path) = @fallback = path
 
-            # A non-Hash payload is a bare scalar arm (e.g. input.Origin's "viewport") with
-            # no object to dispatch on, so it is returned unchanged.
+            # Declared (via the schema's `objectOnly` signal) on a union whose every arm is an
+            # object, so a non-Hash payload is a schema violation rather than a scalar arm.
+            def object_only = @object_only = true
+
+            # Declared (via the schema's `scalarValues` signal) on a non-object_only union whose
+            # bare-scalar arms are a fixed set of literals (input.Origin's "viewport" / "pointer").
+            # An outbound scalar outside that set matches no arm, so it is a caller error.
+            def scalar_values(*values) = @scalar_values = values
+
+            # A non-Hash payload is a bare scalar arm (e.g. input.Origin's "viewport") with no
+            # object to dispatch on, so it is returned unchanged — unless every arm is an object
+            # (object_only), where a non-Hash cannot match any variant and is a wire error.
             def from_json(json_payload)
-              return json_payload unless json_payload.is_a?(::Hash)
+              unless json_payload.is_a?(::Hash)
+                return json_payload unless @object_only
+
+                raise Error::WebDriverError, "#{name} expected an object on the wire, got #{json_payload.inspect}"
+              end
 
               variant = select(json_payload)
               unless variant
@@ -75,8 +89,36 @@ module Selenium
               raise ::ArgumentError, "invalid combination for #{name}: #{invalid.join(', ')}"
             end
 
+            # Outbound mirror of from_json: is +value+ one this union accepts? Any variant is accepted,
+            # and a variant that is itself a union recurses (e.g. LocalValue's RemoteReference fallback).
+            # A non-object_only union (e.g. input.Origin) also admits one of its pinned bare-scalar
+            # literals; an object (a Hash or another union's record) that matched no variant does not.
+            def valid_outbound?(value)
+              return true if variant_refs.any? { |ref| variant_accepts?(ref, value) }
+
+              !@object_only && scalar_arm?(value)
+            end
+
             private
 
+            # A bare-scalar arm must be one of the literals the schema pinned for this union
+            # (scalar_values, e.g. input.Origin's "viewport" / "pointer"). The generator guarantees a
+            # non-object_only union declares them, so no runtime guard is needed here.
+            def scalar_arm?(value)
+              @scalar_values.include?(value)
+            end
+
+            # Every variant's class name: the discriminated table, the presence paths, and the fallback.
+            def variant_refs
+              @variant_refs ||= [*@variants&.values, *@presence&.keys, @fallback].compact
+            end
+
+            # A variant that is itself a union recurses; a record variant is matched by instance.
+            def variant_accepts?(ref, value)
+              klass = (@variant_classes ||= {})[ref] ||= Protocol.const_get(ref)
+              klass < Union ? klass.valid_outbound?(value) : value.is_a?(klass)
+            end
+
             # The discriminator value may legitimately be null (e.g. script.NullValue's
             # "null" tag), so it is matched by key presence.
             def select(json_payload)

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

@@ -21,7 +21,8 @@ module Selenium
   module WebDriver
     class BiDi
       # Wire round-trip runtime for the generated protocol layer: the value-type bases
-      # (Record, Union), the omit sentinel (UNSET), and outbound enum validation.
+      # (Record, Union), the omit sentinel (UNSET), outbound enum validation, and the
+      # strict-inbound toggle.
       #
       # @api private
       module Serialization
@@ -33,6 +34,17 @@ module Selenium
         def UNSET.inspect = 'UNSET'
         UNSET.freeze
 
+        # Strict inbound mode. Off by default: a required field missing from a response is
+        # tolerated as omitted and warned, so a schema ahead of the browser does not block the
+        # caller. When SE_BIDI_STRICT is set to anything but 0/false, that same case escalates
+        # to an error for callers who want it.
+        #
+        # @api private
+        def self.strict?
+          value = ENV.fetch('SE_BIDI_STRICT', '').strip.downcase
+          !value.empty? && value != '0' && value != 'false'
+        end
+
         # Validates an outbound enum argument: +value+ is a symbol (or list of symbols) that
         # must be a key of the enum hash (+{symbol => wire_token}+), so a bad value fails
         # locally with a clear error instead of a round-trip. Outbound only; inbound wire