first commit

docs/api-stack/api/api-graphql-apollo/src/testing/conformance.md

@@ -0,0 +1,62 @@
+# `testing/conformance` — Apollo-bound conformance harness
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`testing/conformance` is the re-export of `runGraphqlEngineConformance`
+from `@suaveplan/api-graphql/testing`, pre-bound to the Apollo factory.
+Consumers call `runApolloConformance()` and the harness exercises the
+abstract `GraphqlEngine` contract against the concrete Apollo adapter.
+Both `api-graphql-apollo` and `api-graphql-yoga` MUST pass the same
+invariants — operator behaviour is engine-agnostic at the contract
+boundary.
+
+The module also re-exports the unmodified `runGraphqlEngineConformance`
+so downstream packages that want to run the harness against a
+*different* factory (e.g. a federated subgraph composing Apollo + a
+custom transport) keep a single import surface.
+
+## Features
+
+- One-line invocation — `runApolloConformance()` runs every scenario.
+- Pre-bound factory — callers do not need to know Apollo's
+  construction args.
+- Labelled — the second-positional `label` parameter shows up in
+  test output so split CI logs are unambiguous.
+- Re-exports `runGraphqlEngineConformance` for advanced callers.
+
+## Usage: Basic
+
+```ts
+import { runApolloConformance } from "@suaveplan/api-graphql-apollo/testing";
+
+runApolloConformance();
+```
+
+## Usage: Advanced
+
+Run the conformance suite under a custom label so two adapter variants
+appear distinctly in CI output:
+
+```ts
+import { runApolloConformance } from "@suaveplan/api-graphql-apollo/testing";
+
+runApolloConformance("apollo (persisted-queries)");
+runApolloConformance("apollo (no-persisted-queries)");
+```
+
+## API Reference
+
+- `runApolloConformance(label?: string): void`.
+- `runGraphqlEngineConformance(opts): void` — unchanged re-export.
+
+## Implementation Notes
+
+The Apollo-bound factory yields a fresh engine per scenario so each
+invariant exercises a clean lifecycle. The `makeRequestContext` slot
+is the cast `{} as RequestContext` — sufficient for the abstract
+contract because the harness never touches context fields beyond
+hand-off. Tests that need a richer context construct one explicitly.