graph_weaver 0.7.0 → 0.7.2

data/docs/testing.md

@@ -3,9 +3,6 @@
 How to run a spec that executes a GraphQL query without a server — against
 fabricated data, against your own resolvers, across a federated graph, or
 through your own transport with any of those behind it.
-Setup is one require and one tag (`:wire` alone adds two test gems); the rest of
-this page is what you reach for when an example is *about* the data, the
-resolvers, or the transport.
 
 One line in your spec helper:
 
@@ -14,8 +11,8 @@ One line in your spec helper:
 require "graph_weaver/rspec"
 ```
 
-Then **one tag says what an example runs against** — on the example, or on
-the group it belongs to, since rspec metadata inherits:
+Then **one tag says what an example runs against** — on the example, or on the
+group it belongs to, since rspec metadata inherits:
 
 ```ruby
 describe "checkout", graphql: :router do
@@ -36,63 +33,47 @@ it "sends the caller tag",    graphql: :wire do … end
 | `:live` | the app's own client is the point, or this one example wants out of `config.default_mode` | whatever your client does — this is the default |
 | [cassettes](cassettes.md) | pinning a real server's exact response | must be re-recorded when the query changes |
 
-The tag installs a stand-in per graph, and every generated module of that
-graph runs against it with no per-test setup — including one generated *with*
-a baked `client:`, since that constant is exactly what the tag means to
-replace. `rspec --tag graphql:router` runs one mode's examples.
-
-**A bad variable never gets as far as a mode.** `execute` coerces the variables
-before it asks any client for anything, so a
-[client-side `InputError`](errors.md#what-an-inputerror-says-without-reading-english)
-raises the same way under every tag and under none. "Which mode do I need for
-this" has no answer there — pick `:fake`, the cheapest.
-
-**The other half is the one `:fake` can't reach.** It fabricates a
-shape-correct *success*, so your server's `validates:` rules and custom
-validators never run and nothing is ever rejected — a `:fake`-only suite has
-zero coverage of server-side refusal. Cover it with
-[`Failure.graphql(code:, extensions:)`](#simulating-failures) for the rejection
-you expect, or with `:in_process`, where the real validators do run.
+There is nothing else to set up: each mode works out what to run against per
+graph, and [refuses rather than guessing](#nothing-to-configure). The tag
+installs a stand-in per graph, and every generated module of that graph runs
+against it — including one whose graph names a `client` of its own, since that
+is exactly what the tag means to replace. `rspec --tag graphql:router`
+runs one mode's examples.
 
 **Every example has exactly one mode.** An untagged one takes
 `config.default_mode`, which is `:live` — your own client, exactly as it is —
 unless the suite sets another; and **`graphql: :live` is how one example steps
 back out** of a default the suite did set.
 
-`GraphWeaver.client` is **snapshotted before every example and restored
-after** — tagged or untagged, whatever its mode, and whatever the example did
-to it. So building your own client is a plain assignment, cleaned up like a
-tagged one:
-
-```ruby
-before { GraphWeaver.client = GraphWeaver::Testing::Failure.throttled }
-```
-
-Both at once and **the tag wins**: a mode's stand-in outranks
-`GraphWeaver.client=`, so assigning one inside a tagged example does *not*
-change what its generated modules run against — the assignment reads back,
-and the modules keep using the mode. Two things do step out of a tag, and
-`graphql: :live` steps the whole example out:
-
-```ruby
-DashboardQuery.execute!(client: GraphWeaver::Testing::Failure.throttled)  # this call
-DashboardQuery.client = GraphWeaver::Testing::Failure.throttled           # this module
-```
-
-[Client resolution](transports.md#client-resolution) has the full order.
+`GraphWeaver.client` is **snapshotted before every example and restored after**,
+whatever the example did to it, so building your own client is a plain
+assignment: `before { GraphWeaver.client = GraphWeaver::Testing::Failure.throttled }`.
+Do both at once and **the tag wins**: the assignment reads back while the modules
+keep using the mode. Two things do step out of a tag — a per-call `client:`, and
+a module [parsed](generated_modules.md#dynamic-mode) from a client of its own,
+which runs against that client
+([client resolution](transports.md#client-resolution) has the full order).
+
+**The half `:fake` can't reach** is refusal. It fabricates a shape-correct
+*success*, so your server's `validates:` rules and custom validators never run —
+a `:fake`-only suite has zero coverage of server-side rejection. Cover it with
+[`Failure.graphql(code:, extensions:)`](#simulating-failures) for the rejection
+you expect, or with `:in_process`, where the real validators do run. (A bad
+*variable* never gets as far as a mode: `execute` coerces before it asks any
+client for anything, so a
+[client-side `InputError`](errors.md#what-an-inputerror-says-without-reading-english)
+raises the same way under every tag and under none.)
 
 Everything here is a *client* — the one interface queries run through (the
-contract is in [transports](transports.md)). Fakes, the router, failures and
-cassettes all slot in wherever a real transport would, so they work outside
-rspec too (`require "graph_weaver/testing"` — never from production code).
-Outside the tags there's no `GraphWeaver.client` to lean on, so parse from
-the fake or the router itself — anything holding a schema parses against it,
-and the module runs on what parsed it:
+contract is in [transports](transports.md)) — so fakes, the router, failures and
+cassettes work outside rspec too (`require "graph_weaver/testing"`, never from
+production code). There's no `GraphWeaver.client` to lean on there, so parse from
+the fake or the router itself: anything holding a schema parses, and the module
+runs on what parsed it.
 
 ```ruby
 router = GraphWeaver::Testing::Router.new(supergraph: "app/graphql/supergraph.graphql")
 DashboardQuery = router.parse("query Dashboard { me { username } }")
-DashboardQuery.execute!.me.username
 ```
 
 Every mode, tagged and running end to end, is
@@ -100,166 +81,33 @@ Every mode, tagged and running end to end, is
 [`spec/wire_mode_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/wire_mode_spec.rb) for `:wire`) — the
 reference for anything this page leaves out.
 
-## Nothing to configure
-
-Each mode works out what to run against **per graph** — with more than one, the
-honest answer varies per module — and **refuses, naming what it looked for,
-rather than guessing**:
-
-- **the schema** is `config.schema` if you set one, else the one that
-  [graph](getting_started.md#more-than-one-schema) names, else the committed
-  dump at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks
-  to. A fake reads the scalar registrations of the graph it is answering, so it
-  invents the wire value that graph's generated cast expects. (Pins and
-  `overrides:` stay suite-wide, keyed by scalar name — one `"Money"` override
-  for the run.)
-- **`:in_process`** needs the live schema *class*, since only that has
-  resolvers: the one that graph names, else the one your client already runs
-  in-process, else the loaded class that defines everything the schema
-  declares — the same derive-verify-refuse rule that
-  [maps subgraphs](federation.md#which-schema-serves-which-subgraph).
-- **`:router`** plans against the composed supergraph **that graph** names,
-  else `config.router = { supergraph: … }`, else the committed dump when
-  *that* carries `@join__*` markers — which for a federated app is usually no
-  config at all. A graph that is in no supergraph is refused **by name**,
-  rather than planned against another graph's. A client can't stand in for
-  one: a client's schema is the API schema the router serves, with the
-  `@join__*` routing table stripped out. Subgraphs are derived either way.
-
-**The helpers say which graph they mean.** `graphql_fake`,
-`graphql_in_process` and `graphql_router` are the stand-in for the modules of
-the graph their schema names — for your only graph when they name none — and
-they refuse, naming your graphs, when there is none they could reach:
-
-```ruby
-graphql_fake("Product.name" => "Ada's Book", schema: Catalog::Schema)
-graphql_in_process(Accounts::Schema)
-```
-
-So configure only to override a derivation, or to tune fabricated values — in
-the same file as the require, since support files load in sorted order and one
-naming `GraphWeaver::Testing` before it dies on `NameError`:
-
-```ruby
-GraphWeaver::Testing.configure do |config|
-  # config.schema = MySchema         # the live class, rather than the dump
-  # config.router = { supergraph: Rails.root.join("supergraph.graphql") }
-  # config.router = { subgraphs: { "reviews" => :fake } }   # either key alone
-  # config.context = { tenant: }     # baseline context every example starts from
-  # config.default_mode = :fake      # what an UNtagged example runs against;
-  #                                  # :live (the default) leaves your client
-  #                                  # alone, and graphql: :live opts one out
-  # config.seed = 4242               # defaults to rspec's own --seed
-  # config.overrides = { "Money" => "12.00", "Person.name" => "Daniel" }
-  # config.list_size = 1..3
-end
-```
-
-`list_size` is how long an **unbounded** list is — an Integer exactly that
-many, a Range randomized within it, or a Hash saying it per list (below). A
-list with a `first:`/`last:`/`limit:` argument is that long instead, whatever
-this says.
-
-**Every list the fabricator reaches reads the same setting, so nested lists
-multiply.** A query selecting `rows { owner { … } tags }` with `tags`
-uncapped fabricates `list_size` rows and `list_size` tags *in each of them* —
-at 1600 that is 2.5M tags, and per-row allocations double with every doubling
-of the number. Three nested lists cube it. Say it per list instead, keyed the
-way a pin is (a `"Type.field"` coordinate or a bare field name), with
-`default:` for the rest:
-
-```ruby
-config.list_size = { "Row.tags" => 3, default: 1000 }
-```
-
-which holds the inner list at 3 however large the outer one grows — or cap it
-in the query (`tags(first: 3)`), where the query is yours to change.
-
-**Configure at load, or in an `around` — never in a plain `before`.** The tag
-builds this example's clients in a `before` hook of its own, and rspec runs
-that one ahead of yours, so a `before` setting `config.schema`, `config.router`
-or `config.context` arrives after the decision it meant to change. It is
-**refused**, not ignored — a green example running against the wrong stand-in
-is the expensive outcome. `Testing.configure` in the spec helper is the usual
-place; an `around` wraps the tag's setup when one group needs its own:
-
-```ruby
-around do |example|
-  GraphWeaver::Testing.configure { |config| config.schema = Catalog::Schema }
-  example.run
-end
-```
-
-For a single example the helper says it where it varies instead —
-`graphql_in_process(MySchema)`, `graphql_fake(schema: MySchema)`,
-`graphql_router(fake: …)`, `graphql_context(current_user: …)`.
-
-**With more than one graph, `graph:` says which one a helper stands in for** —
-`graphql_fake(graph: :poke, "pokemon_v2_pokemon.name" => "pikachu")`,
-`graphql_in_process(graph: :catalog)`, `graphql_router(graph: :storefront,
-fake: …)`. A helper is the stand-in for one graph's modules, so an app with
-several is refused, naming them, rather than guessing. A schema class names
-its graph and its schema in one word — `graphql_in_process(Reviews::Schema)`
-— but only for a graph that runs that class in-process; a graph whose schema
-is a dump has no such object, and `graph:` is the handle every graph has.
-
-**The rule: a helper sets the stand-in for the graph it names; the tag sets
-the mode for every graph no helper named.** So one example can run two graphs
-in two modes — the federated one through its router, the plain one faked —
-and neither helper disturbs the other's graph:
-
-```ruby
-it "renders the dashboard", graphql: :router do
-  graphql_fake(graph: :countries, "Country.name" => "Canada")
-  # :storefront routes through its supergraph (the tag); :countries is faked
-end
-```
-
-A helper naming one graph of several isn't contradicting the tag, so it isn't
-refused. A helper that speaks for the whole example still is: with one graph,
-or with no `graph:`/schema to narrow it, `graphql: :fake` plus
-`graphql_in_process` is two answers to one question, and the later one winning
-silently would hide which was the mistake.
-
-Anything whose honest answer differs per example belongs on the fake instead
-— `graphql_fake(null_chance: 1.0)` for the example that's about an empty
-state, `graphql_fake(values: :literal)` for the one that reads better without
-faker's prose. A suite-wide `null_chance` would sprinkle nils through every
-*other* example, one run in ten, on a seed the failure doesn't name.
-
-Need the schema itself inside an example — to sample a field, or build a
-query on the fly? The client in play exposes it as
-`GraphWeaver.client.schema`, and `GraphWeaver::Testing.config.schema` reads
-back what `config.schema =` set, falling back to the committed dump.
-
 ## Fabricated data — `graphql: :fake`
 
-`FakeClient` fabricates schema-correct responses for whatever query
-arrives: real enum values, valid `__typename` members, and — for a custom
-scalar — a value the Ruby type you registered it as can hold, so every fake
-casts cleanly through your generated structs. `@skip`/`@include` are
-evaluated against the variables you passed (defaults included), so a field
-the server would leave out is left out. `rspec --seed 1234` reproduces the
-values along with test order.
+`FakeClient` fabricates schema-correct responses for whatever query arrives:
+real enum values, valid `__typename` members, and — for a custom scalar — a
+value the Ruby type you registered it as can hold, so every fake casts cleanly
+through your generated structs. `@skip`/`@include` are evaluated against the
+variables you passed (defaults included), so a field the server would leave out
+is left out. `rspec --seed 1234` reproduces the values along with test order.
 
 ```ruby
-fake = GraphWeaver::Testing::FakeClient.new   # schema: falls back to Testing.config
+it "shows the profile", graphql: :fake do
+  person = PersonQuery.execute!(id: "1").person
 
-person = PersonQuery.execute!(client: fake, id: "1").person
-person.name       # a plausible name, when faker is loaded
-person.birthday   # a real Date
+  person.name       # a plausible name, when faker is loaded
+  person.birthday   # a real Date
+end
 ```
 
-Values are semantic when the [faker](https://github.com/faker-ruby/faker) gem
-is loaded — `name` gets a name, `email` an email — and plain and type-derived
-(`"name-1"`, seeded numbers) when it isn't. Say `values: :literal` on a fake
-that reads better without the prose, or `values: :faker` to insist on the
-semantic ones and get told if the gem is missing:
+Values are semantic when the [faker](https://github.com/faker-ruby/faker) gem is
+loaded — `name` gets a name, `email` an email — and plain and type-derived
+(`"name-1"`, seeded numbers) when it isn't. Say `values: :literal` on a fake that
+reads better without the prose, or `values: :faker` to insist on the semantic
+ones and get told if the gem is missing.
 
-```ruby
-graphql_fake(values: :literal)
-GraphWeaver::Testing::FakeClient.new(values: :literal)
-```
+Outside a tagged example, build one yourself:
+`GraphWeaver::Testing::FakeClient.new` (its `schema:` falls back to
+`Testing.config`), then pass it as `client:`.
 
 ### Pins
 
@@ -275,90 +123,64 @@ graphql_fake("Money" => "12.00",            # every Money field, however deep
 
 Keys are schema vocabulary, so they survive query refactors — a type name, or
 `"Type.field"` (a bare `"field"` pins it on every type) — and they are checked
-and spellchecked: `"Person.nmae"` raises rather than quietly pinning nothing
-and leaving the example green against random data. **Schema vocabulary, not
-Ruby:** a `countries` field generates a `Countries` struct, but the pin is
-`"Country"`, the type name the schema uses — spelled the way *that* schema
-spells it, so a Hasura table type is `"pokemon_v2_pokemon"` and not a
-Ruby-cased guess at it.
+and spellchecked: `"Person.nmae"` raises rather than quietly pinning nothing and
+leaving the example green against random data. **Schema vocabulary, not Ruby:** a
+`countries` field generates a `Countries` struct, but the pin is `"Country"`,
+spelled the way *that* schema spells it, so a Hasura table type is
+`"pokemon_v2_pokemon"` and not a Ruby-cased guess at it.
+
+A pin **merges**, and pins a **subtree** as readily as a leaf: name the fields
+the example is about and everything else in the selection is still fabricated. A
+pinned list is exactly as long as you write it — `{}` means "another one, all
+fabricated".
+
+```ruby
+graphql_fake("Reader.name" => "Ada",
+             "Reader.orders" => [{ "status" => "PAID" }, {}])
+```
+
+Inside a subtree the keys are *response* keys, as they come back on the wire
+(`priceCents`, or an alias you selected); one the query doesn't select is refused
+and spellchecked, same as a typo'd coordinate. At a union or interface, name the
+member with `"__typename"`.
 
 An **object pin** is anything answering the field names — a FactoryBot build, a
 model, a `Struct`, an `OpenStruct`. For each selected field the fake calls the
-snake_cased reader, puts a Ruby value on the wire the way its
+snake_cased reader, puts the value on the wire the way its
 [scalar registration](scalars.md) serializes it (a `Time` as its iso8601 string,
 a `T::Enum` as its value), recurses into nested objects and arrays of them, and
 **fabricates any field the object doesn't answer**. Readers are field names, not
 aliases; `__typename` comes from the key, so at a union or interface pin the
-concrete type (`"Person"`, never `"Named"`). One thing rspec's seed can't reach:
-a FactoryBot sequence advances on its own counter, so an object built from one
-isn't reproduced by `--seed`.
+concrete type (`"Person"`, never `"Named"`). A FactoryBot sequence advances on
+its own counter, which is the one thing `--seed` can't reproduce.
 
 A **scalar type pin** is the one thing a scalar registered as *your own class*
 needs — only `Money.parse` knows what wire value it accepts — so without one
-fabrication refuses at the path it reached (`at reader.orders.0.total`) and
-names the pin to add, rather than feeding your cast a placeholder that fails
-deep inside `from_h`. A scalar registered as `BigDecimal`, `Time`, `Date`,
-`Integer`, `Float`, `String` or `T::Boolean` needs nothing. The key is the
-**schema's scalar name**, not the Ruby class it maps to, so two scalars that
-both deserialize into `Money` want a pin each. Suite-wide, the same hash is
-`config.overrides`, and the [cassette anonymizer](cassettes.md) reads it too.
-
-A pin is **what the wire carries** — `"12.00"`, not `Money.parse("12.00")` —
-but the object is accepted wherever the registration can serialize one, which
-is the same rule an object pin's fields already follow. A `serialize:` **Proc**
-builds source rather than converting a value, so a registration spelled that
-way has nothing to run: pin the wire value there, and the fake says so if you
-don't.
+fabrication refuses at the path it reached (`at reader.orders.0.total`) and names
+the pin to add, rather than feeding your cast a placeholder that fails deep
+inside `from_h`. A scalar registered as `BigDecimal`, `Time`, `Date`, `Integer`,
+`Float`, `String` or `T::Boolean` needs nothing. The key is the **schema's scalar
+name**, not the Ruby class it maps to, so two scalars that both deserialize into
+`Money` want a pin each. What you pin there is **what the wire carries** —
+`"12.00"`, not `Money.parse("12.00")` — though the object is accepted wherever
+the registration can serialize one. (A `serialize:` **Proc** builds source rather
+than converting a value, so a registration spelled that way has nothing to run:
+pin the wire value, and the fake says so if you don't.) Suite-wide, the same hash
+is `config.overrides`, and the [cassette anonymizer](cassettes.md) reads it too.
 
 Pins lead and options follow — `graphql_fake("Money" => "12.00", values:
-:literal)`. Pins and options are the same keywords, told apart by a lookup: a
-key the fake takes is an option, a key **your schema** knows is a pin, and a
-key that is neither is refused naming both. So a lowercase type pins as
-readily as a capitalized one — `graphql_fake("pokemon_v2_pokemon" => …)` for a
-Hasura API. `overrides:` takes the same hash by keyword, and the leading pins
-win where both name a key; written as that leading hash a key is only ever a
-pin, which is the spelling for a schema whose own vocabulary collides with an
-option name. The refusal is the same at every door: `FakeClient.new`,
-`graphql_fake`, `Router.new(fake:)` and `graphql_router(fake:)`.
+:literal)`. They are the same keywords, told apart by a lookup: a key the fake
+takes is an option, a key **your schema** knows is a pin, and a key that is
+neither is refused naming both. `overrides:` takes the same hash by keyword, and
+the leading pins win where both name a key — write it as that leading hash when a
+schema's own vocabulary collides with an option name. The refusal is the same at
+every door: `FakeClient.new`, `graphql_fake`, `Router.new(fake:)` and
+`graphql_router(fake:)`.
 
 **A pin answers every call the same way**, which is how a paging loop fed by a
 fake runs forever — page two is as full as page one.
-`GraphWeaver::Testing::Sequence` chains clients and repeats the last, so an
-empty pin on the second one is what ends the loop:
-
-```ruby
-page  = GraphWeaver::Testing::FakeClient.new(schema:, overrides: { "pokemon_v2_pokemon" => [{ "name" => "pikachu" }] })
-empty = GraphWeaver::Testing::FakeClient.new(schema:, overrides: { "pokemon_v2_pokemon" => [] })
-
-GraphWeaver.client = GraphWeaver::Testing::Sequence.new(page, empty)
-```
-
-It is the same chain a retry test uses — [simulating
-failures](#simulating-failures) has that one.
-
-### The example that's *about* the data
-
-Fabricated data answers "does this render", not "does it render Ada's two
-orders". `graphql_fake` is the tag with options — same client, built where
-the example can say what it needs:
-
-```ruby
-it "shows the two paid orders", graphql: :fake do
-  graphql_fake("Reader.name" => "Ada",
-               "Reader.orders" => [{ "status" => "PAID" }, {}])
-
-  expect(DashboardQuery.execute!.reader.orders.size).to eq 2
-end
-```
-
-An override pins a **subtree** as readily as a leaf, and **merges**: name
-the fields the example is about and everything else in the selection is
-still fabricated. A pinned list is exactly as long as you write it — `{}`
-means "another one, all fabricated". Inside a subtree the keys are
-*response* keys, as they come back on the wire (`priceCents`, or an alias
-you selected); one the query doesn't select is refused and spellchecked,
-same as a typo'd coordinate. At a union or interface, name the member with
-`"__typename"`.
+`GraphWeaver::Testing::Sequence.new(page, empty)` chains clients and repeats the
+last, so a fake whose pin is `[]` on the second one is what ends the loop.
 
 `graphql_fake` returns the client, which records what it was asked:
 
@@ -369,17 +191,16 @@ expect(fake.requests.size).to eq 1                      # memoized
 expect(fake.requests.first[:variables]).to eq({ "id" => "1" })
 ```
 
-It works in a `before` block, an example body, or a shared context — and
-with no tag at all, since it installs the client itself. The tag is
-`graphql_fake` with no options.
-
-One thing to know: **two identical queries fabricate different data**, so
-assert a memoization with `requests.size`, not by comparing two responses.
+It works in a `before` block, an example body, or a shared context — and with no
+tag at all, since it installs the client itself. The tag is `graphql_fake` with
+no options. One thing to know: **two identical queries fabricate different
+data**, so assert a memoization with `requests.size`, not by comparing two
+responses.
 
 ## Real resolvers — `graphql: :in_process`
 
-Your actual resolvers, your actual `context`, in the same process — no
-socket, no serialization, and a resolver's real backtrace when it raises.
+Your actual resolvers, your actual `context`, in the same process — no socket,
+no serialization, and a resolver's real backtrace when it raises.
 
 ```ruby
 it "hides other people's drafts", graphql: :in_process do
@@ -388,73 +209,51 @@ it "hides other people's drafts", graphql: :in_process do
 end
 ```
 
-The live schema *class* is found for you (a schema dump has no resolvers,
-so it won't do). If two loaded classes match, or none does, it says so and
-asks for `config.schema = MySchema` — and in Rails, remember that an
-autoloaded schema isn't loaded until something references it.
+The live schema *class* is found for you (a schema dump has no resolvers, so it
+won't do). If two loaded classes match, or none does, it says so and asks for
+`config.schema = MySchema` — and in Rails, remember that an autoloaded schema
+isn't loaded until something references it.
 
 A federated app has no one live class, so the example says which subgraph it
-means. Testing one subgraph's resolvers directly is a different question from
-`graphql: :router`, which plans across the whole graph and stitches; both are
-worth asking, and a suite asks them of different subgraphs:
-
-```ruby
-it "rejects a review from a blocked reader" do
-  graphql_in_process(Reviews::Schema)
-  …
-end
-```
-
-Like `graphql_fake`, `graphql_in_process` needs no tag, works in a `before`
-block, and is restored after the example.
+means: `graphql_in_process(Reviews::Schema)`. Testing one subgraph's resolvers
+directly is a different question from `graphql: :router`, which plans across the
+whole graph and stitches; both are worth asking, and a suite asks them of
+different subgraphs. Like `graphql_fake`, `graphql_in_process` needs no tag,
+works in a `before` block, and is restored after the example.
 
 ### The context your resolvers see
 
-`graphql_context` is available in every example. It **merges** onto
-`config.context` — the baseline survives unless you override a key — reaches
-every stand-in the example runs through (all your graphs', and the ones
-`:wire` serves behind its endpoints), and is **reset before the next
-example**, so one example running as somebody else can't leak into the one
-after it.
+`graphql_context` is available in every example, and is the *only* way to set a
+context from inside one — `config.context` is the suite baseline, read when an
+example's clients are built, before any `before` hook runs, so setting it there
+is refused rather than silently dropped. It **merges** onto that baseline,
+reaches every stand-in the example runs through (all your graphs', and the ones
+`:wire` serves behind its endpoints), and is **reset before the next example**,
+so one example running as somebody else can't leak into the one after it.
 
-It is also the *only* way to set a context from inside an example.
-`config.context` is the suite baseline, read when an example's clients are
-built — before any `before` hook runs — so setting it there is refused rather
-than silently dropped.
-
-Context is setup, so it usually belongs in a `before` block — a group of
-examples sharing one identity says who they are once:
+Context is setup, so it usually belongs in a `before` block — a group of examples
+sharing one identity says who they are once:
 
 ```ruby
 describe "as the owner", graphql: :in_process do
   before { graphql_context(current_user: alice) }
-
-  it "shows the drafts" do
-    expect(DraftsQuery.execute!.drafts.size).to eq 2
-  end
 end
 ```
 
-The reset runs ahead of any group hook, so each example re-applies that
-`before` from the same baseline rather than stacking onto the last one's
-context. Set it inline for the one-off, or pass a block to scope it for the
-example that needs two identities:
-
-```ruby
-graphql_context(admin: true) { expect(SettingsQuery.execute!.settings).to be_present }
-```
-
-Called with nothing it reads the context back. Under `graphql: :fake` it
-refuses: there are no resolvers to receive a context, and silently ignoring
-one would leave an example asserting on data nothing scoped. Pin the data
-itself instead — `graphql_fake("Person.name" => "Ada")`, above.
+The reset runs ahead of any group hook, so each example re-applies that `before`
+from the same baseline rather than stacking onto the last one's context. Pass a
+block to scope it for the example that needs two identities —
+`graphql_context(admin: true) { … }` — and call it with nothing to read the
+context back. Under `graphql: :fake` it refuses: there are no resolvers to
+receive a context, and silently ignoring one would leave an example asserting on
+data nothing scoped. Pin the data itself instead.
 
 ## A federated graph — `graphql: :router`
 
 Same thing across a federated graph: the tag builds a
-[`Testing::Router`](federation.md#the-local-router), which plans the query
-across your subgraphs and runs it against those **real resolvers** — no
-gateway, no node, no sockets.
+[`Testing::Router`](federation.md#the-local-router), which plans the query across
+your subgraphs and runs it against those **real resolvers** — no gateway, no
+node, no sockets.
 
 ```ruby
 describe "the dashboard", graphql: :router do
@@ -469,19 +268,18 @@ A router is built once per supergraph (parsing one per example would be real
 time) and stands in for that graph's modules; its context is reset from
 `config.context` every time.
 
-`graphql_router` is the tag with options, the way `graphql_fake` is — one
-option, `fake:`, saying how the subgraphs the router
+`graphql_router` is the tag with options, the way `graphql_fake` is — one option,
+`fake:`, saying how the subgraphs the router
 [fakes](federation.md#a-supergraph-only-partly-local) fabricate: the pins and
-options `graphql_fake` takes, in one hash:
+options `graphql_fake` takes, in one hash.
 
 ```ruby
 graphql_router(fake: { "Shipment.carrier" => "UPS", list_size: 2 })
 ```
 
-It names no schema, so with more than one graph it refuses: the tag alone
-already routes each module through its own graph's supergraph, and
-`config.router = { fake: … }` says how the faked subgraphs fabricate for the
-suite.
+It names no schema, so with more than one graph it refuses: the tag alone already
+routes each module through its own graph's supergraph, and `config.router = {
+fake: … }` says how the faked subgraphs fabricate for the suite.
 
 What it plans, what it **refuses** and why, how subgraphs are matched to your
 schema classes, and what to do about a supergraph only partly local:
@@ -505,21 +303,14 @@ a production router
 
 `path` survives; nothing else about the subgraph does — including the
 `extensions.code` your own subgraph set, since it is a subgraph like any other.
-So assert on `path` and on what your app does with the failure, not on a
-message, a code, or the `service` stamp.
-An example that needs the redacted shape gets it from
-[`Failure`](#simulating-failures), which reproduces it exactly:
+So assert on `path` and on what your app does with the failure, not on a message,
+a code, or the `service` stamp. An example that needs the redacted shape gets it
+from [`Failure`](#simulating-failures), which reproduces it exactly:
 
 ```ruby
-it "degrades when shipping is unavailable" do
-  response = ProductQuery.execute(
-    client: GraphWeaver::Testing::Failure.graphql(
-      "Subgraph errors redacted", path: ["product", "shippingEstimate"],
-    ),
-    upc: "p1",
-  )
-  expect(response.errors.first.path).to eq ["product", "shippingEstimate"]
-end
+GraphWeaver::Testing::Failure.graphql(
+  "Subgraph errors redacted", path: ["product", "shippingEstimate"],
+)
 ```
 
 ## Over the wire — `graphql: :wire`
@@ -528,13 +319,8 @@ Your schema, served at the endpoint your own client posts to — with
 **`GraphWeaver.client` left exactly where it is**. So the request really is
 serialized, posted through your middleware, answered at the far end, and read
 back by `from_h` over the server's own bytes. That is the half the other three
-tags skip: they sit *in* the client slot, so the transport your app ships —
-APM tracing, a caller tag, mTLS — never runs.
-
-**It needs [webmock](https://github.com/bblimke/webmock) and
-[rack](https://github.com/rack/rack)** in the Gemfile (`group :test`) — webmock
-hooks Net::HTTP, Faraday and HTTPX underneath, and its `to_rack` builds the Rack
-env with rack.
+tags skip: they sit *in* the client slot, so the transport your app ships — APM
+tracing, a caller tag, mTLS — never runs.
 
 ```ruby
 it "sends the caller tag", graphql: :wire do
@@ -545,21 +331,33 @@ it "sends the caller tag", graphql: :wire do
 end
 ```
 
-What sits behind each endpoint is **what that graph is** — decided the way the
-other tags already decide it, **per graph**, in descending faithfulness: that
+**It needs [webmock](https://github.com/bblimke/webmock) and
+[rack](https://github.com/rack/rack)** in the Gemfile (`group :test`), and
+webmock has to be *enabled* — `require "webmock/rspec"` in the spec helper, in
+either order with `graph_weaver/rspec`. Having it in the Gemfile is not enough:
+`Bundler.require` loads webmock without installing its adapters, so `:wire`
+checks and refuses *before* the first request rather than letting it leave the
+suite. The tag adds one stub per endpoint and takes each back after the example —
+it never disables net connections on your behalf, and never resets stubs it
+didn't make.
+
+**Every endpoint an example can reach is served**, one per graph: the `client`
+each [declared graph](getting_started.md#more-than-one-schema) names, or
+`GraphWeaver.client` for a graph naming none — so a billing module posts to
+billing's url and is answered by billing's schema. What
+sits behind each is **what that graph is**, in descending faithfulness: that
 graph's [router](#a-federated-graph--graphql-router) when it is in a composed
 supergraph, its [live schema class](#real-resolvers--graphql-in_process) when it
-has one, else a [fake](#fabricated-data--graphql-fake) of its schema. So one
-federated graph doesn't put its router behind a plain graph's url, and an app
-that is a pure *client* of someone else's API — a committed dump and no
-resolvers to serve — gets a schema-correct server without writing one. A graph
-with no schema at all is refused, **by `:wire`'s own name**: the one thing the
-other tags can fall back to and this one can't is your client's own schema,
-since reading it means introspecting the endpoint `:wire` has just stubbed.
-Commit a dump, or set `config.schema`.
-
-**It says which, on the logger** — the choice is the one thing this tag makes
-for you, and it is invisible from inside the example. One line per endpoint, at
+has one, else a [fake](#fabricated-data--graphql-fake) of its schema. So an app
+that is a pure *client* of someone else's API gets a schema-correct server
+without writing one. A graph with no schema at all is refused, **by `:wire`'s own
+name** — the one fallback the other tags have and this one can't use is your
+client's own schema, since reading it means introspecting the endpoint `:wire`
+has just stubbed. Commit a dump, or set `config.schema`. A graph whose `client`
+posts nowhere is refused by name too.
+
+**It says which, on the logger** — the choice is the one thing this tag makes for
+you, and it is invisible from inside the example. One line per endpoint, at
 `info` (a Rails app already has a logger; elsewhere set `GraphWeaver.logger`):
 
 ```
@@ -567,50 +365,22 @@ graph_weaver: :wire serving Shop::Schema (in-process) at https://api.example.com
 ```
 
 When a **fake** stands in while the process has a `GraphQL::Schema` class that
-nothing named, that line is a `warn` instead and names the class — the case
-worth catching, because an app that owns real resolvers otherwise goes green
-against fabricated data with nothing said:
+nothing named, that line is a `warn` instead and names the class, telling you to
+set `GraphWeaver::Testing.config.schema` — the case worth catching, because an
+app that owns real resolvers otherwise goes green against fabricated data with
+nothing said. A warning rather than a refusal, because a loaded class isn't proof
+you meant it *here* — a federated suite loads every subgraph's — and a fake
+behind the wire is a thing to want.
 
-```
-graph_weaver: :wire serving a fake at https://api.example.com/graphql — Shop::Schema
-is loaded and nothing named it, so your resolvers did not run. To serve them,
-name it: GraphWeaver::Testing.config.schema = Shop::Schema
-```
-
-A warning rather than a refusal, because a loaded class isn't proof you meant
-it *here* — a federated suite loads every subgraph's — and a fake behind the
-wire is a thing to want. Name the class for the suite, and call `graphql_fake`
-in the examples that want fabricated data.
+**A helper says what goes behind the wire.** Under the other tags a `graphql_*`
+helper takes the client slot; under `:wire` it is served instead — the client
+slot has to keep your own client for the transport to run at all — so
+`graphql_fake("Reader.orders" => [{ "status" => "PAID" }, {}])` reads exactly as
+it does under `:fake`, and the helper returns the client it serves, so
+`fake.requests` is what the *endpoint* was asked.
 
-**A helper says what goes behind the wire.** Under the other tags a
-`graphql_*` helper takes the client slot; under `:wire` it is served instead —
-the client slot has to keep your own client for the transport to run at all —
-so pins read exactly as they do under `:fake`:
-
-```ruby
-it "renders two orders, through our own transport", graphql: :wire do
-  graphql_fake("Reader.orders" => [{ "status" => "PAID" }, {}])
-
-  expect(DashboardQuery.execute!.reader.orders.size).to eq 2
-end
-```
-
-It returns the client it serves, so `fake.requests` is what the *endpoint* was
-asked. `graphql_router(fake: …)` and `graphql_in_process(Reviews::Schema)` say
-the same thing for the other two.
-
-**Every endpoint an example can reach is served**, one per graph: the client
-each [declared graph](getting_started.md#more-than-one-schema) bakes into its
-modules with `client:`, or `GraphWeaver.client` for a graph that bakes none —
-so an app whose graphs all bake one needs no app default at all. Each gets
-that graph's own schema behind it, so a billing module posts to billing's
-url and is answered by billing's schema. A graph whose baked client posts
-nowhere is refused by name, rather than its requests quietly leaving the
-suite.
-
-**Identity comes from the request.** A `context:` **proc** is called per
-request with the headers as sent, which is the seam nothing above the wire can
-test:
+**Identity comes from the request.** A `context:` **proc** is called per request
+with the headers as sent, which is the seam nothing above the wire can test:
 
 ```ruby
 GraphWeaver::Testing.configure do |config|
@@ -621,46 +391,36 @@ end
 A hash still works, and is still the baseline `graphql_context` merges onto; a
 proc replaces it, and `graphql_context` then says so rather than merging onto
 something that isn't there. (Rack drops a header's capitalization, so `X-CALLER`
-arrives as `X-Caller`.)
-
-Like every suite setting, it goes in `Testing.configure` or an `around` —
-[never a plain `before`](#nothing-to-configure), `:wire` least of all, since the
-tag stubs this example's endpoints in a `before` hook of its own.
-
-**And webmock has to be *enabled*** — `require "webmock/rspec"` in the spec
-helper, in either order with `graph_weaver/rspec`. Having it in the Gemfile is
-not enough: `Bundler.require` loads webmock without installing its adapters, so
-`:wire` checks and refuses *before* the first request rather than letting it
-leave the suite. That is what makes this a *transport* test rather than a mock
-of one — every transport [documented here](transports.md) runs unchanged,
-pooling and all. The tag adds one stub per endpoint and takes each back after
-the example — it never disables net connections on your behalf, and never
-resets stubs it didn't make.
+arrives as `X-Caller`.) Like every suite setting, it goes in `Testing.configure`
+or an `around` — [never a plain `before`](#nothing-to-configure), `:wire` least
+of all, since the tag stubs this example's endpoints in a `before` hook of its
+own.
 
 **The wire adds a hop, not a capability.** Behind a router, everything
-[it refuses](federation.md#what-it-refuses) is still refused, before any
-resolver runs. Behind a fake, what you are testing is your *transport* — the
-request your middleware wrote, the headers it sent, the retry it does on a 500,
-and that `from_h` reads real JSON off a socket rather than a Ruby hash you
-handed it. What it can't tell you is whether your `cast:` agrees with the real
-server: the fabricated bytes are written to match your own
-[scalar registrations](scalars.md), so the round trip agrees with itself. Put
-the live schema class behind the wire for that, or pin a real response with a
-[cassette](cassettes.md).
+[it refuses](federation.md#what-it-refuses) is still refused, before any resolver
+runs. Behind a fake, what you are testing is your *transport* — the request your
+middleware wrote, the headers it sent, the retry it does on a 500, and that
+`from_h` reads real JSON off a socket. What it can't tell you is whether your
+`cast:` agrees with the real server: the fabricated bytes are written to match
+your own [scalar registrations](scalars.md), so the round trip agrees with
+itself. Put the live schema class behind the wire for that, or pin a real
+response with a [cassette](cassettes.md).
 
 `GraphWeaver::Testing::Endpoint` is an ordinary Rack app wrapping anything that
-satisfies the [client contract](transports.md) — so mount it yourself if you'd
-rather have a real socket:
-
-```ruby
-run GraphWeaver::Testing::Endpoint.new(router)   # config.ru, or a Puma in a thread
-```
+satisfies the [client contract](transports.md), so mount it yourself
+(`run GraphWeaver::Testing::Endpoint.new(router)`) if you'd rather have a real
+socket. A client answering a `context:` **proc** is served **one request at a
+time** — answering one means setting the client's context for the length of that
+dispatch, so the identity a request asked for is the identity it gets, whatever
+else is in flight. The lock is the client's own, so it holds however the endpoint
+is mounted. A `context:` hash is served **concurrently**: nothing writes it, so
+there is nothing to serialize.
 
 ### Making the served endpoint fail
 
-The tag adds **one stub per endpoint**, and webmock answers with the *last*
-stub declared for a url — so an example that wants the server to misbehave
-declares its own, and it wins for that example:
+The tag adds **one stub per endpoint**, and webmock answers with the *last* stub
+declared for a url — so an example that wants the server to misbehave declares
+its own, and it wins for that example:
 
 ```ruby
 it "surfaces a 503, after the retries it's allowed", graphql: :wire do
@@ -673,33 +433,28 @@ it "surfaces a 503, after the retries it's allowed", graphql: :wire do
   }
 end
 
-it "surfaces a timeout", graphql: :wire do
-  stub_request(:post, "https://api.example.com/graphql").to_timeout
-
-  expect { PlaceOrderMutation.execute!(input:) }.to raise_error(GraphWeaver::TransportError)
-end
+# .to_timeout instead, and the call raises GraphWeaver::TransportError
 ```
 
-`to_timeout` raises what a timeout raises, instantly — it tests what your app
-*does* with one. It does not test that a `read_timeout:` of yours is short
-enough, and neither does sleeping inside `to_return { |req| … }`: webmock stands
-in for the socket, so there is nothing to time out and the call simply takes
-that long and succeeds. A timeout *value* can only be proven against a
-genuinely slow server — the [`Endpoint`](#over-the-wire--graphql-wire) above on
-a real port, or a `TCPServer` that dawdles before it replies.
-
-That is a **served** failure: your transport reads the status and the headers
-off a real response, and your `retries:` budget really spends itself against it
-— including [the one attempt a mutation gets](transports.md#retries). That is
-the half a [`Failure` client](#simulating-failures) can't reach, since those sit
-*in* the client slot and raise above the wire. Use `Failure.server` /
+That is a **served** failure: your transport reads the status and the headers off
+a real response, and your `retries:` budget really spends itself against it —
+including [the one attempt a mutation gets](transports.md#retries). That is the
+half a [`Failure` client](#simulating-failures) can't reach, since those sit *in*
+the client slot and raise above the wire. Use `Failure.server` /
 `Failure.timeout` when the example is about your `rescue`; a stub when it is
 about the transport.
 
+`to_timeout` raises instantly, so it tests what your app *does* with a timeout —
+not that a `read_timeout:` of yours is short enough. Sleeping inside
+`to_return { |req| … }` doesn't either: webmock stands in for the socket, so
+there is nothing to time out and the call simply takes that long and succeeds. A
+timeout *value* can only be proven against a genuinely slow server — the
+`Endpoint` above on a real port, or a `TCPServer` that dawdles before it replies.
+
 ## Simulating failures
 
-Every failure mode is just a client, so error-handling paths are testable
-without a server that misbehaves on cue:
+Every failure mode is just a client, so error-handling paths are testable without
+a server that misbehaves on cue:
 
 ```ruby
 Failure = GraphWeaver::Testing::Failure
@@ -732,11 +487,10 @@ GraphWeaver::Testing::FakeClient.new(schema:, fail_at: "people.2.pets.name")
 ```
 
 `Failure.graphql` is the **whole response** failing — `data` is null unless you
-pass `data:`, which is what makes it a partial one. Shape the error by naming
-its wire fields beside the message (`code:`, `extensions:`, `path:`,
-`locations:` — anything else is refused rather than swallowed), so a rejection
-that follows the [`extensions.input`
-convention](errors.md#what-your-server-can-send) is one call:
+pass `data:`, which is what makes it a partial one. Shape the error by naming its
+wire fields beside the message (`code:`, `extensions:`, `path:`, `locations:` —
+anything else is refused rather than swallowed), so a rejection that follows the
+[`extensions.input` convention](errors.md#what-your-server-can-send) is one call:
 
 ```ruby
 # a plain code, the coarse bucket every server states
@@ -757,31 +511,134 @@ Failure.graphql({ message: "boom", path: ["person"] }, "and again", data: { "per
 
 **A server's own rejection lands in `#errors` unless it marked it.** A
 graphql-ruby `validates:` failure carries no `extensions` at all, so it is an
-ordinary error in `response.errors` — `#input_errors` is empty, because
-"the value was out of range" and "the database is down" are the same bytes.
-Assert on `errors` for that, and reach for `#input_errors` only once your
-server [says the error is about the input](errors.md#when-the-server-rejects-the-input);
-the `Failure.graphql(code:, extensions:)` call above is the shape that says it.
+ordinary error in `response.errors` — `#input_errors` is empty, because "the
+value was out of range" and "the database is down" are the same bytes. Assert on
+`errors` for that, and reach for `#input_errors` only once your server
+[says the error is about the input](errors.md#when-the-server-rejects-the-input).
 
 ## Capture and replay
 
-Cassettes record real API responses and replay them offline, above the
-transport (no HTTP interception):
+`GraphWeaver::Testing.cassette("github", client: live)` returns a client that
+records real API responses and replays them offline, above the transport (no HTTP
+interception). Re-record with `GRAPHWEAVER_RECORD=1`, and set
+`config.anonymize = true` so the response is scrubbed on its way to disk. The
+full workflow guide is **[cassettes](cassettes.md)**.
+
+## Nothing to configure
+
+Each mode works out what to run against **per graph** — with more than one, the
+honest answer varies per module — and **refuses, naming what it looked for,
+rather than guessing**:
+
+- **the schema** is `config.schema` if you set one, else the one that
+  [graph](getting_started.md#more-than-one-schema) names, else the committed dump
+  at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to. A
+  fake reads the scalar registrations of the graph it is answering, so it invents
+  the wire value that graph's generated cast expects. (Pins and `overrides:` stay
+  suite-wide, keyed by scalar name — one `"Money"` override for the run.)
+- **`:in_process`** needs the live schema *class*, since only that has resolvers:
+  the one that graph names, else the one your client already runs in-process,
+  else the loaded class that defines everything the schema declares — the same
+  derive-verify-refuse rule that
+  [maps subgraphs](federation.md#which-schema-serves-which-subgraph).
+- **`:router`** plans against the composed supergraph **that graph** names, else
+  `config.router = { supergraph: … }`, else the committed dump when *that*
+  carries `@join__*` markers, else the dump your own client was built from
+  (`GraphWeaver.new("supergraph.graphql")`) — which for a federated app is
+  usually no config at all. A graph that is in no supergraph is refused **by
+  name**, rather than planned against another graph's. A client's *schema* can't
+  stand in for one — it is the API schema the router serves, with the `@join__*`
+  routing table stripped out — but the file it was read from carries the table.
+  Subgraphs are derived either way.
+
+So configure only to override a derivation, or to tune fabricated values — in the
+same file as the require, since support files load in sorted order and one naming
+`GraphWeaver::Testing` before it dies on `NameError`:
+
+```ruby
+GraphWeaver::Testing.configure do |config|
+  # config.schema = MySchema         # the live class, rather than the dump
+  # config.router = { supergraph: Rails.root.join("supergraph.graphql") }
+  # config.router = { subgraphs: { "reviews" => :fake } }   # either key alone
+  # config.context = { tenant: }     # baseline context every example starts from
+  # config.default_mode = :fake      # what an UNtagged example runs against;
+  #                                  # :live (the default) leaves your client
+  #                                  # alone, and graphql: :live opts one out
+  # config.seed = 4242               # defaults to rspec's own --seed
+  # config.overrides = { "Money" => "12.00", "Person.name" => "Daniel" }
+  # config.list_size = 1..3
+end
+```
+
+**The rule: a helper sets the stand-in for the graph it names; the tag sets the
+mode for every graph no helper named.** `graphql_fake`, `graphql_in_process` and
+`graphql_router` stand in for the modules of the graph their schema names — your
+only graph when they name none — and with more than one, `graph:` says which:
+`graphql_fake(graph: :poke, "pokemon_v2_pokemon.name" => "pikachu")`. A schema
+class names its graph and its schema in one word
+(`graphql_in_process(Reviews::Schema)`), but only for a graph that runs that
+class in-process; `graph:` is the handle every graph has. Naming none they could
+reach is refused, naming your graphs.
+
+So one example can run two graphs in two modes — the federated one through its
+router, the plain one faked — and neither helper disturbs the other's graph:
 
 ```ruby
-# records against the live client when the file is missing, replays after
-client = GraphWeaver::Testing.cassette("github", client: live)
+it "renders the dashboard", graphql: :router do
+  graphql_fake(graph: :countries, "Country.name" => "Canada")
+  # :storefront routes through its supergraph (the tag); :countries is faked
+end
 ```
 
-Re-record with `GRAPHWEAVER_RECORD=1`, and set `config.anonymize = true` so the
-response is scrubbed on its way to disk — the query and its variables are the
-replay key and are recorded verbatim, so read a cassette before committing it.
-The full workflow guide is **[cassettes](cassettes.md)**.
+A helper that speaks for the whole example *is* refused, though: with one graph,
+or with no `graph:`/schema to narrow it, `graphql: :fake` plus
+`graphql_in_process` is two answers to one question, and the later one winning
+silently would hide which was the mistake.
+
+Anything whose honest answer differs per example belongs on the fake instead —
+`graphql_fake(null_chance: 1.0)` for the example that's about an empty state,
+`graphql_fake(values: :literal)` for the one that reads better without faker's
+prose. A suite-wide `null_chance` would sprinkle nils through every *other*
+example, one run in ten, on a seed the failure doesn't name.
+
+**Configure at load, or in an `around` — never in a plain `before`.** The tag
+builds this example's clients in a `before` hook of its own, and rspec runs that
+one ahead of yours, so a `before` setting `config.schema`, `config.router` or
+`config.context` arrives after the decision it meant to change. It is
+**refused**, not ignored — a green example running against the wrong stand-in is
+the expensive outcome.
+
+### Fabricated list lengths
+
+`list_size` is how long an **unbounded** list is — an Integer exactly that many,
+a Range randomized within it, or a Hash saying it per list. A list with a
+`first:`/`last:`/`limit:` argument is that long instead, whatever this says.
+
+**Every list the fabricator reaches reads the same setting, so nested lists
+multiply.** A query selecting `rows { owner { … } tags }` with `tags` uncapped
+fabricates `list_size` rows and `list_size` tags *in each of them* — at 1600 that
+is 2.5M tags, and three nested lists cube it. Say it per list instead, keyed the
+way a pin is (a `"Type.field"` coordinate or a bare field name), with `default:`
+for the rest — `config.list_size = { "Row.tags" => 3, default: 1000 }` holds the
+inner list at 3 however large the outer one grows. Or cap it in the query
+(`tags(first: 3)`), where the query is yours to change.
+
+**A list field whose name ends in `errors` fabricates empty** — `userErrors`,
+`errors`, `mutationErrors`. The Relay/Shopify payload
+(`placeOrder { order userErrors }`) is the ecosystem's mutation shape, and a
+fabricated order beside a fabricated failure is a response no server can send;
+[pin it](#pins) to write the failure path
+(`{ "userErrors" => [{ "message" => "Out of stock" }] }`).
+
+Need the schema itself inside an example — to sample a field, or build a query on
+the fly? The client in play exposes it as `GraphWeaver.client.schema`, and
+`GraphWeaver::Testing.config.schema` reads back what `config.schema =` set,
+falling back to the committed dump.
 
 ## Test-only generated modules
 
-They don't have to live in `app/` — `generated_paths` is an appendable list,
-so a support file can register a spec-local set:
+They don't have to live in `app/` — `generated_paths` is an appendable list, so a
+support file can register a spec-local set:
 
 ```ruby
 # spec/support/graph_weaver.rb
@@ -793,5 +650,5 @@ Both lines matter. In Rails the Railtie loads generated modules during boot,
 which is finished before `spec/support/*.rb` runs — so a path appended here is
 never loaded unless you load it. And keep the directory *outside*
 `spec/support/`: rspec-rails requires every `spec/support/**/*.rb` itself, in
-sorted order, so a generated module gets required before the shared `types.rb`
-it needs and dies on `LoadError`.
+sorted order, so a generated module gets required before the shared `types.rb` it
+needs and dies on `LoadError`.