graph_weaver 0.6.1 → 0.7.0

data/lib/graph_weaver/internal.rb

@@ -47,6 +47,9 @@ module GraphWeaver
           DidYouMean::SpellChecker.new(dictionary: dictionary).correct(term).first
         end
 
+        # "a" or "an" for a word an error message is about to name.
+        def article(word) = word.downcase.start_with?(/[aeiou]/) ? "an" : "a"
+
         # The module a .graphql file generates, and the basename of the file
         # it generates into: the camelized file name plus the operation's own
         # word.
@@ -67,6 +70,30 @@ module GraphWeaver
         # just the module name — see generated_names
         def module_name(path, source) = generated_names(path, source).first
 
+        # The one sentence about scalars nothing registered — said on the
+        # logger per parse and once per run by the build, and worth saying
+        # identically in both. Keyed by graph name (nil for an app with no
+        # declared graphs): a registration is scoped to one graph, so merging
+        # the names across several would read as "forgotten everywhere" for a
+        # scalar registered for one of them and forgotten for the next.
+        def untyped_scalars_report(by_graph)
+          found = by_graph.reject { |_, names| names.empty? }
+          return if found.empty?
+
+          advice = "(register with GraphWeaver.register_scalar)"
+          # One graph ran, so there is nothing to attribute — including when it
+          # is the only one with findings is what made a forgetful graph read
+          # as a forgetful app.
+          if by_graph.one?
+            names = found.values.first.sort
+            return "#{names.size} unregistered custom scalar#{"s" unless names.one?} → T.untyped: " \
+              "#{names.join(", ")} #{advice}"
+          end
+
+          ["unregistered custom scalars → T.untyped #{advice}:",
+            *found.map { |graph, names| "  graph #{graph.inspect}: #{names.sort.join(", ")}" }].join("\n")
+        end
+
         # A path setting, as a real path: relative to GraphWeaver.root, which
         # is the app root and not wherever the process was started. Every
         # filesystem access on a configured path goes through here; the
@@ -85,12 +112,95 @@ module GraphWeaver
           path.start_with?(prefix) ? path.delete_prefix(prefix) : path
         end
 
+        # The registrations a schema generates with: the graph that named it,
+        # or the default graph's. The testing fakes ask, so a fabricated
+        # scalar is the shape the module generated against that schema will
+        # cast — a `Money` registered for one graph is not a `Money` for the
+        # next one along. Matched on the schema class a graph runs in-process,
+        # which is the only identity cheap enough to ask per fake; anything
+        # else falls back to the default, which is where a single-schema app
+        # has always read from.
+        def registry_for(schema) = graph_for(schema)&.registry || Codegen.registry
+
+        # The declared graph that runs `schema` in-process, or nil. Matched on
+        # the schema class a graph runs, which is the only identity cheap
+        # enough to ask per call — a dump would have to be re-read, and
+        # re-reading it gives a different object every time. GraphWeaver.parse
+        # asks too, to bake the GRAPH a generated file would have carried.
+        def graph_for(schema)
+          schema && GraphWeaver.graphs.find { |candidate| candidate.live_schema.equal?(schema) }
+        end
+
+        # Where generated modules are READ from: the configured patterns, plus
+        # any graph writing somewhere they don't already cover. generated_paths'
+        # default glob (app/graphql/*/generated) covers the conventional layout,
+        # so listing a graph's output as well would name the same directory
+        # twice — in the log, and in the globbing.
+        #
+        # FNM_PATHNAME because Dir.glob is what expands these patterns
+        # everywhere else (Zeitwerk's ignore, load_generated!) and its * stops
+        # at a /. Without it app/graphql/*/generated "covered"
+        # app/graphql/a/b/generated, which was then neither ignored nor loaded.
+        def generated_dirs
+          extra = GraphWeaver.graphs.map(&:output).reject do |dir|
+            GraphWeaver.generated_paths.any? do |pattern|
+              File.fnmatch?(resolve(pattern), resolve(dir), File::FNM_PATHNAME)
+            end
+          end
+          GraphWeaver.generated_paths | extra
+        end
+
         # Every query document under these directories, sorted — the files
         # generate!, verify_generated!, check_queries and load_queries! read.
         def query_files(paths = GraphWeaver.queries_paths)
           Array(paths).flat_map { |dir| Dir[File.join(resolve(dir), Codegen::DOCUMENT_GLOB)].sort }
         end
 
+        # Anywhere GraphWeaver takes schema:, a Client stands for its schema — so
+        # the console object and the rake task point at the same thing. A path
+        # (String or Pathname) or SDL loads like it does everywhere else in the
+        # library; without that it reached `schema.validate` as itself and failed
+        # as `undefined method 'validate' for an instance of String`.
+        def schema_for(source)
+          return source.schema if source.is_a?(Client)
+          return SchemaLoader.load(source) if source.is_a?(String) || source.respond_to?(:to_path)
+
+          source
+        end
+
+        # Whether this source carries the @join__* routing table, i.e. is a
+        # composed supergraph rather than an API schema. The one place that
+        # asks: Graph#supergraph reads it per graph, Testing::Config for the
+        # app-wide fallbacks, and the federation rake tasks through both.
+        #
+        # Kept per source for the life of the process — parsing a supergraph
+        # is milliseconds and :wire asks per example — and keyed on what the
+        # file IS, since the answer is a property of its content. A supergraph
+        # recomposed at a stable path (a `before` hook, chained rake tasks)
+        # used to be answered from the previous composition, which routed a
+        # graph into the wrong plan or refused it as being in none.
+        def composed?(source)
+          @composed ||= {}
+          key = composed_key(source)
+          return @composed[key] if @composed.key?(key)
+
+          @composed[key] = begin
+            SchemaLoader.routing_table?(source)
+          rescue GraphWeaver::Error
+            # a source that can't even be read is in no supergraph either —
+            # and that Error is worth its warn line, where "not federated"
+            # never was
+            false
+          end
+        end
+
+        # the conventional schema dump, required
+        def locate_schema!
+          SchemaLoader.locate or raise GraphWeaver::Error,
+            "no schema dump at #{GraphWeaver.schema_path} (.json/.graphql/.gql) — pass schema:, " \
+            "or cache one: GraphWeaver.new(url, cache: true).schema"
+        end
+
         # The graphql-ruby schema class the app default executes against,
         # when it runs in-process — a Client wrapping one, or the class in
         # the slot bare. nil for every network client. Not memoized: in dev
@@ -104,8 +214,32 @@ module GraphWeaver
           target if target.is_a?(Class) && target <= GraphQL::Schema
         end
 
+        # The context to hand resolvers. A proc is answered from a request's
+        # headers (Testing::Endpoint resolves it), so off the wire there is
+        # nothing to answer it with — and a Proc reaching graphql-ruby as a
+        # context fails far from the line that set it.
+        def context!(context)
+          return context unless context.respond_to?(:call)
+
+          raise GraphWeaver::Error, "context: is a proc, so it is answered from a request's " \
+            "headers — and nothing here made a request. Tag the example graphql: :wire, which " \
+            "serves your resolvers at your client's endpoint so your transport's headers reach " \
+            "them; off the wire, pass the hash."
+        end
+
         private
 
+        # What makes a composed? answer stale. Both callers pass a path that
+        # exists, so the file's identity is its stat — size as well as mtime,
+        # because a coarse mtime can miss two writes in one tick. Anything
+        # that isn't a path (SDL, a class) is its own key.
+        def composed_key(source)
+          stat = File.stat(source.to_s)
+          [source.to_s, stat.mtime, stat.size]
+        rescue SystemCallError
+          source
+        end
+
         # "Mutation" for a mutation document, "Query" for everything else.
         def operation_suffix(source)
           operation = GraphQL.parse(source).definitions
@@ -142,7 +276,7 @@ module GraphWeaver
         # JSON round-trip so symbol keys become strings — otherwise
         # YAML.dump writes Ruby symbols the safe loader rejects on the next
         # run, and lookup keys stay stable across processes
-        def normalize_variables(variables) = JSON.parse(JSON.generate(variables || {}))
+        def normalize_variables(variables) = JSON.parse(Wire.json(variables || {}))
 
         # one readable line: an error naming a 60-line query is a wall, not a hint
         def summarize(query, limit: 160)
@@ -157,6 +291,54 @@ module GraphWeaver
     # carries an error in. Lived on Transport and Router, both of which
     # users touch — the worst place for it.
     module Wire
+      # JSON for the wire, or the caller's bug named under the umbrella: a
+      # value with no JSON form (NaN, Infinity, binary) raised a raw JSON::
+      # error from wherever it was first encoded — the transport, a cassette
+      # key, a log line — so every encoder goes through here.
+      def self.json(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError => e
+        raise GraphWeaver::Error, "variables are not JSON-serializable: #{e.message}"
+      end
+
+      # The half of that discipline JSON doesn't raise for. JSON.generate
+      # carries a String, a number, a boolean, null, a list and an object;
+      # anything else it renders as the value's #to_s — right for a Date or
+      # a Symbol, a memory address for a File, which then sits in the
+      # server's database looking like it meant something. So a variable
+      # whose #to_s is Ruby's debug form, or that is a stream whose bytes
+      # JSON can't carry at all, is refused before the body is built.
+      def self.check_variables!(variables)
+        variables&.each { |name, value| check_variable!(name.to_s, value) }
+      end
+
+      def self.check_variable!(path, value)
+        case value
+        when Hash then value.each { |key, nested| check_variable!("#{path}.#{key}", nested) }
+        when Array then value.each_with_index { |nested, i| check_variable!("#{path}[#{i}]", nested) }
+        when String, Symbol, Numeric, true, false, nil then nil
+        else
+          raise GraphWeaver::Error, variable_refusal(path, value) if value.respond_to?(:read) ||
+            value.to_s.start_with?("#<")
+        end
+      end
+      private_class_method :check_variable!
+
+      # A stream and an anonymous object fail the same way and need different
+      # next steps: one is a feature this client doesn't have, the other is a
+      # value that never said what it is.
+      def self.variable_refusal(path, value)
+        if value.respond_to?(:read)
+          "$#{path} is a #{value.class} — graph_weaver posts application/json and doesn't implement " \
+            "the GraphQL multipart request spec, so a file can't ride along; send what the server " \
+            "expects as JSON, or POST the upload with your own transport"
+        else
+          "$#{path} is a #{value.class}, which has no JSON form — it would go on the wire as " \
+            "#{value.to_s.inspect}; send a String, a number, a boolean, a list, or an object"
+        end
+      end
+      private_class_method :variable_refusal
+
       # The name of the document's FIRST operation, nil when anonymous. Only
       # the fallback for a raw query string handed straight to a transport —
       # generated modules pass their OPERATION_NAME, parsed properly.

data/lib/graph_weaver/log_subscriber.rb

@@ -0,0 +1,66 @@
+# typed: ignore — ActiveSupport::LogSubscriber, which sorbet can't resolve here
+# frozen_string_literal: true
+
+module GraphWeaver
+  # One line per GraphQL operation in a Rails log, the shape ActiveRecord
+  # uses for a query:
+  #
+  #      GraphWeaver PersonQuery (12.3ms) ok
+  #      GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
+  #      GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+  #      GraphWeaver billing/InvoicesQuery (12.3ms) ok
+  #
+  # Attached by the railtie wherever ActiveSupport is, and fed by the
+  # instrumenter it sets. Requires ActiveSupport — `require` this yourself
+  # only if you subscribe by hand.
+  #
+  # **One rule decides which line you get: the summary is info, the wire is
+  # debug.** This is the only GraphWeaver line at info, so a production log
+  # gets one per operation and nothing that could carry PII; turning
+  # GraphWeaver.logger up to debug adds the query, the variables and the
+  # response *beneath* it rather than repeating it.
+  #
+  # It writes through GraphWeaver.logger rather than Rails.logger, so
+  # `GraphWeaver.logger = nil` — the documented way to silence the gem —
+  # silences this too, and the line carries the same `graph_weaver`
+  # progname as every other one.
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    # attach_to(:graph_weaver) subscribes "#{method}.graph_weaver" and
+    # ActiveSupport::Subscriber#call dispatches on the name up to the first
+    # dot — so this method name is EXECUTE_EVENT's first half, both ways.
+    def execute(event)
+      payload = event.payload
+
+      GraphWeaver::Internal::Log.log(:info) do
+        # duration_ms is the instrumenter's own measurement; event.duration
+        # covers a subscriber attached to something that didn't set it
+        ms = payload[:duration_ms] || event.duration
+        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
+      end
+    end
+
+    # GraphWeaver's logger, not Rails' — LogSubscriber#call skips a
+    # subscriber whose logger is nil, which is what makes the gem's own
+    # opt-out reach this line too.
+    def logger = GraphWeaver.logger
+
+    private
+
+    # What ran: the operation, prefixed by its graph when the request carried
+    # one — an app with several graphs reads `billing/InvoicesQuery` without
+    # a second line shape to learn, and one with a single graph never sees it.
+    def subject(payload)
+      operation = payload[:operation] || "query"
+      payload[:graph] ? "#{payload[:graph]}/#{operation}" : operation
+    end
+
+    # status, then whatever narrows it: the error class, the code an alert
+    # groups by, and which attempt this was when a Retry is in the stack.
+    def outcome(payload)
+      parts = [payload[:status], payload[:error]]
+      parts << "[#{payload[:code]}]" if payload[:code]
+      parts << "(retry #{payload[:retries]})" if payload[:retries].to_i.positive?
+      parts.compact.join(" ")
+    end
+  end
+end

data/lib/graph_weaver/logging.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require "json"
+
 module GraphWeaver
   class << self
     # Where GraphWeaver narrates what it's doing — anything
@@ -43,18 +45,20 @@ module GraphWeaver
 
     # One callable wrapping every request GraphWeaver makes — over the
     # wire or in-process — so an APM can time it and count errors. A
-    # no-op until you set one:
+    # no-op until you set one (Rails sets this one for you):
     #
     #      GraphWeaver.instrumenter = lambda do |event, payload, &block|
     #        ActiveSupport::Notifications.instrument(event, payload, &block)
     #      end
     #
-    # It must call the block and return its value. The only event today
-    # is EXECUTE_EVENT; its payload carries :url (nil in-process),
-    # :schema (in-process only), :operation (the document's operation
-    # name, nil for an anonymous one), and — added after the response
-    # lands — :status. Never the query text or the variables: those
-    # carry PII and belong at debug on the logger, where they're gated.
+    # It must call the block and return its value. The only event today is
+    # EXECUTE_EVENT; its payload is the contract in docs/logging.md —
+    # :operation, :client, :status, :duration_ms, :graph always;
+    # :url/:http_status over the wire, :schema in-process, :error/:code on a
+    # failure, :retries when a Retry wrapped it. Never the query text or the
+    # variables: the payload fans out to subscribers that know none of the
+    # filtering rules, so PII belongs at debug on the logger, where the
+    # level gates it and filter_parameters scrubs it.
     attr_accessor :instrumenter
   end
 
@@ -77,6 +81,30 @@ module GraphWeaver
         # wrote can spell a value any way, so for a filtered key none of it
         # survives, not the parts that would have been safe.
         def detail(key, detail) = filtered?(key) ? FILTERED : detail
+
+        # A value the library reports as DATA rather than inside a sentence —
+        # InputError#value. Scrubbed at every depth, so a filtered key nested
+        # inside an input object is covered too, and the same list decides it
+        # as decides the debug log's variables line.
+        def value(key, value) = Log.filter_variables({ key.to_s => value })[key.to_s]
+
+        # A value the library spells INTO a sentence. `detail` can only ask
+        # about the key the value arrived under, so it reads a filtered key one
+        # level in as safe; this scrubs at every depth, like #value. The key is
+        # optional because a coercer refusing a value hasn't been told one.
+        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(value(key, raw).inspect)
+
+        # Text the library didn't author — a value a caller sent, a sentence a
+        # server wrote — cut to what an error may carry. The number lives on
+        # InputError, which is the class that documents it and the one every
+        # capped string reaches.
+        def cap(text)
+          limit = GraphWeaver::InputError::VALUE_LIMIT
+          return text if text.bytesize <= limit
+
+          # byteslice can land mid-character; scrub drops the partial tail
+          "#{text.byteslice(0, limit).scrub("")}…(#{text.bytesize - limit} more bytes)"
+        end
       end
     end
   end
@@ -91,14 +119,23 @@ module GraphWeaver
   self.filter_parameters = DEFAULT_FILTER_PARAMETERS
 
   # The one instrumentation event: a single GraphQL request, start to
-  # parsed response, whichever client slot served it.
-  EXECUTE_EVENT = "graph_weaver.execute"
+  # parsed response, whichever client slot served it. `<event>.<namespace>`
+  # is how every notification in this ecosystem is spelled
+  # (sql.active_record, execute_multiplex.graphql) — it's what
+  # ActiveSupport::LogSubscriber.attach_to and an APM's namespace routing
+  # key on, so a backwards name made both of them a puzzle.
+  EXECUTE_EVENT = "execute.graph_weaver"
 
   module Internal
     # The emitting half of the narration the three accessors above
     # configure. Setting a logger is API; writing to it is not, and the
     # two read as a pair when they sit on the same object.
     module Log
+      # fiber-local, set only for the duration of one attempt (with_retries)
+      RETRIES = :graph_weaver_retries
+      # fiber-local, set only for the duration of one dispatch (with_graph)
+      GRAPH = :graph_weaver_graph
+
       class << self
         # Level-gated and lazy — the block only runs when a logger is
         # listening. Messages carry "graph_weaver" as progname.
@@ -118,13 +155,89 @@ module GraphWeaver
           result
         end
 
-        # Wrap the block in the instrumenter, if one is set. The payload is
-        # a plain Hash the caller may add to inside the block.
+        # Wrap the block in the instrumenter, if one is set. The caller
+        # supplies what only it knows (:url, :schema, :client); this fills
+        # in the half every path shares — how it ended, how long it took,
+        # what a Retry had already spent — so one subscriber reads one
+        # shape whichever client slot served the request.
         def instrument(event, payload)
           hook = GraphWeaver.instrumenter
           return yield unless hook
 
-          hook.call(event, payload) { yield }
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          retries = Thread.current[RETRIES]
+          payload[:retries] = retries if retries
+          payload[:graph] = Thread.current[GRAPH]
+          # pessimistic, so :status is set even for what a rescue can't
+          # see — an Interrupt, a killed thread — and never silently absent
+          payload[:status] = :failed
+
+          # One dispatch labels one request. Whatever THIS request reaches —
+          # a resolver serving it that calls out — is a request of its own,
+          # and the caller's graph would be a wrong label on it.
+          with_graph(nil) do
+            hook.call(event, payload) do
+              result = yield
+              errors = response_errors(result)
+              if errors.empty?
+                payload[:status] = :ok
+              else
+                payload[:status] = :errors
+                payload[:code] = errors.grep(Hash).filter_map { |e| GraphWeaver::GraphQLError.from_h(e).code }.first
+              end
+              result
+            rescue => e
+              payload[:error] = e.class.name
+              # the one key an alert groups by, whichever kind of failure it was
+              payload[:code] = e.status if e.is_a?(GraphWeaver::ServerError)
+              raise
+            ensure
+              payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+            end
+          end
+        end
+
+        # What a Retry has already spent, read by the attempt it is about
+        # to make. A dynamic extent rather than a global: the count is only
+        # visible while the call it describes is on the stack, so a client
+        # that never reaches instrument can't leave a stale one behind.
+        def with_retries(count)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[RETRIES]
+          Thread.current[RETRIES] = count
+          begin
+            yield
+          ensure
+            Thread.current[RETRIES] = previous
+          end
+        end
+
+        # The graph a generated module is dispatching, read by the request it
+        # is about to make. Same dynamic extent as with_retries, for the same
+        # reason — and instrument clears it for the duration of the request it
+        # labels, so exactly one request wears the label.
+        def with_graph(name)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[GRAPH]
+          Thread.current[GRAPH] = name
+          begin
+            yield
+          ensure
+            Thread.current[GRAPH] = previous
+          end
+        end
+
+        # The variables as one JSON line for a log: filtered, and unable to
+        # raise. A value with no JSON form (NaN, binary) is the caller's bug
+        # and the transport refuses it a few lines later — but a logger that
+        # decides WHICH exception a caller sees, or whether one is raised at
+        # all, is worse than a log line that says it couldn't render.
+        def variables_for_log(variables)
+          JSON.generate(filter_variables(variables))
+        rescue StandardError => e
+          "<unloggable: #{e.class}>"
         end
 
         # variables with the filtered keys blanked out
@@ -138,6 +251,17 @@ module GraphWeaver
 
         private
 
+        # The GraphQL errors a response carries, whatever answered it — a
+        # Hash from a transport, a graphql-ruby Result in-process, a fake.
+        # Never raises: an instrumenter that decides which exception a
+        # caller sees is worse than a missing tag.
+        def response_errors(result)
+          errors = result.to_h["errors"] if result.respond_to?(:to_h)
+          errors.is_a?(Array) ? errors : []
+        rescue StandardError
+          []
+        end
+
         def scrub(value, filters)
           case value
           when Hash then value.to_h { |k, v| [k, filtered?(k, filters) ? FILTERED : scrub(v, filters)] }

data/lib/graph_weaver/query_module.rb

@@ -3,6 +3,8 @@
 
 require "sorbet-runtime"
 
+require_relative "internal/test_clients"
+
 module GraphWeaver
   # Called by generated code — not semver'd for direct use.
   #
@@ -14,7 +16,8 @@ module GraphWeaver
   # those are the point.
   #
   # Resolution order, per the docs: per call → per module (`MyQuery.client =`)
-  # → the module's baked DEFAULT_CLIENT → `GraphWeaver.client`.
+  # → a test mode's stand-in (Internal::TestClients) → the module's baked
+  # DEFAULT_CLIENT → `GraphWeaver.client`.
   module QueryModule
     extend T::Sig
 
@@ -30,13 +33,36 @@ module GraphWeaver
 
     private
 
+    # The one call a generated `execute` makes: resolve the client, run this
+    # module's own operation, hand the raw response back for from_response to
+    # wrap. Here rather than emitted, so what has to BRACKET a request — the
+    # graph label today — costs nothing in every generated file, and one
+    # reading of it covers every module in the app.
+    #
+    # The constants come off the module rather than the caller: a generated
+    # `execute` already knows them, but reading them here is what makes this
+    # the whole of the call instead of three arguments' worth of it.
+    sig { params(variables: T::Hash[String, T.untyped], client: T.untyped).returns(T.untyped) }
+    def dispatch(variables, client:)
+      mod = T.unsafe(self)
+      # the graph codegen baked in, never one inferred from the client — a
+      # wrong label on a request is worse than no label
+      graph = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
+
+      GraphWeaver::Internal::Log.with_graph(graph) do
+        client_for(client).execute(mod.const_get(:QUERY), variables:,
+          operation_name: mod.const_get(:OPERATION_NAME))
+      end
+    end
+
     # The client one execute runs through: the per-call `client:`, else the
     # module's, else the app default. Checked here so a wrong one names the
     # contract and the module, rather than surfacing as a NoMethodError from
-    # inside the call.
+    # inside the call — and put through Client.instrumented, the one place a
+    # bare schema class gets the seam it has no way to carry itself.
     sig { params(override: T.untyped).returns(T.untyped) }
     def client_for(override)
-      target = override || client
+      target = GraphWeaver::Client.instrumented(override || client)
       return target if target.respond_to?(:execute)
 
       # Kernel.raise: this module is extended into another, so sorbet can't
@@ -48,9 +74,16 @@ module GraphWeaver
     # Codegen's `client:` constant, emitted as a DEFAULT_CLIENT lambda so the
     # constant it names is resolved on first use rather than at load — a
     # generated file may load before the initializer that builds the client.
+    #
+    # A test mode stands in for it: what codegen baked in is exactly what a
+    # `graphql:` tag means to replace, so a bound module is covered by the
+    # tag like every other one.
     sig { returns(T.untyped) }
     def default_client
       mod = T.unsafe(self)
+      stand_in = GraphWeaver::Internal::TestClients.for(mod)
+      return stand_in if stand_in
+
       mod.const_defined?(:DEFAULT_CLIENT, false) ? mod.const_get(:DEFAULT_CLIENT).call : GraphWeaver.client!
     end
   end