graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/testing/fake_client.rb

@@ -15,34 +15,43 @@ require_relative "../parsing"
 #
 # Values are type-correct by construction (real enum values, valid
 # __typename members for unions/interfaces, iso8601 for date scalars), so
-# every fake response casts cleanly through the generated structs. See
-# Values for value fabrication (mode: :faker / :literal).
+# every fake response casts cleanly through the generated structs.
 #
-# overrides: pin fields by GraphQL name — schema vocabulary, so keys
-# survive query refactors. "Type.field" beats "field"; values are
-# literals or zero-arg procs. Keys are checked against the schema, since
-# a typo'd one would pin nothing and leave the test green. (An override
-# with a wrong-typed value is also the way to simulate a corrupt
-# payload — casting raises GraphWeaver::TypeError.)
+# values: how they're written — :faker (semantic, matched on the field
+# name), :literal (plain type-derived), or nil to use faker when the gem is
+# loaded. Per fake: which reads better is one example's question.
 #
-#      FakeClient.new(schema:, overrides: {
-#        "Person.name" => "Daniel",
-#        "email" => -> { "test@example.com" },
-#      })
+# pins: what the fake uses instead of inventing a value, keyed by GraphQL
+# name — schema vocabulary, so keys survive query refactors. A scalar type
+# ("Money"), an object type ("Person"), or a field ("Order.total", or a
+# bare field name on any type). The value is a wire value, an object the
+# fake reads the selected fields off — a FactoryBot build, a model, a
+# Struct — or a proc returning either, handed the seeded Random when it
+# takes one. Keys are checked against the schema, since a typo'd one would
+# pin nothing and leave the test green. (A pin with a wrong-typed value is
+# also the way to simulate a corrupt payload — casting raises
+# GraphWeaver::TypeError.)
 #
-# An override pins a whole subtree as readily as a leaf, and **merges**
-# rather than replaces: name the fields the test is about and the rest of
-# the selection is still fabricated. A list pins its own length, so "two
+#      FakeClient.new({ "Money" => "12.00", "Person" => build(:person),
+#                       "email" => -> { "test@example.com" } }, schema:)
+#
+# Options are lowercase words, so a key with a dot or a leading capital is
+# a pin wherever it is written — `overrides:` is the same hash by keyword,
+# and the leading one wins where both name a key.
+#
+# A pin covers a whole subtree as readily as a leaf, and **merges** rather
+# than replaces: name the fields the test is about and the rest of the
+# selection is still fabricated. A list pins its own length, so "two
 # orders, the first one paid" is the literal thing you write:
 #
-#      FakeClient.new(schema:, overrides: {
-#        "Reader.name" => "Ada",
-#        "Reader.orders" => [{ "status" => "PAID" }, {}],
-#      })
+#      FakeClient.new({ "Reader.name" => "Ada",
+#                       "Reader.orders" => [{ "status" => "PAID" }, {}] }, schema:)
 #
-# Keys inside a pinned subtree are response keys — what comes back on the
+# Keys inside a pinned Hash are response keys — what comes back on the
 # wire, aliases included — and one the query doesn't select is refused,
-# for the same reason a typo'd coordinate is.
+# for the same reason a typo'd coordinate is. An object pin is read the
+# other way round: the reader is the snake_cased field name, not the alias,
+# and a field it doesn't answer is fabricated.
 #
 # requests: every execute, in order ({ query:, variables:, operation_name: })
 # — "did we send the right variables", and "did we call it at all".
@@ -65,15 +74,23 @@ require_relative "../parsing"
 #
 #      FakeClient.new(schema:, corrupt: "Person.birthday")
 #
-# seed: makes a run reproducible (also seeds faker). Every option,
-# schema: included, falls back to GraphWeaver::Testing.config — and the
+# null_chance: how often a nullable field comes back null — 0 by default,
+# and per fake only: "does this render with no email" is one example's
+# question, and a suite-wide answer would sprinkle nils through every other
+# example instead.
+#
+#      FakeClient.new(schema:, null_chance: 1.0)   # everything nullable, null
+#
+# seed: makes a run reproducible (also seeds faker). schema:, overrides:
+# and list_size: fall back to GraphWeaver::Testing.config — and the
 # config's schema falls back to the committed dump.
 class GraphWeaver::Testing::FakeClient
   include GraphWeaver::Parsing
-  include GraphWeaver::Selection
+  include GraphWeaver::Internal::Selection
 
   # sentinel: a simulated failure bubbling up to the nearest nullable spot
   NULL_BUBBLE = Object.new.freeze
+  private_constant :NULL_BUBBLE
 
   # sentinel: no override here — distinct from an override OF nil, which
   # pins the field null
@@ -90,22 +107,57 @@ class GraphWeaver::Testing::FakeClient
   #      expect(fake.requests.last[:variables]).to eq({ "id" => "1" })
   attr_reader :requests
 
-  def initialize(schema: nil, overrides: {}, seed: nil, mode: nil, list_size: nil, null_chance: nil,
-    errors: nil, fail_at: nil, corrupt: nil)
+  # Everything a fake takes, with its default. This IS the signature — a
+  # keyword list can only refuse what reaches it, and two of the three doors
+  # onto a fake (graphql_fake, a router's fake:) forward a hash, so a
+  # misspelled key arrived as a bare "unknown keyword" from inside the
+  # fabricator, naming neither the accepted options nor the one you meant.
+  OPTIONS = {
+    schema: nil, overrides: {}, seed: nil, values: nil, list_size: nil,
+    null_chance: nil, errors: nil, fail_at: nil, corrupt: nil,
+  }.freeze
+
+  # One rule tells a pin from an option: options are lowercase words, and
+  # anything with a dot or a leading capital names something in the schema.
+  # Ruby 3 hands every braceless pair to **options — String keys included —
+  # so `FakeClient.new("Order.total" => "9", seed: 1)` arrives whole and is
+  # split here, as is a quoted symbol (`"Order.total":`) or a hash forwarded
+  # by a router's fake:.
+  PIN_KEY = /\A[A-Z]|\./
+
+  # JSON's own types are already on the wire: at a leaf they skip the
+  # registry's serializer, and at a composite position (a Hash aside, which
+  # is response keys) they pin the field as written — nil is null, the rest
+  # is the corrupt payload the example asked for.
+  WIRE = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Array, Hash].freeze
+
+  # Methods every Ruby object answers aren't fields: a schema does have a
+  # `hash` or a `count`, and a Struct answers both with plausible nonsense
+  # where fabricating is right.
+  RUBY_OWN = [BasicObject, Kernel, Object, Comparable, Enumerable, Struct, Data].freeze
+  private_constant :OPTIONS, :PIN_KEY, :WIRE, :RUBY_OWN
+
+  def initialize(pins = {}, **options)
+    pins, options = check_options!(pins, options)
     config = GraphWeaver::Testing.config
-    @schema = schema || config.schema || raise(GraphWeaver::Error,
+    @schema = options[:schema] || config.schema || raise(GraphWeaver::Error,
       "no schema to fake against — set GraphWeaver::Testing.config.schema, pass schema:, " \
       "or commit a schema dump at #{GraphWeaver.schema_path}")
-    @overrides = config.overrides.merge(overrides)
-    GraphWeaver::Testing.validate_overrides!(@schema, @overrides)
-    @values = GraphWeaver::Testing::Values.new(seed:, mode:)
-    @list_size = list_size || config.list_size
-    @null_chance = null_chance || config.null_chance
+    # last wins, narrowest last: the suite's, then overrides:, then the pins
+    # this fake was handed outright
+    @overrides = [config.overrides, options[:overrides], pins]
+      .map { |hash| hash.transform_keys(&:to_s) }.reduce(:merge)
+    GraphWeaver::Internal::Overrides.validate!(@schema, @overrides)
+    @values = GraphWeaver::Internal::Values.new(seed: options[:seed], values: options[:values],
+      pins: @overrides)
+    @list_size = options[:list_size] || config.list_size
+    @null_chance = options[:null_chance] || 0.0
     # NOT Array(): it would explode a bare Hash into key/value pairs
-    @extra_errors = wrap(errors).map { |error| normalize_error(error) }
-    @fail_at = wrap(fail_at).map { |spec| normalize_fail_spec(spec) }
-    @corrupt = wrap(corrupt)
+    @extra_errors = wrap(options[:errors]).map { |error| normalize_error(error) }
+    @fail_at = wrap(options[:fail_at]).map { |spec| normalize_fail_spec(spec) }
+    @corrupt = wrap(options[:corrupt])
     @requests = []
+    @variables = nil # unknown until an execute says; see #object
   end
 
   # operation_name: is accepted for contract parity and ignored — one
@@ -126,6 +178,7 @@ class GraphWeaver::Testing::FakeClient
 
     operation = load_operation(query)
     root_type = operation_root_type(operation)
+    @variables = variable_values(operation, variables)
 
     @path = []
     @failures = []
@@ -144,14 +197,27 @@ class GraphWeaver::Testing::FakeClient
   # {FakeSubgraph} answers a federation `_entities` fetch through, where the
   # representation names the type and the document only ever reached it
   # through an inline fragment.
-  def object(type_name, selections, fragments: {})
+  #
+  # variables: are what @skip/@include read. Left unsaid they are *unknown*,
+  # not empty, and the directives go unevaluated: the router has already
+  # decided them for the fetch it is sending, and reading an unpassed
+  # variable as absent would drop the field it just asked for.
+  # operation: is the definition the selections came from — a faked subgraph
+  # passes it so @skip/@include see the defaults it declares, as graphql-ruby
+  # would. Without it, or variables:, directives stay unevaluated.
+  # failures: an array any simulated field error (fail_at:) is appended to,
+  # paths relative to this object. Left unsaid, a fail_at here only nulls the
+  # field — a null with no error is a response no server gives.
+  def object(type_name, selections, fragments: {}, variables: nil, operation: nil, failures: nil)
     type = @schema.get_type(type_name) or
       raise GraphWeaver::Error, "#{type_name} is not a type of this schema"
 
     @fragments = fragments
+    @variables = variables && variable_values(operation, variables)
     @path = []
     @failures = []
     value = object_value(type, selections)
+    failures&.concat(@failures)
     value.equal?(NULL_BUBBLE) ? nil : value
   end
 
@@ -163,8 +229,62 @@ class GraphWeaver::Testing::FakeClient
 
   private
 
+  # A misspelled option pins nothing and leaves the example green — the same
+  # silent pass a typo'd override key is refused for.
+  def check_options!(pins, options)
+    options, keyed_pins = options.partition { |key, _| !PIN_KEY.match?(key.to_s) }.map(&:to_h)
+    # what was written as a leading hash wins: it is the one form that can
+    # only ever be a pin
+    pins = keyed_pins.merge(pins.to_h)
+
+    unknown = options.keys - OPTIONS.keys
+    return [pins, OPTIONS.merge(options)] if unknown.empty?
+
+    suggestion = GraphWeaver::Internal::Util.did_you_mean(OPTIONS.keys.map(&:to_s), unknown.first.to_s)
+    hint = suggestion ? " — did you mean #{suggestion}:?" : "."
+    raise ArgumentError, "a fake doesn't take #{unknown.first}:#{hint} It takes " \
+      "#{OPTIONS.keys.map { |name| "#{name}:" }.join(", ")}"
+  end
+
   def rng = @values.rng
 
+  # Codegen has to type a @skip/@include field as maybe-absent because it
+  # can't know the variable; a fake was handed it, so it can answer the way
+  # the server would — and the way {Router} already does, or one query would
+  # carry a key under :fake and not under :router. Selection's walk recurses
+  # through this method, so filtering here filters at every depth.
+  def each_field(type, selections, visiting = Set.new, conditional: false, &block)
+    selections = selections.reject { |selection| omitted?(selection) } if @variables
+    super(type, selections, visiting, conditional:, &block)
+  end
+
+  # A variable with neither a value nor a declared default reads as absent,
+  # which excludes under @include and includes under @skip — as graphql-ruby
+  # resolves it.
+  def omitted?(selection)
+    selection.directives.any? do |directive|
+      next false unless GraphWeaver::Internal::Selection::CONDITIONAL_DIRECTIVES.include?(directive.name)
+
+      argument = directive.arguments.find { |arg| arg.name == "if" } or next false
+      value = argument_value(argument)
+      (directive.name == "skip") ? !!value : value.nil? || value == false
+    end
+  end
+
+  def argument_value(argument)
+    value = argument.value
+    value.is_a?(GraphQL::Language::Nodes::VariableIdentifier) ? @variables&.[](value.name) : value
+  end
+
+  # An operation's declared defaults are part of the variables graphql-ruby
+  # runs with, so @skip/@include and a `first:` have to see them too.
+  def variable_values(operation, variables)
+    defaults = (operation&.variables || []).each_with_object({}) do |definition, out|
+      out[definition.name] = definition.default_value unless definition.default_value.nil?
+    end
+    defaults.merge(variables.to_h { |name, value| [name.to_s, value] })
+  end
+
   def wrap(value)
     case value
     when nil then []
@@ -241,7 +361,7 @@ class GraphWeaver::Testing::FakeClient
     return pinned_value(field_type, node, selections, pin, source) unless pin.equal?(UNPINNED)
     return corrupt_value(field_type) if @corrupt.include?(coordinate)
 
-    type_value(field_type, node, selections)
+    type_value(field_type, node, selections, coordinate:)
   end
 
   # What an override pins here. A leaf takes the value outright; a composite
@@ -249,7 +369,7 @@ class GraphWeaver::Testing::FakeClient
   # fabricated, so pinning one nested field never means hand-writing the
   # subtree around it. A pinned list is exactly as long as it is written.
   def pinned_value(type, node, selections, value, source)
-    value = value.call if value.is_a?(Proc)
+    value = GraphWeaver::Internal::Overrides.resolve(value, rng)
 
     case type.kind.name
     when "NON_NULL" then pinned_value(type.of_type, node, selections, value, source)
@@ -264,30 +384,83 @@ class GraphWeaver::Testing::FakeClient
           @path.pop
         end
       end
-    when "OBJECT", "UNION", "INTERFACE"
-      return value unless value.is_a?(Hash)
-
-      object_value(pinned_type(type, value, source), selections, pins: value, source:)
+    when "OBJECT", "UNION", "INTERFACE" then pinned_object(type, selections, value, source)
     else
       value
     end
   end
 
+  # A pinned composite is a Hash of response keys, or an object the fake
+  # reads them off — a FactoryBot build, a model, a Struct. Either way it
+  # MERGES: what it doesn't answer is fabricated.
+  def pinned_object(type, selections, value, source)
+    return value if !value.is_a?(Hash) && wire?(value)
+
+    concrete = pinned_type(type, value, source)
+    pins = value.is_a?(Hash) ? value : read_fields(concrete, selections, value)
+    object_value(concrete, selections, pins:, source:)
+  end
+
+  # The response keys an object pin answers, read off it. The reader is the
+  # snake_cased FIELD name, not the alias — the object belongs to the domain,
+  # not to this query — and its Ruby values go through the scalar registry on
+  # the way to the wire.
+  def read_fields(type, selections, object)
+    gather(type, selections).each_with_object({}) do |(key, nodes), pins|
+      name = nodes.first.name
+      next if name == "__typename"
+
+      reader = GraphWeaver::Inflect.underscore(name)
+      next unless reader?(object, reader)
+
+      field_type = @schema.get_field(type.graphql_name, name).type
+      pins[key] = wire_value(field_type, object.public_send(reader),
+        "#{type.graphql_name}.#{name}")
+    end
+  end
+
+  # what the object itself answers — see RUBY_OWN
+  def reader?(object, name)
+    object.respond_to?(name) && !RUBY_OWN.include?(object.method(name).owner)
+  end
+
+  def wire?(value) = WIRE.any? { |klass| value.is_a?(klass) }
+
+  # An object pin holds Ruby values — a Time, a Money, a T::Enum — where the
+  # wire holds what the registration says they serialize to. A value that
+  # is already wire-shaped is taken as written.
+  def wire_value(type, value, coordinate)
+    case type.kind.name
+    when "NON_NULL" then wire_value(type.of_type, value, coordinate)
+    when "LIST"
+      value.is_a?(Array) ? value.map { |element| wire_value(type.of_type, element, coordinate) } : value
+    when "SCALAR"
+      return value if wire?(value)
+
+      GraphWeaver::Codegen.scalar(type.graphql_name, coordinate).serialize_value(value)
+    when "ENUM" then value.is_a?(T::Enum) ? value.serialize : value
+    else value # a composite: pinned_object reads it, one level down
+    end
+  end
+
   # The concrete type a pinned object is fabricated as. At a union or
   # interface the pin has to say: picking a member at random would fabricate
   # a shape the pinned keys don't fit, in whichever fraction of runs the
   # seed lands there.
   def pinned_type(type, value, source)
-    named = value["__typename"]
+    named = value["__typename"] if value.is_a?(Hash)
     return type if named == type.graphql_name
 
     members = (type.kind.name == "OBJECT") ? [type] : @schema.possible_types(type)
     if named.nil?
       return type if members.one?
 
+      # an object pin has no "__typename" to carry, so it says which by
+      # being keyed on the type it is
+      hint = value.is_a?(Hash) ? "name the one you mean with \"__typename\"" :
+        "pin it by type instead — { #{members.first.graphql_name.inspect} => ... }"
       raise GraphWeaver::Error, "override #{source.inspect} pins an object at #{location}, where " \
-        "the query can return #{members.map(&:graphql_name).sort.join(" or ")} — name the one you " \
-        "mean with \"__typename\"."
+        "the query can return #{members.map(&:graphql_name).sort.join(" or ")} — #{hint}."
     end
 
     found = members.find { |member| member.graphql_name == named }
@@ -306,7 +479,7 @@ class GraphWeaver::Testing::FakeClient
     unknown = pins.keys.reject { |key| key == "__typename" || fields.key?(key) }
     return if unknown.empty?
 
-    suggestion = GraphWeaver.did_you_mean(fields.keys, unknown.first.to_s)
+    suggestion = GraphWeaver::Internal::Util.did_you_mean(fields.keys, unknown.first.to_s)
     hint = suggestion ? " — did you mean #{suggestion.inspect}?" : "."
     raise GraphWeaver::Error, "override #{source.inspect} supplies #{unknown.first.inspect} at " \
       "#{location}, which this query doesn't select#{hint} An override's keys are response keys, " \
@@ -340,24 +513,32 @@ class GraphWeaver::Testing::FakeClient
     @fail_at.find { |spec| !spec["triggered"] && spec["path"] == chain }
   end
 
-  # honor pagination-ish arg semantics: first/last/limit with a literal
-  # int caps the fabricated list length
+  # honor pagination-ish arg semantics: first/last/limit caps the fabricated
+  # list length, whether it arrives as a literal or as a variable
   def list_length(node)
     argument = node.arguments.find { |arg| %w[first last limit].include?(arg.name) }
-    return argument.value if argument && argument.value.is_a?(Integer)
+    capped = argument && argument_value(argument)
+    # Array.new(-1) is "negative array size" out of the fabricator's guts; a
+    # cap below zero asks for nothing, which is what a page of none is
+    return [capped, 0].max if capped.is_a?(Integer)
 
     # an Integer list_size means exactly that many; a Range randomizes within it
     @list_size.is_a?(Range) ? rng.rand(@list_size) : @list_size
   end
 
-  def type_value(type, node, selections, non_null: false)
+  def type_value(type, node, selections, coordinate: nil, non_null: false)
+    if type.kind.name == "NON_NULL"
+      return type_value(type.of_type, node, selections, coordinate:, non_null: true)
+    end
+    # every nullable position, a list included — null_chance is about the
+    # nilable props codegen emitted, and it emits one for `[Thing!]` too
+    return if !non_null && rng.rand < @null_chance
+
     case type.kind.name
-    when "NON_NULL"
-      type_value(type.of_type, node, selections, non_null: true)
     when "LIST"
       elements = Array.new(list_length(node)) do |index|
         @path.push(index)
-        element = type_value(type.of_type, node, selections)
+        element = type_value(type.of_type, node, selections, coordinate:)
         @path.pop
         element
       end
@@ -370,23 +551,35 @@ class GraphWeaver::Testing::FakeClient
       end
       elements
     else
-      return if !non_null && rng.rand < @null_chance
-
-      core_value(type, node, selections)
+      core_value(type, node, selections, coordinate)
     end
   end
 
-  def core_value(type, node, selections)
+  # A pin keyed by a concrete type name says what an object of that type is,
+  # wherever the query reaches one — at a union or interface, that is the
+  # member the walk landed on, so the pin never has to disambiguate.
+  def composite_value(type, selections)
+    name = type.graphql_name
+    return object_value(type, selections) unless @overrides.key?(name)
+
+    pinned_object(type, selections, GraphWeaver::Internal::Overrides.resolve(@overrides[name], rng), name)
+  end
+
+  # the scalar-type pin lives in Values, which the cassette anonymizer
+  # shares; the enum one has no second reader
+  def core_value(type, node, selections, coordinate = nil)
     case type.kind.name
     when "SCALAR"
-      @values.scalar(type.graphql_name, node.name)
+      @values.scalar(type.graphql_name, node.name, coordinate, at: location)
     when "ENUM"
+      return GraphWeaver::Internal::Overrides.resolve(@overrides[type.graphql_name], rng) if @overrides.key?(type.graphql_name)
+
       type.values.keys.sort.sample(random: rng)
     when "OBJECT"
-      object_value(type, selections)
+      composite_value(type, selections)
     when "UNION", "INTERFACE"
       member = @schema.possible_types(type).sort_by(&:graphql_name).sample(random: rng)
-      object_value(member, selections)
+      composite_value(member, selections)
     else
       raise NotImplementedError, "cannot fake kind: #{type.kind.name}"
     end

data/lib/graph_weaver/testing/fake_subgraph.rb

@@ -46,17 +46,21 @@ module GraphWeaver
       # resolvers here to receive one.
       def execute(query, variables: {}, operation_name: nil, context: nil)
         document = GraphQL.parse(query)
-        entities = entities_field(document)
+        operation = document.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
+        entities = entities_field(operation)
         return @client.execute(query, variables:, operation_name:) unless entities
 
-        { "data" => { "_entities" => entities_value(entities, document, variables) } }
+        failures = []
+        value = entities_value(entities, document, operation, variables, failures)
+        response = { "data" => { "_entities" => value } }
+        response["errors"] = failures unless failures.empty?
+        response
       end
 
       private
 
       # the router sends _entities as the operation's only root field
-      def entities_field(document)
-        operation = document.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
+      def entities_field(operation)
         operation&.selections&.find do |node|
           node.is_a?(GraphQL::Language::Nodes::Field) && node.name == "_entities"
         end
@@ -64,15 +68,22 @@ module GraphWeaver
 
       # one object per representation, in order and as the type it names —
       # which is the contract _entities answers on
-      def entities_value(field, document, variables)
+      def entities_value(field, document, operation, variables, failures)
         fragments = document.definitions
           .grep(GraphQL::Language::Nodes::FragmentDefinition).to_h { |node| [node.name, node] }
 
-        representations(variables).map do |representation|
+        representations(variables).each_with_index.map do |representation, index|
           type_name = representation["__typename"] or raise GraphWeaver::Error,
-            "a representation sent to #{@name} carries no __typename: #{representation.inspect}"
+            "a representation sent to #{@name} carries no __typename: " \
+              "#{GraphWeaver::Internal::Log.filter_variables(representation).inspect}"
 
-          @client.object(type_name, field.selections, fragments:)
+          here = []
+          object = @client.object(type_name, field.selections, fragments:, variables:, operation:,
+            failures: here)
+          # rooted where the fetch put it, which is how the router maps an
+          # entity error back onto the caller's path
+          here.each { |error| failures << error.merge("path" => ["_entities", index] + error["path"]) }
+          object
         end
       end