Initial Commit

packages/api-stack/api/api-auth-better-auth/src/testing/testing.md

@@ -0,0 +1,90 @@
+# `testing`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`@suaveplan/api-auth-better-auth/testing` is the subpath downstream packages
+import when they want to assert their own wiring layer still meets the
+abstract `auth.session` and `auth.provider` contracts on top of this
+adapter. It re-exports both conformance harnesses
+(`runAuthSessionConformance` from `@suaveplan/api-auth` and
+`runAuthProviderConformance` from `@suaveplan/api-auth-provider`) alongside
+the two Better-Auth factories from this package, so a single import gets
+the consumer everything they need.
+
+## Features
+
+- Re-exports `runAuthSessionConformance` + `runAuthProviderConformance` from
+  the contract packages so consumers don't have to add those packages to
+  their own dependency closure.
+- Re-exports `createBetterAuthSession` + `createBetterAuthProvider`
+  so the conformance call sites can drop the factory inline.
+- `AuthSessionConformanceFactory` / `AuthProviderConformanceFactory` /
+  `AuthProviderConformanceOptions` type aliases for explicit typing.
+
+## Usage: Basic
+
+```ts
+import {
+    createBetterAuthProvider,
+    runAuthProviderConformance,
+} from "@suaveplan/api-auth-better-auth/testing";
+
+const results = runAuthProviderConformance({
+    label: "my-host's Better-Auth wiring",
+    factory: () => createBetterAuthProvider(myOptions),
+});
+for (const scenario of results) {
+    it(`${scenario.category} :: ${scenario.name}`, () => {
+        expect(scenario.passed).toBe(true);
+    });
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    createBetterAuthSession,
+    runAuthSessionConformance,
+    type AuthSessionConformanceFactory,
+} from "@suaveplan/api-auth-better-auth/testing";
+
+const spec: AuthSessionConformanceFactory = {
+    label: "Postgres-backed Better-Auth + my custom mapping",
+    factory: () => createBetterAuthSession(myOptionsWithCustomMapping),
+    seedNull: () => new Request("https://api.example.com/anon"),
+    seedPrincipal: () => ({
+        request: new Request("https://api.example.com/me", {
+            headers: { cookie: "better-auth.session=valid" },
+        }),
+        expected: knownPrincipal,
+    }),
+};
+runAuthSessionConformance(spec);
+```
+
+## API Reference
+
+| Export | Source | Purpose |
+| ------ | ------ | ------- |
+| `runAuthSessionConformance` | `@suaveplan/api-auth` | Session contract harness |
+| `runAuthProviderConformance` | `@suaveplan/api-auth-provider` | Provider contract harness |
+| `createBetterAuthSession` | this package | Session factory under test |
+| `createBetterAuthProvider` | this package | Provider factory under test |
+| `AuthSessionConformanceFactory` | type | Spec passed to session harness |
+| `AuthProviderConformanceFactory` | type | Factory signature for provider harness |
+| `AuthProviderConformanceOptions` | type | Options for provider harness |
+
+## Implementation Notes
+
+The subpath is intentionally light — most of the value is just having one
+import path consumers can pull from. The conformance harnesses themselves
+live in the contract packages because that's where the abstract invariants
+are authored; this package's contribution to "passing conformance" is the
+factory pair. Consumers test their own wiring layer (custom middleware,
+host configuration, plugin order) by invoking the harnesses with their
+own options bag and asserting every `ConformanceScenarioResult.passed`.