first commit

docs/identity/auth/better-auth-surrealdb/src/testing/run-adapter-conformance.md

@@ -0,0 +1,86 @@
+# testing/run-adapter-conformance
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Exposes `runAdapterConformance(factory)` — the reusable suite that pins
+every Better-Auth Adapter scenario this package implements against a real
+SurrealDB testcontainer. Downstream test files (and consumers of the
+package who maintain their own adapter implementations) import this
+harness once and get an exhaustive contract sweep without rewriting per-
+scenario boilerplate.
+
+## Features
+
+- Single `describe("Better-Auth adapter conformance")` block exercising
+  create, findOne, findMany (with limit/offset/sortBy), update,
+  updateMany, count, delete, deleteMany, and `consumeOne`.
+- Validates link-field roundtrips on `session.userId` (`record<user>`).
+- Validates `applyBetterAuthSchema` succeeds against the live container.
+- Factory injection: callers supply `{ adapter, client }` so the harness
+  can hit both surfaces without re-importing module-private state.
+- Every `it()` carries `{ timeout: 60000 }` to absorb container startup +
+  network jitter typical of dockerised SurrealDB.
+
+## Usage: Basic
+
+```ts
+import { runAdapterConformance } from "@suaveplan/better-auth-surrealdb/testing";
+
+runAdapterConformance(async () => {
+    // Caller is responsible for starting the testcontainer, applying the
+    // schema, and constructing the adapter.
+    const { adapter, client } = await bootstrapTestEnv();
+    return { adapter, client };
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { SurrealDBFixture } from "@suaveplan/testing-integration-surrealdb";
+import { SurrealAdapter } from "@suaveplan/surrealdb";
+import { applyBetterAuthSchema } from "@suaveplan/better-auth-surrealdb/schema";
+import { createBetterAuthSurrealAdapter } from "@suaveplan/better-auth-surrealdb/adapter";
+import { runAdapterConformance } from "@suaveplan/better-auth-surrealdb/testing";
+
+const fixture = new SurrealDBFixture();
+let cfg: Awaited<ReturnType<typeof fixture.start>>;
+let client: SurrealAdapter;
+
+beforeAll(async () => {
+    cfg = await fixture.start();
+    client = new SurrealAdapter(cfg);
+    await client.connect();
+    await applyBetterAuthSchema(client);
+});
+
+afterAll(async () => {
+    await client.disconnect();
+    await fixture.stop();
+});
+
+runAdapterConformance(() => ({
+    client,
+    adapter: createBetterAuthSurrealAdapter({ client }),
+}));
+```
+
+## API Reference
+
+- `runAdapterConformance(factory: ConformanceFactory): void`
+- `ConformanceFactory = () => Promise<ConformanceContext> | ConformanceContext`
+- `ConformanceContext = { adapter: BetterAuthSurrealAdapter; client: SurrealClientView }`
+
+## Implementation Notes
+
+The harness uses the runner-agnostic `@suaveplan/testing/runner` exports
+so it works under both Vitest and Bun's `bun:test`. The factory is
+invoked inside each `it()` so callers may choose either to share one
+adapter across tests (return the same `ctx` reference) or to construct a
+fresh adapter per scenario. Tests use stable `id` values prefixed
+`u_conf_*` / `s_conf_*` to avoid cross-suite collisions when multiple
+harness invocations share a database.