graph_weaver 0.6.1 → 0.7.0

data/docs/testing.md

@@ -1,20 +1,19 @@
 # Testing
 
 How to run a spec that executes a GraphQL query without a server — against
-fabricated data, against your own resolvers, or across a federated graph. Read
-this once when you set the suite up; after that the one thing to remember is
-the `graphql:` tag.
+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:
 
 ```ruby
+# spec/support/graph_weaver.rb — or rails_helper.rb itself
 require "graph_weaver/rspec"
 ```
 
-(In Rails, put it **above** the `spec/support` glob in `rails_helper.rb` —
-rspec-rails requires those partway through, and a support file mentioning
-`GraphWeaver::Testing` before this line dies on `NameError`.)
-
 Then **one tag says what an example runs against** — on the example, or on
 the group it belongs to, since rspec metadata inherits:
 
@@ -25,6 +24,7 @@ end
 
 it "renders the empty state", graphql: :fake do … end
 it "authorizes drafts",       graphql: :in_process do … end
+it "sends the caller tag",    graphql: :wire do … end
 ```
 
 | mode | reach for it when | what it costs |
@@ -32,30 +32,54 @@ it "authorizes drafts",       graphql: :in_process do … end
 | [`:fake`](#fabricated-data--graphql-fake) | most unit tests — you need *a* well-shaped response | no resolver code runs |
 | [`:in_process`](#real-resolvers--graphql-in_process) | the point of the test is that your resolver logic works | slower; needs a live schema class |
 | [`:router`](#a-federated-graph--graphql-router) | the same, across a federated graph | needs a composed supergraph; [refuses](federation.md#what-it-refuses) shapes it can't plan faithfully |
+| [`:wire`](#over-the-wire--graphql-wire) | the test is about your own transport — headers, middleware, deserialization | needs webmock and rack, and an http client |
+| `: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 its client as `GraphWeaver.client` for that example, so
-generated modules run against it with zero per-test setup. (Generate them
-*without* a baked `client:` — a module that has one never consults
-`GraphWeaver.client`.) `rspec --tag graphql:router` runs one mode's
-examples; an untagged example is left alone unless you set
-`config.default_mode`, and **`graphql: false` opts one back out** of that
-default.
+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.
+
+**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, untagged or opted out, and whatever the example did to
-it. So building your own client is a plain assignment, cleaned up like a
+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 assignment wins: the tag installs its client from a
-suite-level `before`, which rspec runs ahead of any group hook. So a tagged
-example with a `before` of its own runs against the client the `before`
-built — tag the group for the mode, override the one example that needs
-something else.
+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.
 
 Everything here is a *client* — the one interface queries run through (the
 contract is in [transports](transports.md)). Fakes, the router, failures and
@@ -71,29 +95,50 @@ DashboardQuery = router.parse("query Dashboard { me { username } }")
 DashboardQuery.execute!.me.username
 ```
 
-All three modes, tagged and running end to end, are
-[`spec/rspec_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/rspec_spec.rb) — the reference for anything
-this page leaves out.
+Every mode, tagged and running end to end, is
+[`spec/rspec_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/rspec_spec.rb) (and
+[`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, and **refuses — naming what it
-looked for — rather than guessing**:
-
-- **the schema** is `config.schema` if you set one, else the committed dump
-  at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to.
+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 your client already runs in-process, else the loaded
-  class that defines everything the schema declares — the same
-  derive-verify-refuse rule that
+  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. If your committed dump
-  *is* one (it carries `@join__*` markers), that's it — no config at all. A
-  client can't stand in for it: a client's schema is the API schema the router
-  serves, with the `@join__*` routing table stripped out, so the supergraph has
-  to be named. Subgraphs are derived either way.
+- **`: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:
 
-So configure only to override a derivation, or to tune fabricated values:
+```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|
@@ -101,14 +146,81 @@ GraphWeaver::Testing.configure do |config|
   # 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
-  #                                  # (graphql: false opts one back out)
+  # 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
@@ -164,7 +276,11 @@ 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.
+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.
 
 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
@@ -182,16 +298,43 @@ 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. Suite-wide, the same hash is
+`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.
+
 Pins lead and options follow — `graphql_fake("Money" => "12.00", values:
-:literal)`. Options are lowercase words, so a key with a dot or a leading
-capital is a pin wherever it is written; `overrides:` takes the same hash by
-keyword, and the leading pins win where both name a key. A fake refuses an
-option it doesn't take, lists the ones it does, and guesses at what you meant —
-at every door: `FakeClient.new`, `graphql_fake`, `Router.new(fake:)` and
-`graphql_router(fake:)`.
+: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:)`.
+
+**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
 
@@ -268,10 +411,16 @@ 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 — and is
-**reset before the next example**, so one example running as somebody else
-can't leak into the one after it. (Use it rather than the
-`graphql_in_process(context:)` baseline, which is per-suite.)
+`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.
+
+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:
@@ -316,9 +465,9 @@ describe "the dashboard", graphql: :router do
 end
 ```
 
-The router is built once for the suite (parsing a supergraph per example
-would be real time) and installed as `GraphWeaver.client` for each; its
-context is reset from `config.context` every time.
+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
@@ -329,10 +478,224 @@ options `graphql_fake` takes, in one hash:
 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.
+
 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:
 **[federation → the local router](federation.md#the-local-router)**.
 
+### Production redacts what this router hands you
+
+A subgraph's error reaches you here in full — its message, and
+`extensions: {"service" => "<subgraph>"}` saying which subgraph produced it. So
+does a dev router configured with `include_subgraph_errors.all: true`. A
+production Apollo Router, with that setting **omitted** — the default — replaces
+the message and empties the extensions:
+
+```
+here, and a dev router
+  {"message" => "carrier unavailable for this weight",
+   "path" => ["product", "shippingEstimate"], "extensions" => {"service" => "reviews"}}
+a production router
+  {"message" => "Subgraph errors redacted", "path" => ["product", "shippingEstimate"]}
+```
+
+`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:
+
+```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
+```
+
+## Over the wire — `graphql: :wire`
+
+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.
+
+```ruby
+it "sends the caller tag", graphql: :wire do
+  DashboardQuery.execute!
+
+  expect(WebMock).to have_requested(:post, "https://api.example.com/graphql")
+    .with(headers: { "X-Caller" => "web" })
+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
+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
+`info` (a Rails app already has a logger; elsewhere set `GraphWeaver.logger`):
+
+```
+graph_weaver: :wire serving Shop::Schema (in-process) at https://api.example.com/graphql
+```
+
+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:
+
+```
+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 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:
+
+```ruby
+GraphWeaver::Testing.configure do |config|
+  config.context = ->(headers) { { current_user: User.find_by(token: headers["Authorization"]) } }
+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.
+
+**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).
+
+`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
+```
+
+### 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:
+
+```ruby
+it "surfaces a 503, after the retries it's allowed", graphql: :wire do
+  stub_request(:post, "https://api.example.com/graphql")
+    .to_return(status: 503, headers: { "Retry-After" => "0" }, body: "down for maintenance")
+
+  expect { PlaceOrderMutation.execute!(input:) }.to raise_error(GraphWeaver::ServerError) { |e|
+    expect(e.status).to eq 503
+    expect(e.retry_after).to eq 0    # the header your backoff read
+  }
+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` 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` /
+`Failure.timeout` when the example is about your `rescue`; a stub when it is
+about the transport.
+
 ## Simulating failures
 
 Every failure mode is just a client, so error-handling paths are testable
@@ -342,10 +705,11 @@ without a server that misbehaves on cue:
 Failure = GraphWeaver::Testing::Failure
 
 PersonQuery.execute(client: Failure.transport, id: "1")            # raises TransportError
+PersonQuery.execute(client: Failure.timeout, id: "1")               # raises TransportError, cause Net::ReadTimeout
 PersonQuery.execute(client: Failure.server(status: 502), id: "1")  # raises ServerError
 PersonQuery.execute(client: Failure.throttled, id: "1")            # errors.first.code => "THROTTLED"
 PersonQuery.execute(client: Failure.stale_schema, id: "1")         # schema_stale? => true
-PersonQuery.execute(client: Failure.graphql("boom"), id: "1")      # partial failure
+PersonQuery.execute(client: Failure.graphql("boom"), id: "1")      # errors, and no data
 
 # a throttling server, with the header a backoff reads
 PersonQuery.execute(client: Failure.server(status: 429, headers: { "retry-after" => "2" }), id: "1")
@@ -356,14 +720,49 @@ fake = GraphWeaver::Testing::FakeClient.new(schema:)
 GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
 
 # type mismatch: corrupt: derives a wrong-typed wire value for the field —
-# casting raises GraphWeaver::TypeError (overrides remain the manual escape hatch)
+# casting raises GraphWeaver::CastError (overrides remain the manual escape hatch)
 GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")
 
 # field-level partial failure with real GraphQL null propagation: the error
-# lands with its concrete path and nulls bubble to the nearest nullable spot
+# lands with its concrete path and nulls bubble to the nearest nullable spot.
+# The path is response keys joined by dots, and a list index is a segment of
+# its own — state only the indices you mean, the rest match any position
 GraphWeaver::Testing::FakeClient.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
+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:
+
+```ruby
+# a plain code, the coarse bucket every server states
+Failure.graphql("that input was bad", code: "BAD_USER_INPUT")
+
+# the convention: response.input_errors reads this back as one InputError,
+# kind :out_of_range, details { min: 1 }, on path ["input", "min"]
+Failure.graphql(
+  "min must be at least 1",
+  code: "BAD_USER_INPUT",
+  extensions: { "input" => { "kind" => "out_of_range", "path" => ["input", "min"],
+                             "coordinate" => "RangeInput.min", "value" => 0, "min" => 1 } },
+)
+
+# several errors, and partial data: each carries its own hash
+Failure.graphql({ message: "boom", path: ["person"] }, "and again", data: { "person" => nil })
 ```
 
+**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.
+
 ## Capture and replay
 
 Cassettes record real API responses and replay them offline, above the