first commit

docs/api-stack/api/api-graphql-yoga/src/testing/testing.md

@@ -0,0 +1,64 @@
+# `testing.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Binds the abstract `runGraphqlEngineConformance` from
+`@suaveplan/api-graphql/testing` to the Yoga engine factory so concrete
+host tests can call a single helper instead of wiring the factory by
+hand. The same conformance suite passes against every concrete engine —
+this binding is the only Yoga-specific piece — so swapping engines stays
+host-config-only.
+
+The barrel also re-exports the abstract harness types
+(`ConformanceContext`, `RunConformanceOptions`) and the harness itself so
+callers that need to compose a non-Yoga binding alongside the Yoga one
+can do so without a second package import.
+
+## Features
+
+- `runYogaConformance(label?, config?)` — single-call wrapper that
+  spins up a fresh Yoga engine per scenario.
+- Re-exports the abstract harness for composition.
+- Returns `void` because the harness registers `describe` / `it` blocks
+  against the active runner — call it inside a parent `describe`.
+
+## Usage: Basic
+
+```ts
+import { describe } from "@suaveplan/testing/runner";
+import { runYogaConformance } from "@suaveplan/api-graphql-yoga/testing";
+
+describe("yoga engine", () => {
+    runYogaConformance();
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { describe } from "@suaveplan/testing/runner";
+import { runYogaConformance } from "@suaveplan/api-graphql-yoga/testing";
+
+describe("yoga engine (strict-namespace)", () => {
+    runYogaConformance("yoga-strict", {
+        options: { strictNamespace: true, maxQueryDepth: 6 },
+    });
+});
+```
+
+## API Reference
+
+- `runYogaConformance(label?, config?)` — bound harness invocation.
+- `runGraphqlEngineConformance` — re-exported abstract harness.
+- `ConformanceContext`, `RunConformanceOptions` — types.
+
+## Implementation Notes
+
+The stub `RequestContext` is empty — the abstract suite intentionally
+never reads from it. Concrete tests that need to assert on
+context-flowing behaviour should write their own scenarios outside the
+conformance harness.