selenium-webdriver 4.46.0 → 4.48.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,18 +79,24 @@ 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 raises (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}"
+                raise Error::SerializationError, "#{name} expected an object on the wire, got #{json_payload.inspect}"
               end
 
               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)
+              checks = Array(field.scalar).filter_map { |primitive| PRIMITIVE_CHECKS[primitive] }
+              return if checks.empty? || checks.any? { |check| check.call(value) }
+
+              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,34 +199,61 @@ 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)
+              check = PRIMITIVE_CHECKS[field.primitive]
+              return if check.nil? || check.call(value)
+
+              raise ::ArgumentError, "#{name}##{field.name} expected #{field.primitive}, got #{value.inspect}"
+            end
+
             def fixed?(field)
               !UNSET.equal?(field.fixed)
             end
 
+            # A required field absent from the response cannot yield a valid typed object, so it raises
+            # rather than substitute a placeholder or represent the field as omitted; a remote end that
+            # lags the schema is handled by a project schema override, not by runtime tolerance.
             def wire_value(field, json_payload)
               return field.fixed if fixed?(field)
               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"
+              raise Error::SerializationError, "#{name}##{field.name} is required but was missing from the response"
             end
 
             def read(field, raw)
               if raw.nil?
                 return raw if field.nullable
 
-                raise Error::WebDriverError, "#{name}##{field.name} received null but is not nullable"
+                raise Error::SerializationError, "#{name}##{field.name} received null but is not nullable"
               end
               check_shape(field, raw)
               return Serialization.to_symbol("#{name}##{field.name}", raw, enum_hash(field)) if field.enum
 
               if field.ref.nil?
-                check_primitive(field, raw) unless field.list
-                return raw
+                return raw if field.list
+
+                check_primitive(field, raw)
+                # A whole number is exact in both types, so the declared type is held with nothing lost.
+                return field.primitive == 'integer' && raw.is_a?(::Float) ? raw.to_i : 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
@@ -157,40 +262,91 @@ module Selenium
               return if field.list == raw.is_a?(::Array)
               return unless field.list || field.enum || field.ref
 
-              raise Error::WebDriverError,
+              raise Error::SerializationError,
                     "#{name}##{field.name} expected #{field.list ? 'a list' : 'a single value'}, got #{raw.inspect}"
             end
 
-            # Ruby classes a checkable primitive admits. `number` is any Numeric (JSON has one
-            # number type); `integer` requires an Integer — a browser emits `5`, not `5.0`, for an
-            # integer (JS has no int/float split), so this rarely false-positives yet still rejects
-            # a genuine non-integer like 1.5. A field with no primitive descriptor is left unchecked.
-            PRIMITIVE_TYPES = {
-              'string' => [::String], 'boolean' => [::TrueClass, ::FalseClass],
-              'number' => [::Numeric], 'integer' => [::Integer]
+            # The check a schema primitive admits, by JSON kind rather than Ruby class: `number` is
+            # any Numeric (JSON has one number type), and `integer` is any whole one — a browser is
+            # free to send `5` or `5.0` (JS has no int/float split), while a fractional value like
+            # 1.5 is a real mismatch. A field with no primitive descriptor is left unchecked.
+            WHOLE_FLOAT = ->(value) { value.is_a?(::Float) && value.finite? && (value % 1).zero? }
+            PRIMITIVE_CHECKS = {
+              'string' => ->(value) { value.is_a?(::String) },
+              'boolean' => ->(value) { value.is_a?(::TrueClass) || value.is_a?(::FalseClass) },
+              'number' => ->(value) { value.is_a?(::Numeric) },
+              'integer' => ->(value) { value.is_a?(::Integer) || WHOLE_FLOAT.call(value) }
             }.freeze
 
             def check_primitive(field, raw)
-              expected = PRIMITIVE_TYPES[field.primitive]
-              return if expected.nil? || expected.any? { |type| raw.is_a?(type) }
+              check = PRIMITIVE_CHECKS[field.primitive]
+              return if check.nil? || check.call(raw)
 
-              raise Error::WebDriverError, "#{name}##{field.name} expected #{field.primitive}, got #{raw.inspect}"
+              raise Error::SerializationError, "#{name}##{field.name} expected #{field.primitive}, got #{raw.inspect}"
             end
 
             def enum_hash(field)
               (@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::SerializationError,
+                      "#{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_CHECKS) is
+            # left unchecked, matching the lenient default elsewhere.
+            def scalar_value(field, value)
+              checks = Array(field.scalar).filter_map { |primitive| PRIMITIVE_CHECKS[primitive] }
+              return value if checks.empty? || checks.any? { |check| check.call(value) }
+
+              raise Error::SerializationError,
+                    "#{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 +371,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,14 +44,32 @@ 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"), valid only
+            # as a literal the schema pins; under object_only it cannot match any variant at all.
             def from_json(json_payload)
-              return json_payload unless json_payload.is_a?(::Hash)
+              unless json_payload.is_a?(::Hash)
+                if @object_only
+                  raise Error::SerializationError,
+                        "#{name} expected an object on the wire, got #{json_payload.inspect}"
+                end
+                return json_payload if scalar_arm?(json_payload)
+
+                raise Error::SerializationError,
+                      "#{name} received a scalar not in this Selenium's BiDi schema: #{json_payload.inspect}"
+              end
 
               variant = select(json_payload)
               unless variant
-                raise Error::WebDriverError,
+                raise Error::SerializationError,
                       "#{name} received a variant not in this Selenium's BiDi schema: #{json_payload.inspect}"
               end
               Protocol.const_get(variant).from_json(json_payload)
@@ -75,8 +93,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

@@ -67,7 +67,7 @@ module Selenium
           return value if value.nil?
           return value.map { |element| to_symbol(name, element, enum) } if value.is_a?(::Array)
 
-          enum.key(value) || raise(Error::WebDriverError, "#{name} received an unknown value: #{value.inspect}")
+          enum.key(value) || raise(Error::SerializationError, "#{name} received an unknown value: #{value.inspect}")
         end
       end
     end # BiDi