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