# 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.