graph_weaver 0.4.4 → 0.5.0

data/lib/graph_weaver/testing/fake_client.rb

@@ -4,11 +4,13 @@
 require "graphql"
 require "json"
 
+require_relative "../parsing"
+
 # A fake client that fabricates schema-correct responses for whatever query
 # arrives — the zero-setup way to test code built on generated modules:
 #
-#      fake = GraphWeaver::Testing::FakeClient.new(schema:)
-#      result = PersonQuery.execute!(id: "1", fake — positionally)
+#      fake = GraphWeaver::Testing::FakeClient.new
+#      result = PersonQuery.execute!(client: fake, id: "1")
 #      result.person.name  # => a plausible String, typed and castable
 #
 # Values are type-correct by construction (real enum values, valid
@@ -18,15 +20,33 @@ require "json"
 #
 # overrides: pin fields by GraphQL name — schema vocabulary, so keys
 # survive query refactors. "Type.field" beats "field"; values are
-# literals or zero-arg procs. (An override with a wrong-typed value is
-# also the way to simulate a corrupt payload — casting raises
-# GraphWeaver::TypeError.)
+# 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.)
 #
 #      FakeClient.new(schema:, overrides: {
 #        "Person.name" => "Daniel",
 #        "email" => -> { "test@example.com" },
 #      })
 #
+# 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
+# orders, the first one paid" is the literal thing you write:
+#
+#      FakeClient.new(schema:, overrides: {
+#        "Reader.name" => "Ada",
+#        "Reader.orders" => [{ "status" => "PAID" }, {}],
+#      })
+#
+# Keys inside a pinned subtree 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.
+#
+# requests: every execute, in order ({ query:, variables:, operation_name: })
+# — "did we send the right variables", and "did we call it at all".
+#
 # Partial failures: fail_at simulates a field-level error with
 # spec-correct null propagation — the field's error lands in the errors
 # array (with its concrete path), the field becomes null, and nulls
@@ -45,19 +65,39 @@ require "json"
 #
 #      FakeClient.new(schema:, corrupt: "Person.birthday")
 #
-# seed: makes a run reproducible (also seeds faker). Per-instance options
-# fall back to GraphWeaver::Testing.config.
+# seed: makes a run reproducible (also seeds faker). Every option,
+# schema: included, falls 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
 
   # sentinel: a simulated failure bubbling up to the nearest nullable spot
   NULL_BUBBLE = Object.new.freeze
 
-  def initialize(schema:, overrides: {}, seed: nil, mode: nil, list_size: nil, null_chance: nil,
+  # sentinel: no override here — distinct from an override OF nil, which
+  # pins the field null
+  UNPINNED = Object.new.freeze
+  private_constant :UNPINNED
+
+  # the schema responses are fabricated against — the way to reach it from
+  # a graphql: :fake spec, where GraphWeaver.client is one of these
+  attr_reader :schema
+
+  # Every execute, in order: { query:, variables:, operation_name: }.
+  #
+  #      expect(fake.requests.size).to eq 1          # memoized, then
+  #      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)
     config = GraphWeaver::Testing.config
-    @schema = schema
+    @schema = 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
@@ -65,14 +105,32 @@ class GraphWeaver::Testing::FakeClient
     @extra_errors = wrap(errors).map { |error| normalize_error(error) }
     @fail_at = wrap(fail_at).map { |spec| normalize_fail_spec(spec) }
     @corrupt = wrap(corrupt)
+    @requests = []
   end
 
-  def execute(query, variables: {})
+  # operation_name: is accepted for contract parity and ignored — one
+  # document holds one operation, so there is nothing to select between
+  # (see Selection#load_operation).
+  def execute(query, variables: {}, operation_name: nil)
+    # recorded before validation: "we never called it" and "we called it with
+    # a query that doesn't compile" are different failures
+    @requests << { query:, variables:, operation_name: }.freeze
+
+    # Validate first, as the other clients in the slot do: a field the schema
+    # doesn't have would otherwise walk into `get_field(...).type` on nil, and
+    # a NoMethodError from inside the fabricator is undiagnosable next to the
+    # "Did you mean" a real server gives. This is the commonest mistake there
+    # is — a query drifting ahead of the dump, or a typo in an ad-hoc one.
+    invalid = @schema.validate(GraphQL.parse(query))
+    return { "data" => nil, "errors" => invalid.map(&:to_h) } if invalid.any?
+
     operation = load_operation(query)
     root_type = operation_root_type(operation)
 
     @path = []
     @failures = []
+    # fail_at fires once per execute, not once per client lifetime
+    @fail_at.each { |spec| spec.delete("triggered") }
     data = object_value(root_type, operation.selections)
     data = nil if data.equal?(NULL_BUBBLE) # total propagation, like a real server
 
@@ -82,6 +140,27 @@ class GraphWeaver::Testing::FakeClient
     response
   end
 
+  # One fabricated object of `type_name` for these selections — the seam
+  # {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: {})
+    type = @schema.get_type(type_name) or
+      raise GraphWeaver::Error, "#{type_name} is not a type of this schema"
+
+    @fragments = fragments
+    @path = []
+    @failures = []
+    value = object_value(type, selections)
+    value.equal?(NULL_BUBBLE) ? nil : value
+  end
+
+  # The Selection mixin's walk is machinery, not interface: a developer who
+  # types `.methods` on a fake should find execute, schema, requests, object
+  # and parse, not the twelve steps behind them.
+  private :load_operation, :operation_root_type, :each_field, :gather,
+    :gather_conditional, :applies?, :conditional?
+
   private
 
   def rng = @values.rng
@@ -102,11 +181,24 @@ class GraphWeaver::Testing::FakeClient
     spec.is_a?(String) ? { "path" => spec } : JSON.parse(JSON.generate(spec))
   end
 
-  def object_value(type, selections)
+  # pins: the response keys an override pinned at this object, merged in as
+  # the walk reaches them — everything it doesn't name is fabricated.
+  def object_value(type, selections, pins: nil, source: nil)
+    # gather (not each_field) so a field selected twice — `a { x } a { y }` —
+    # fabricates the MERGED shape codegen's struct expects, not last-writer-wins
+    fields = gather(type, selections)
+    check_pins!(fields, pins, source) if pins
+
     result = {}
-    each_field(type, selections) do |key, node|
+    fields.each do |key, nodes|
+      node = nodes.first
+      pin = (pins && pins.key?(key)) ? pins[key] : UNPINNED
       @path.push(key)
-      value = node.name == "__typename" ? type.graphql_name : field_value(type, node)
+      value = if node.name == "__typename"
+        type.graphql_name
+      else
+        field_value(type, node, nodes.flat_map(&:selections), pin, source)
+      end
       @path.pop
 
       if value.equal?(NULL_BUBBLE)
@@ -127,7 +219,7 @@ class GraphWeaver::Testing::FakeClient
     @schema.get_field(type.graphql_name, node.name).type.kind.name == "NON_NULL"
   end
 
-  def field_value(parent_type, node)
+  def field_value(parent_type, node, selections, pin = UNPINNED, source = nil)
     if (spec = matching_failure)
       @failures << {
         "message" => spec["message"] || "simulated failure",
@@ -138,19 +230,92 @@ class GraphWeaver::Testing::FakeClient
       return NULL_BUBBLE
     end
 
-    override = @overrides.fetch("#{parent_type.graphql_name}.#{node.name}") do
-      @overrides[node.name]
+    coordinate = "#{parent_type.graphql_name}.#{node.name}"
+    if pin.equal?(UNPINNED)
+      # most specific key wins; #fetch (not #[]) so an override OF nil pins null
+      pin = @overrides.fetch(coordinate) { @overrides.fetch(node.name, UNPINNED) }
+      source = @overrides.key?(coordinate) ? coordinate : node.name unless pin.equal?(UNPINNED)
     end
-    return override.is_a?(Proc) ? override.call : override unless override.nil?
 
     field_type = @schema.get_field(parent_type.graphql_name, node.name).type
-    if @corrupt.include?("#{parent_type.graphql_name}.#{node.name}")
-      return corrupt_value(field_type)
+    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)
+  end
+
+  # What an override pins here. A leaf takes the value outright; a composite
+  # MERGES — the keys it names are pinned and the rest of the selection is
+  # 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)
+
+    case type.kind.name
+    when "NON_NULL" then pinned_value(type.of_type, node, selections, value, source)
+    when "LIST"
+      return value unless value.is_a?(Array)
+
+      value.each_with_index.map do |element, index|
+        @path.push(index)
+        begin
+          pinned_value(type.of_type, node, selections, element, source)
+        ensure
+          @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:)
+    else
+      value
+    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"]
+    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?
+
+      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\"."
     end
 
-    type_value(field_type, node)
+    found = members.find { |member| member.graphql_name == named }
+    return found if found
+
+    raise GraphWeaver::Error, "override #{source.inspect} pins __typename #{named.inspect} at " \
+      "#{location}, where the query can only return #{members.map(&:graphql_name).sort.join(" or ")}"
+  end
+
+  # A pinned key the query doesn't select would fabricate the field anyway
+  # and quietly leave the pin unread — the same silent-green failure a typo'd
+  # coordinate is validated against, one level down.
+  def check_pins!(fields, pins, source)
+    # __typename in a pin names the type to fabricate (see #pinned_type); it
+    # is an instruction, not a field the query has to have selected
+    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)
+    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, " \
+      "exactly as they arrive on the wire (#{fields.keys.join(", ")})."
   end
 
+  # where the walk is, for a message: "reader.orders.0"
+  def location = @path.empty? ? "the root" : @path.join(".")
+
   # a value casting can't accept, derived from the field's own type — and
   # wrapped per list layer so the corruption lands on the element cast
   def corrupt_value(type)
@@ -181,17 +346,18 @@ class GraphWeaver::Testing::FakeClient
     argument = node.arguments.find { |arg| %w[first last limit].include?(arg.name) }
     return argument.value if argument && argument.value.is_a?(Integer)
 
-    rng.rand(@list_size)
+    # 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, non_null: false)
+  def type_value(type, node, selections, non_null: false)
     case type.kind.name
     when "NON_NULL"
-      type_value(type.of_type, node, non_null: true)
+      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)
+        element = type_value(type.of_type, node, selections)
         @path.pop
         element
       end
@@ -206,21 +372,21 @@ class GraphWeaver::Testing::FakeClient
     else
       return if !non_null && rng.rand < @null_chance
 
-      core_value(type, node)
+      core_value(type, node, selections)
     end
   end
 
-  def core_value(type, node)
+  def core_value(type, node, selections)
     case type.kind.name
     when "SCALAR"
       @values.scalar(type.graphql_name, node.name)
     when "ENUM"
       type.values.keys.sort.sample(random: rng)
     when "OBJECT"
-      object_value(type, node.selections)
+      object_value(type, selections)
     when "UNION", "INTERFACE"
       member = @schema.possible_types(type).sort_by(&:graphql_name).sample(random: rng)
-      object_value(member, node.selections)
+      object_value(member, selections)
     else
       raise NotImplementedError, "cannot fake kind: #{type.kind.name}"
     end

data/lib/graph_weaver/testing/fake_subgraph.rb

@@ -0,0 +1,85 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+require_relative "fake_client"
+
+module GraphWeaver
+  module Testing
+    # A subgraph this process doesn't serve, answered with fabricated data.
+    #
+    # Composed into the supergraph but routed to another service, a subgraph
+    # has no schema class here, so by default {Router} refuses any query that
+    # reaches its fields. `subgraphs: { "reviews" => :fake }` swaps that
+    # refusal for schema-correct fabricated data — mid-migration that's often
+    # what you want: the fields exist, the shapes are right, and nothing has
+    # to be stood up to exercise the rest of the graph.
+    #
+    # It satisfies the same contract every other subgraph does, including the
+    # `_entities(representations:)` fetch a boundary crossing sends. Each
+    # representation names its own `__typename`, so the entity comes back as
+    # that type — a `_Entity` union faked the ordinary way would answer as a
+    # random member and match nothing the query asked for.
+    #
+    # Fabricated data is invented data, and a green test against invented
+    # data is worse than a red one — so {Router} marks every fetch that came
+    # from here (`faked: true` in #trace) and logs it at :warn.
+    class FakeSubgraph
+      # the subgraph being faked, as the supergraph names it
+      attr_reader :name
+
+      # the schema responses are fabricated against — the composed API
+      # schema, which carries every type this subgraph can be asked for
+      attr_reader :schema
+
+      def initialize(name, schema, **options)
+        @name = name
+        @schema = schema
+        @client = FakeClient.new(schema:, **options)
+      end
+
+      def inspect = "#<#{self.class.name} #{@name.inspect}>"
+      alias to_s inspect
+
+      # context: is accepted for contract parity and ignored — there are no
+      # resolvers here to receive one.
+      def execute(query, variables: {}, operation_name: nil, context: nil)
+        document = GraphQL.parse(query)
+        entities = entities_field(document)
+        return @client.execute(query, variables:, operation_name:) unless entities
+
+        { "data" => { "_entities" => entities_value(entities, document, variables) } }
+      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
+        operation&.selections&.find do |node|
+          node.is_a?(GraphQL::Language::Nodes::Field) && node.name == "_entities"
+        end
+      end
+
+      # 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)
+        fragments = document.definitions
+          .grep(GraphQL::Language::Nodes::FragmentDefinition).to_h { |node| [node.name, node] }
+
+        representations(variables).map do |representation|
+          type_name = representation["__typename"] or raise GraphWeaver::Error,
+            "a representation sent to #{@name} carries no __typename: #{representation.inspect}"
+
+          @client.object(type_name, field.selections, fragments:)
+        end
+      end
+
+      def representations(variables)
+        found = variables.to_h.transform_keys(&:to_s)["representations"]
+        (found || []).map { |representation| representation.to_h.transform_keys(&:to_s) }
+      end
+    end
+  end
+end