# conformance-suite

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Provides `runConformanceSuite`, a driver-agnostic test factory that accepts a `DriverFactory` callback and executes a standard suite of CRUD, transaction, and rollback assertions against any SQLite driver. Running the same suite against both the Bun driver and a WASM driver ensures that both runtimes satisfy the same behavioural contract, catching driver-specific regressions before they reach production.

The suite is intentionally minimal — it tests the lowest-level SQL operations that the adapter layer depends on. Higher-level tests (prepared-statement cache behaviour, migration runner idempotency, OTel counter increments) live in their respective unit test files.

## Features

- `runConformanceSuite(name, factory)` — registers a Vitest `describe` block named `${name} conformance`
- Tests: table creation, SELECT, INSERT with parameters, transaction commit, transaction rollback, UPDATE, DELETE
- `DriverFactory` interface — a single `create()` method returning `{ sqlite, close }`
- Runs under the Bun driver via `bun-conformance.test.ts`

## Usage: Basic Example

```ts
import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";
import { createBunDriver } from "@suaveplan/db-sqlite/drivers/bun-driver";

runConformanceSuite("Bun driver", {
  async create() {
    return createBunDriver({ filename: ":memory:" });
  },
});
```

## Usage: Advanced Example

```ts
import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";

// Custom driver shim for testing
runConformanceSuite("Custom driver", {
  async create() {
    const driver = await MyCustomDriver.open(":memory:");
    return { sqlite: driver.raw, close: async () => driver.close() };
  },
});
```

## API Reference

### `DriverFactory`

```ts
interface DriverFactory {
  create(): Promise<{ sqlite: any; close: () => Promise<void> }>;
}
```

### `runConformanceSuite(name: string, factory: DriverFactory): void`

Registers a Vitest `describe` block with 5 test cases covering the core SQLite contract.

## Implementation Notes

The conformance suite uses raw `sqlite.run()` / `sqlite.query().all()` calls rather than going through `SqliteAdapter` or Drizzle. This keeps the suite focused on driver-level semantics rather than adapter-layer concerns, making it useful for validating new driver implementations independently of the adapter code.

Each test creates fresh tables with unique names to avoid interference between tests within the same suite run.